Difference between revisions of "TES5Edit Scripting Functions"

From the CreationKit Wiki
Jump to navigation Jump to search
imported>DavidJCobb
(→‎Pascal implementation: correction: JvInterpreter!Delphi's handling of global variables is just atrocious in every way, and Delphi itself isn't any help)
 
(24 intermediate revisions by 5 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>ProgramPath</b> || String || Provides the file path to Tes5edit's installation folder as a String ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>ScriptsPath</b> || 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.)
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>FileCount</b> || 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.
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>wbAppName</b> || String || Returns 'TES5','TES4','FNV','FO3'||
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>wbVersionNumber</b> || Integer || Returns xEdit version number.||
|}


=== TES5Edit Scripting Functions ===
* [[TES5Edit|TES5Edit]]
xEdit scripts only have access to a generic type called ''IInterface'', which wraps around every object that xEdit returns. However, different types are used internally to classify different objects. To illustrate this with an example: files are coded as ''IwbFile'' objects, while forms are coded as ''IwbMainRecord'' objects. However, an xEdit script will only ever see IInterface objects, and any IInterface can be a IwbFile ''or'' an IwbMainRecord. Functions like ''GetIsESM'' can be called on any IInterface, but are designed to work with IwbFiles and will not produce a meaningful result for other types (i.e. ''GetIsESM'' would always return false for any other type).
* [[TES5Edit_Cleaning_Guide_-_TES5Edit|TES5Edit Cleaning Guide]]
 
* [[TES5Edit_Mod_Cleaning_Tutorial|TES5Edit Mod Cleaning Tutorial]]
The functions below are sorted by the internal types that they operate on. This is to make it easier to find certain functions and to make this page easier to maintain (because frankly, fixing up row colors on a massive table is just a big disincentive to even editing the page).
* [[Fixing_Navmesh_Deletion_Tutorial|Fixing Navmesh Deletion Tutorial]]
 
* [[Skyrim_Dirty_Plugins_List|Skyrim Dirty Plugins List]]
The relationships between internal types are as follows:
* [[TES5Edit_Scripting_Functions|TES5Edit Scripting Functions]]
 
* [https://bethesda.net/community/topic/57570/relz-sseedit/ Official Elderscrolls TES5Edit forum topic] (offline)
    [[#IwbElement|IwbElement]]
    └ IwbContainerBase
      ├ [[#IwbContainer|IwbContainer]]
      │ ├ IwbDataContainer
      │ │  ├ IwbFileHeader
      │ │  └ IwbRecord
      │ │    ├ [[#IwbGroupRecord|IwbGroupRecord]]
      │ │    ├ [[#IwbMainRecord|IwbMainRecord]]
      │ │    └ [[#IwbSubRecord|IwbSubRecord]]
      │ │
      │ └ [[#IwbFile|IwbFile]]
      │
      └ IwbContainerElementRef
   
    [[#IwbResource|IwbResource]]
    IwbResourceContainer
    │ IwbBA2File
    │ IwbBSAFile
    └ IwbFolder
   
    [[#Misc functions|Misc functions]]
    └ [[#DDS functions|DDS]]
    └ [[#NIF functions|NIF]]
 
==== Global functions ====
These functions can be called on anything and should return a meaningful result.
 
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
|- align="left"
! scope="col" style="background-color: #DDDDDD" | Function
! scope="col" style="background-color: #DDDDDD" | Returns
! scope="col" style="background-color: #DDDDDD" | Arguments
! scope="col" style="background-color: #DDDDDD" | Description
{{TES5Edit function row|even
  |Assigned|boolean|aeElement: IwbElement
  |An extension to Delphi's native [http://www.delphibasics.co.uk/RTL.asp?Name{{=}}Assigned Assigned] function: returns true if ''aeElement'' is not ''Nil'', and returns false otherwise.}}
{{TES5Edit function row|odd
  |ObjectToElement|IInterface|akObject
  |If you have stored an IInterface inside of a TList or TStringList, you must call this function when retrieving the object from the list, i.e. <code>ObjectToElement(myList.Items[0])</code>.}}
{{TES5Edit function row|even
  |FileByIndex|IwbFile|aiFile: integer
  |See also: ''FileCount''.}}
{{TES5Edit function row|odd
  |FullPathToFilename|string|asFilename: string
  |Returns the full path to the filename ''asFilename''.}}
{{TES5Edit function row|even
  |EnableSkyrimSaveFormat||
  |As of xEdit 3.1.2, calling this function will corrupt saved plugins until xEdit is restarted.}}
{{TES5Edit function row|odd
  |GetRecordDefNames||akList: TStrings
  |Unverified: Modifies ''akList'' by adding entries based on the contents of the global ''wbRecordDefs''.}}
{{TES5Edit function row|even
  |wbFilterStrings||akListIn: TStrings;<br/> akListOut: TStrings;<br/> asFilter: String
  |Modifies ''akListOut'', adding every entry in ''akListIn'' that contains the substring ''asFilter''.}}
{{TES5Edit function row|odd
  |wbRemoveDuplicateStrings||akList: TStringList
  |Modifies ''akList'', removing any duplicate entries that it contains.}}
|}
 
==== IwbElement ====
These functions can be called on any IwbElement IInterface.
 
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
|- align="left"
! scope="col" style="background-color: #DDDDDD" | Function
! scope="col" style="background-color: #DDDDDD" | Returns
! scope="col" style="background-color: #DDDDDD" | Arguments
! scope="col" style="background-color: #DDDDDD" | Description
{{TES5Edit function row|even
  |BaseName|string|aeElement: IwbElement
  |Identical to ''Name'' except that it handles IwbFiles differently. ''Name'' will prepend a load order index (i.e. <code>[02] PluginName.esp</code>), while ''BaseName'' will not.}}
{{TES5Edit function row|odd
  |BuildRef||aeElement: IwbElement
  |Builds reference information for the element and all of its descendants. Note that this function will run even if reference information has already been built.}}
{{TES5Edit function row|even
  |CanContainFormIDs|boolean|aeElement: IwbElement
  |Guaranteed to return ''True'' if the element can contain form IDs, but not guaranteed to return ''False'' if it can't. This accesses an internal property, ''CanContainFormIDs'', which the internal implementation of ''BuildRef'' uses to skip processing certain descendant elements.}}
{{TES5Edit function row|odd
  |CanMoveDown|boolean|aeElement: IwbElement
  |Returns true if the element is part of an array and can be moved further down using ''MoveDown''.}}
{{TES5Edit function row|even
  |CanMoveUp|boolean|aeElement: IwbElement
  |Returns true if the element is part of an array and can be moved further up using ''MoveUp''.}}
{{TES5Edit function row|odd
  |Check|string|aeElement: IwbElement
  |Returns the error message produced when the "Check for Errors" functionality is run on ''aeElement''; or else an empty string if no error is found.}}
{{TES5Edit function row|even
  |ClearElementState||aeElement: IwbElement;<br/> aiState: TwbElementState
  |Manipulates the internal flags of an element, e.g. <code>ClearElementState(eElement, esModified);</code>. See also: ''GetElementState'', ''SetElementState''.}}
{{TES5Edit function row|odd
  |ContainingMainRecord|IwbMainRecord|aeElement: IwbElement
  |Returns the main record that contains the element.}}
{{TES5Edit function row|even
  |DefType|TwbDefType|aeElement: IwbElement
  |Returns the def-type of the element.}}
{{TES5Edit function row|odd
  |DisplayName|string|aeElement: IwbElement
  |Returns the display name of the element, if it has one; otherwise, this behaves identically to ''Name''. See also: ''BaseName'', ''ShortName''.}}
{{TES5Edit function row|even
  |ElementAssign|IwbElement|aeContainer: IwbContainer;<br/> aiIndex: integer;<br/> aeSource: IwbElement;<br/> abOnlySK: boolean
  |Copy the contents of one element into a container element, or create and append an element to a container.
 
;aeContainer
:Destination element.
;aiIndex
:Where to place the new element, if the destination is an array. Specify ''HighInteger'' to append. Specify ''LowInteger'' or a negative value to add to non-arrays.
;aeSource
:Element to copy from. Use ''Nil'' to create a blank element of the appropriate type.
;abOnlySK
:Unknown; believed to be a "shallow copy only" bool. False appears to work.
 
Sample: there is a script to copy VMAD subrecords "Skyrim - Copy VMAD subrecord.pas"}}
{{TES5Edit function row|odd
  |ElementType|TwbElementType|aeElement: IwbElement
  |Returns the type of the element. This is one of the following values: etFile, etMainRecord, etGroupRecord, etSubRecord, etSubRecordStruct, etSubRecordArray, etSubRecordUnion, etArray, etStruct, etValue, etFlag, etStringListTerminator,etUnion, etStructChapter.}}
{{TES5Edit function row|even
  |EnumValues|string|aeElement: IwbElement
  |If ''aeElement'' is a set of named enum values, this function returns the names of any values that have been set, separated with spaces.}}
{{TES5Edit function row|odd
  |Equals|boolean|aeElement1: IwbElement;<br/> aeElement2: IwbElement
  |Compares two elements by their ElementID. This is sometimes necessary, as different IInterface variables pointing to the same element don't always compare properly when using the <code>{{=}}</code> operator.}}
{{TES5Edit function row|even
  |FlagValues|string|aeElement: IwbElement
  |If ''aeElement'' is a set of flags, this function returns the names of all set flags, separated with spaces.}}
{{TES5Edit function row|odd
  |FullPath|string|aeElement: IwbElement
  |Returns the full path to the element, going all the way down to its containing file. See also: ''Path'', ''PathName''.}}
{{TES5Edit function row|even
  |GetContainer|IwbContainer|aeElement: IwbElement
  |Returns the element's container.}}
{{TES5Edit function row|odd
  |GetEditValue|string|aeElement: IwbElement
  |Returns a string representation of the element's value. See also: ''SetEditValue'', ''GetElementEditValues'', ''SetElementEditValues''.}}
{{TES5Edit function row|even
  |GetElementState|TwbElementState|aeElement: IwbElement;<br/> aiState: TwbElementState
  |Checks the internal flags of an element. See also: ''ClearElementState'', ''SetElementState''.}}
{{TES5Edit function row|odd
  |GetFile|IwbFile|aeElement: IwbElement
  |Returns the file that contains the element.}}
{{TES5Edit function row|even
  |GetNativeValue|variant|aeElement: IwbElement
  |Returns the element's value. See also: ''SetNativeValue'', ''GetElementNativeValues'', ''SetElementNativeValues''.}}
{{TES5Edit function row|odd
  |IsEditable|boolean|aeElement: IwbElement
  |Returns true if the record can be edited. In some cases, xEdit will block edits to files like Skyrim.esm.}}
{{TES5Edit function row|even
  |IsInjected|boolean|aeElement: IwbElement
  |Returns true if the element is an injected record.}}
{{TES5Edit function row|odd
  |LinksTo|IwbElement|aeElement: 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).}}
{{TES5Edit function row|even
  |MarkModifiedRecursive||aeElement: IwbElement
  |Presumably marks the element and all of its descendants as modified.}}
{{TES5Edit function row|odd
  |MoveDown||aeElement: IwbElement
  |If the element is part of an array, this function moves it down by one slot. See also: ''CanMoveDown''.}}
{{TES5Edit function row|even
  |MoveUp||aeElement: IwbElement
  |If the element is part of an array, this function moves it up by one slot. See also: ''CanMoveUp''.}}
{{TES5Edit function row|odd
  |Name|string|aeElement: IwbElement
  |Returns the name of the element, if it has one. If ''aeElement'' is an IwbFile or certain kinds of IwbMainRecords, ''Name'' will return a "pretty" name, while ''BaseName'' or ''ShortName'' will return a more basic string. See also: ''DisplayName''.}}
{{TES5Edit function row|even
  |Path|string|aeElement: IwbElement
  |Returns the ''path component'' of ''aeElement'' -- that is, ''one single piece'' of the path that ''FullPath'' would return. You could use this when manually constructing a path to supply to ''ElementByPath''. See also (and don't confuse with): ''FullPath'', ''PathName''.}}
{{TES5Edit function row|odd
  |PathName|string|aeElement: IwbElement
  |Similar to ''FullPath'' except that names in the path are prefixed with brackets, to uniquely identify each element's unique position among its siblings (see ''IndexOf'').
 
Example: <code>\[02] neromancer.esp\[7] Worldspace\[1] World Children\[1] Children of 00000D74\[0] Persistent\[2] [REFR:00100452]</code>}}
{{TES5Edit function row|even
  |Remove||aeElement: IwbElement
  |Removes the element from its file.}}
{{TES5Edit function row|odd
  |ReportRequiredMasters||aeElement: IwbElement;<br/> akListOut: TStrings;<br/> akUnknown1: boolean;<br/> akUnknown2: boolean
  |Checks which master files ''aeElement'' depends on, and adds their filenames to ''akListOut''. The boolean arguments' purposes are unknown, but the "Report masters.pas" script passes ''False'' for both.}}
{{TES5Edit function row|even
  |SetEditValue|string|aeElement: IwbElement;<br/> asValue: string
  |Sets the element's value to one that matches the string representation passed in. See also: ''GetEditValue'', ''GetElementEditValues'', ''SetElementEditValues''.}}
{{TES5Edit function row|odd
  |SetElementState|TwbElementState|aeElement: IwbElement;<br/> aiState: TwbElementState
  |Manipulates the internal flags of an element. Returns the value prior to modification. See also: ''ClearElementState'', ''GetElementState''.}}
{{TES5Edit function row|even
  |SetNativeValue|string|aeElement: IwbElement;<br/> avValue: variant
  |Sets the element's value. See also: ''GetNativeValue'', ''GetElementNativeValues'', ''SetElementNativeValues''.}}
{{TES5Edit function row|odd
  |SetToDefault||aeElement: IwbElement
  |Unknown. Introduced in xEdit 3.1.3.}}
{{TES5Edit function row|even
  |ShortName|string|aeElement: IwbElement
  |Generally the same as ''Name'' unless ''aeElement'' is a reference, cell, or similar record. ''Name'' will return detailed information for those records, while ''ShortName'' will return the signature and form ID in the format <code>[XXXX:01234567]</code>.}}
{{TES5Edit function row|odd
  |SortKey|string|aeElement: IwbElement
  |Returns a string unique to the element entered. This can be used for sorting elements or for comparing them; for example, you could compare the SortKey for two elements in records which override each other to see if they are different from each other.}}
{{TES5Edit function row|even
  |wbCopyElementToFile|IwbElement|aeElement: IwbElement;<br/> aeFile: IwbFile;<br/> abAsNew: boolean;<br/> abDeepCopy: boolean
  |Copies an IwbMainRecord, IwbGroupRecord, or IwbContainer to the specified file. The ''abAsNew'' boolean controls whether or not you're copying the record as an override record. Returns the copied element.}}
{{TES5Edit function row|odd
  |wbCopyElementToFileWithPrefix|IwbElement|aeElement: IwbElement;<br/> aeFile: IwbFile;<br/> abAsNew: boolean;<br/> abDeepCopy: boolean;<br/> akUnknown;<br/> akUnknown;<br/> akUnknown
  |Details unknown. Returns the copied element.}}
{{TES5Edit function row|even
  |wbCopyElementToRecord|IwbElement|aeElement: IwbElement;<br/> aeRecord: IwbMainRecord;<br/> abAsNew: boolean;<br/> abDeepCopy: boolean
  |Copies an element to a record, e.g. the "Conditions" element on a [[Constructible Object|COBJ]] record or a faction from an [[ActorBase|NPC_]] record. Returns the copied element.}}
|}
 
==== IwbContainer ====
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
|- align="left"
! scope="col" style="background-color: #DDDDDD" | Function
! scope="col" style="background-color: #DDDDDD" | Returns
! scope="col" style="background-color: #DDDDDD" | Arguments
! scope="col" style="background-color: #DDDDDD" | Description
{{TES5Edit function row|even
  |Add|IwbElement|aeContainer: IwbContainer;<br/> asNameOrSignature: string;<br/> abSilent: boolean
  |Creates a child element with the name-or-signature ''asNameOrSignature'' in ''aeContainer'' if no such child already exists; otherwise, marks the existing child as modified. Returns the created or existing element.}}
{{TES5Edit function row|odd
  |AddElement||aeContainer: IwbContainer;<br/> aeElement: IwbElement
  |Adds ''aeElement'' as a child of ''aeContainer''. Throws an error if ''aeElement'' already has a container.}}
{{TES5Edit function row|even
  |AdditionalElementCount|integer|aeContainer: IwbContainer
  |Unknown. This getter accesses an internal function used internally for imposing some order on the sub-elements; it checks whether this element "counts," and if so, how many times. Seems to return 1 or 2 for (main?) records, and 0 for record fields (sub-records).}}
{{TES5Edit function row|odd
  |ContainerStates|byte|aeContainer: IwbContainer
  |Returns the internal container flags for ''aeContainer'' (e.g. whether it's initialized, or whether it has had references built) as a bitmask. Refer to "Worldspace browser.pas" for a usage example.}}
{{TES5Edit function row|even
  |ElementByIndex|IwbElement|aeContainer: IwbContainer;<br/> aiIndex: integer
  |Returns the ''aiIndex''-th child element in ''aeContainer''. See also: ''ElementCount''.}}
{{TES5Edit function row|odd
  |ElementByName|IwbElement|aeContainer: IwbContainer;<br/> asName: string
  |Searches ''aeContainer'' for the child element with name ''asName'', and returns the found element or ''Nil''. See also: ''ElementExists''.}}
{{TES5Edit function row|even
  |ElementByPath|IwbElement|aeContainer: IwbContainer;<br/> asPath: string
  |Searches ''aeContainer'' for the descendant element specified by path ''asPath'', and returns the found element or ''Nil''.}}
{{TES5Edit function row|odd
  |ElementBySignature|IwbElement|aeContainer: IwbContainer;<br/> asSignature: string
  |Searches ''aeContainer'' for the child element with signature ''asSignature'', and returns the found element or ''Nil''.}}
{{TES5Edit function row|even
  |ElementCount|integer|aeContainer: IwbContainer
  |Returns the number of child elements in ''aeContainer''. See also: ''ElementByIndex''.}}
{{TES5Edit function row|odd
  |ElementExists|boolean|aeContainer: IwbContainer;<br/> asName: string
  |Returns true if ''aeContainer'' as a child element whose name is ''asName''. See also: ''ElementByName''.}}
{{TES5Edit function row|odd
  |GetElementEditValues|string|aeContainer: IwbContainer;<br/> asPath: string
  |Finds the element within ''aeContainer'' specified by ''asPath'', and returns a string representation of its value.}}
{{TES5Edit function row|even
  |GetElementNativeValues|variant|aeContainer: IwbContainer;<br/> asPath: string
  |Finds the element within ''aeContainer'' specified by ''asPath'', and returns its value.}}
{{TES5Edit function row|even
  |IndexOf|integer|aeContainer: IwbContainer;<br/> aeChild: IwbElement
  |Returns the index of ''aeChild'' in ''aeContainer'', or -1 if ''aeChild'' is not a child element of ''aeContainer''.}}
{{TES5Edit function row|odd
  |InsertElement||aeContainer: IwbContainer;<br/> aiPosition: Integer;<br/> aeElement: IwbElement
  |Inserts ''aeElement'' as a child of ''aeContainer'' at the specified position.}}
{{TES5Edit function row|even
  |IsSorted|boolean|aeContainer: IwbSortableContainer
  |Checks whether xEdit always keeps ''aeContainer'' sorted. If so, this function will return ''True'', and calling ''CanMoveUp'' and ''CanMoveDown'' on child elements will always return ''False''.}}
{{TES5Edit function row|odd
  |LastElement|IwbElement|aeContainer: IwbContainer
  |Returns the last child element in ''aeContainer'', or ''Nil'' if there are no child elements.}}
{{TES5Edit function row|even
  |RemoveByIndex|IwbElement|aeContainer: IwbContainer;<br/> aiIndex: integer;<br/> abMarkModified: boolean
  |Removes the ''aiIndex''-th child from ''aeContainer'', and returns it.}}
{{TES5Edit function row|odd
  |RemoveElement|IwbElement|aeContainer: IwbContainer;<br/> avChild: variant
  |Removes ''avChild'' from ''aeContainer'' and returns the removed element. The ''avChild'' argument can be: the index of an element to remove from an array container; the name or signature of an element to remove; or an IwbElement to remove.}}
{{TES5Edit function row|even
  |ReverseElements||aeContainer: IwbContainer
  |Reverses the order of the child elements in ''aeContainer''.}}
{{TES5Edit function row|odd
  |SetElementEditValues||aeContainer: IwbContainer;<br/> asPath: string;<br/> asValue: string
  |Finds the element within ''aeContainer'' specified by ''asPath'', and sets its value based on the string representation ''asValue''.}}
{{TES5Edit function row|even
  |SetElementNativeValues||aeContainer: IwbContainer;<br/> asPath: string;<br/> avValue: variant
  |Finds the element within ''aeContainer'' specified by ''asPath'', and sets its value to ''asValue''.}}
|}
 
==== IwbFile ====
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
|- align="left"
! scope="col" style="background-color: #DDDDDD" | Function
! scope="col" style="background-color: #DDDDDD" | Returns
! scope="col" style="background-color: #DDDDDD" | Arguments
! scope="col" style="background-color: #DDDDDD" | Description
{{TES5Edit function row|even
  |AddMasterIfMissing||aeFile: IwbFile;<br/> asMasterFilename: string
  |Adds the specified file as a master for ''aeFile'', if it isn't already a master.}}
{{TES5Edit function row|odd
  |CleanMasters||aeFile: IwbFile
  |Appears to find unnecessary files in ''aeFile''<nowiki/>'s master list and remove them, updating all form indices accordingly. Don't confuse this within "cleaning master files" as in "removing ITMs and UDRs from official DLCs." This function is used in "Skyrim - Book Covers Patch.pas".}}
{{TES5Edit function row|even
  |FileFormIDtoLoadOrderFormID|cardinal|aeFile: IwbFile; aiFormID: cardinal
  |Converts ''aiFormID'' from a form ID relative to ''aeFile''<nowiki/>'s master list (like that returned by ''FixedFormID'') to a load-order-relative form ID (like that returned by ''FormID''). See also: ''LoadOrderFormIDtoFileFormID''.}}
{{TES5Edit function row|odd
  |FileWriteToStream||aeFile: IwbFile;<br/> akOutStream: TStream
  |Writes the contents of ''aeFile'' to ''akOutStream''. Used in "SaveAs.pas" to allow a user to save a loaded file under a new name; that script creates a TFileStream object and uses this function to write to it.}}
{{TES5Edit function row|even
  |GetFileName|string|aeFile: IwbFile
  |Returns ''aeFile''<nowiki/>'s filename.}}
{{TES5Edit function row|odd
  |GetIsESM|boolean|aeFile: IwbFile
  |Returns ''True'' if ''aeFile'' is flagged as an ESM. See also: ''SetIsESM''.}}
{{TES5Edit function row|even
  |GetLoadOrder|string|aeFile: IwbFile
  |Returns ''aeFile''<nowiki/>'s index in the load order, or -1 if called on something that is not an IwbFile.}}
{{TES5Edit function row|odd
  |GetNewFormID|cardinal|aeFile: IwbFile
  |Returns a new form ID, the same way that <code>Add(..., ..., True)</code> does.}}
{{TES5Edit function row|even
  |GroupBySignature|IwbGroupRecord|aeFile: IwbFile;<br/> asSignature: string
  |If ''aeFile'' has a top-level group with the specified signature, that group is returned.}}
{{TES5Edit function row|odd
  |HasGroup|boolean|aeFile: IwbFile;<br/> asSignature: string
  |Returns ''True'' if ''aeFile'' contains a top-level group with the specified signature.}}
{{TES5Edit function row|even
  |HasMaster|boolean|aeFile: IwbFile;<br/> asMasterFilename: string
  |Returns ''True'' if ''aeFile'' has a file with the name ''asMasterFilename'' as a master.}}
{{TES5Edit function row|odd
  |LoadOrderFormIDtoFileFormID|cardinal|aeFile: IwbFile; aiFormID: cardinal
  |Converts ''aiFormID'' from a load-order-relative form ID (like that returned by ''FormID'') to a form ID relative to ''aeFile''<nowiki/>'s master list (like that returned by ''FixedFormID''). See also: ''FileFormIDtoLoadOrderFormID''.}}
{{TES5Edit function row|even
  |MasterByIndex|IwbFile|aeFile: IwbFile;<br/> aiIndex: integer
  |Returns the ''aiIndex''-th master file for ''aeFile''.}}
{{TES5Edit function row|odd
  |MasterCount|cardinal|aeFile: IwbFile
  |Returns the number of master files that ''aeFile'' has.}}
{{TES5Edit function row|even
  |RecordByEditorID|IwbMainRecord|aeFile: IwbFile;<br/> asEditorID: string
  |Returns the [[Magic Effect|MGEF]] or [[Setting|GMST]] record in ''aeFile'' that has the specified editor ID. For all other record types, use something like <code>MainRecordByEditorID(GroupBySignature(f, 'ECZN'), 'RandomEncounterZone1')</code>.}}
{{TES5Edit function row|odd
  |RecordByFormID|IwbMainRecord|aeFile: IwbFile;<br/> aiFormID: integer;<br/> abAllowInjected: boolean
  |Returns the main record in ''aeFile'' that has the specified form ID, or ''Nil'' if no records match. The form ID must be local to the file (see ''FixedFormID'').}}
{{TES5Edit function row|even
  |RecordByIndex|IwbMainRecord|aeFile: IwbFile;<br/> aiIndex: integer
  |Returns the ''aiIndex''-th record in ''aeFile''.}}
{{TES5Edit function row|odd
  |RecordCount|cardinal|aeFile: IwbFile
  |Returns the number of records that ''aeFile'' has.}}
{{TES5Edit function row|even
  |SetIsESM||aeFile: IwbFile;<br/> abFlag: boolean
  |Modifies the ESM flag for ''aeFile''. See also: ''GetIsESM''.}}
{{TES5Edit function row|odd
  |SortMasters||aeFile: IwbFile
  |Attempts to sort the masters for ''aeFile'' by their place in the current load order.}}
|}
 
==== IwbMainRecord ====
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
|- align="left"
! scope="col" style="background-color: #DDDDDD" | Function
! scope="col" style="background-color: #DDDDDD" | Returns
! scope="col" style="background-color: #DDDDDD" | Arguments
! scope="col" style="background-color: #DDDDDD" | Description
{{TES5Edit function row|even
  |BaseRecord|IwbMainRecord|aeRecord: IwbMainRecord
  |If ''aeRecord'' is a [[reference]], this function returns the IwbMainRecord of its base form. Otherwise, the function returns ''Nil''.}}
{{TES5Edit function row|odd
  |BaseRecordID|cardinal|aeRecord: IwbMainRecord
  |Appears to return the load-order-relative form ID of ''aeRecord''.}}
{{TES5Edit function row|even
  |ChangeFormSignature||aeRecord: IwbMainRecord;<br/> asNewSignature: string
  |Changes ''aeRecord''<nowiki/>'s signature to ''asNewSignature''. No other information is modified.}}
{{TES5Edit function row|odd
  |ChildGroup|IwbGroupRecord|aeRecord: IwbMainRecord
  |Returns the group that ''aeRecord'' contains, if any. For example, a [[Worldspace|WRLD]] record will be followed by a GRUP containing the worldspace's [[Cell|CELL]]s, and you would use this function to retrieve that group.}}
{{TES5Edit function row|even
  |CompareExchangeFormID|boolean|aeRecord: IwbMainRecord;<br/> aiOldFormID: cardinal;<br/> aiNewFormID: cardinal
  |Attempts to change ''aeRecord''<nowiki/>'s form ID from ''aiOldFormID'' to ''aiNewFormID'', and returns ''True'' if the operation succeeds.}}
{{TES5Edit function row|odd
  |EditorID|string|aeRecord: IwbMainRecord
  |Returns the record's editor ID.}}
{{TES5Edit function row|even
  |FixedFormID|cardinal|aeRecord: IwbMainRecord
  |Returns the local FormID of the record. Local records will not have a load-order prefix (i.e. 0x00FFFFFF), and overrides will have a prefix relative to the record's file's masters. See also: ''FormID'', ''GetLoadOrderFormID''.}}
{{TES5Edit function row|odd
  |FormID|cardinal|aeRecord: IwbMainRecord
  |Returns the record's form ID. See also: ''FixedFormID'', ''GetLoadOrderFormID''.}}
{{TES5Edit function row|even
  |GetFormVCS1|cardinal|aeRecord: IwbMainRecord
  |Returns the value of the Version Control Info 1 field. See also: ''SetFormVCS1''.}}
{{TES5Edit function row|odd
  |GetFormVCS2|cardinal <!-- even though the field itself is a word -->|aeRecord: IwbMainRecord
  |Returns the value of the Version Control Info 2 field. See also: ''SetFormVCS2''.}}
{{TES5Edit function row|even
  |GetFormVersion|cardinal|aeRecord: IwbMainRecord
  |Unknown. See also: ''SetFormVersion''.}}
{{TES5Edit function row|odd
  |GetGridCell|TwbGridCell|aeRecord: IwbMainRecord
  |If ''aeRecord'' is an exterior [[cell]], this function will return its grid coordinates as a TwbGridCell; you can access the coordinates by checking <code>returnValue.x</code> and <code>returnValue.y</code>.}}
{{TES5Edit function row|even
  |GetIsDeleted|boolean|aeRecord: IwbMainRecord
  |Checks the record's "deleted" flag. See also: ''SetIsDeleted''.}}
{{TES5Edit function row|odd
  |GetIsInitiallyDisabled|boolean|aeRecord: IwbMainRecord
  |Checks the record's "initially disabled" flag. See also: ''SetIsInitiallyDisabled''.}}
{{TES5Edit function row|even
  |GetIsPersistent|boolean|aeRecord: IwbMainRecord
  |Checks the record's "persistent" flag. See also: ''SetIsPersistent''.}}
{{TES5Edit function row|odd
  |GetIsVisibleWhenDistant|boolean|aeRecord: IwbMainRecord
  |Checks the record's "visible when distant" flag. See also: ''SetIsVisibleWhenDistant''.}}
{{TES5Edit function row|even
  |GetLoadOrderFormID|cardinal|aeRecord: IwbMainRecord
  |Returns the record's form ID relative to the current load order. See also: ''FixedFormID'', ''SetLoadOrderFormID''.}}
{{TES5Edit function row|odd
  |GetPosition|TwbVector|aeRecord: IwbMainRecord
  |If ''aeRecord'' is a [[reference]] (or a subtype, like ACHR), this function will return its position.}}
{{TES5Edit function row|even
  |GetRotation|TwbVector|aeRecord: IwbMainRecord
  |If ''aeRecord'' is a [[reference]] (or a subtype, like ACHR), this function will return its rotation.}}
{{TES5Edit function row|odd
  |HasPrecombinedMesh|boolean|aeRecord: IwbMainRecord
  |Checks whether ''aeRecord'' is a Fallout 4 [[reference]] that has precombined mesh data generated. See also: ''PrecombinedMesh''.}}
{{TES5Edit function row|even
  |HighestOverrideOrSelf|IwbMainRecord|aeRecord: IwbMainRecord
  |See also: ''WinningOverride''.}}
{{TES5Edit function row|odd
  |IsMaster|boolean|aeRecord: IwbMainRecord
  |Returns ''True'' if ''aeRecord'' is a master, and false if it is an override or not an IwbMainRecord. See also: ''Master'', ''MasterOrSelf''.}}
{{TES5Edit function row|even
  |IsWinningOverride|boolean|aeRecord: IwbMainRecord
  |Returns ''True'' if ''aeRecord'' is the last loaded override for its master. See also: ''Master'', ''MasterOrSelf''.}}
{{TES5Edit function row|odd
  |Master|IwbMainRecord|aeRecord: IwbMainRecord
  |}}
{{TES5Edit function row|even
  |MasterOrSelf|IwbMainRecord|aeRecord: IwbMainRecord
  |If ''aeRecord'' is an override, the function returns the master record that it overrides. Otherwise, the function returns ''aeRecord'' itself. See also: ''IsMaster'', ''IsWinningOverride''.}}
{{TES5Edit function row|odd
  |OverrideByIndex|IwbMainRecord|aeRecord: IwbMainRecord;<br/> aiIndex: integer
  |Returns the ''aiIndex''-th override of ''aeRecord''.}}
{{TES5Edit function row|even
  |OverrideCount|cardinal|aeRecord: IwbMainRecord
  |Returns the number of records that override ''aeRecord''.}}
{{TES5Edit function row|odd
  |PrecombinedMesh|string|aeRecord: IwbMainRecord
  |Returns the path to ''aeRecord''<nowiki/>'s precombined mesh file, if ''aeRecord'' is a Fallout 4 [[reference]] that could have that data (i.e. not a placed actor). See also: ''HasPrecombinedMesh''.}}
{{TES5Edit function row|even
  |ReferencedByIndex|IwbMainRecord|aeRecord: IwbMainRecord;<br/> aiIndex: integer
  |Returns the ''aiIndex''-th record that references ''aeRecord''.}}
{{TES5Edit function row|odd
  |ReferencedByCount|cardinal|aeRecord: IwbMainRecord
  |Returns the number of records that refer to ''aeRecord''.}}
{{TES5Edit function row|even
  |SetEditorID|string|aeRecord: IwbMainRecord
  |Sets the record's editor ID, and then returns it.}}
{{TES5Edit function row|odd
  |SetFormVersion||aeRecord: IwbMainRecord;<br/> aiVersion: cardinal
  |Unknown. See also: ''GetFormVersion''.}}
{{TES5Edit function row|even
  |SetIsDeleted|boolean|aeRecord: IwbMainRecord;<br/> abFlag: boolean
  |Modifies the record's "deleted" flag. See also: ''GetIsDeleted''.}}
{{TES5Edit function row|odd
  |SetIsInitiallyDisabled|boolean|aeRecord: IwbMainRecord;<br/> abFlag: boolean
  |Modifies the record's "initially disabled" flag. See also: ''GetIsInitiallyDisabled''.}}
{{TES5Edit function row|even
  |SetIsPersistent|boolean|aeRecord: IwbMainRecord;<br/> abFlag: boolean
  |Modifies the record's "persistent" flag. See also: ''GetIsPersistent''.}}
{{TES5Edit function row|odd
  |SetIsVisibleWhenDistant|boolean|aeRecord: IwbMainRecord;<br/> abFlag: boolean
  |Modifies the record's "visible when distant" flag. See also: ''GetIsVisibleWhenDistant''.}}
{{TES5Edit function row|even
  |SetLoadOrderFormID|cardinal|aeRecord: IwbMainRecord;<br/> aiFormID: cardinal;
  |Modifies the record's form ID, with the specified ID relative to the current load order. See also: ''GetLoadOrderFormID''.}}
{{TES5Edit function row|odd
  |SetFormVCS1||aeRecord: IwbMainRecord;<br/> aiValue: cardinal
  |Modifies the Version Control Info 1 field. See also: ''GetFormVCS1''.}}
{{TES5Edit function row|even
  |SetFormVCS2||aeRecord: IwbMainRecord;<br/> aiValue: cardinal <!-- even though the field itself is a word -->
  |Modifies the Version Control Info 2 field. See also: ''GetFormVCS2''.}}
{{TES5Edit function row|odd
  |Signature|string|aeRecord: IwbMainRecord
  |Returns the record's signature, a four-character code such as [[ActorBase|NPC_]] or [[Topic|DIAL]].}}
{{TES5Edit function row|even
  |UpdateRefs||aeRecord: IwbMainRecord
  |Appears to be the same as ''BuildRef'', except that it aborts if references are already in the middle of being built.}}
{{TES5Edit function row|odd
  |WinningOverride|IwbMainRecord|aeRecord: IwbMainRecord
  |Returns the last loaded override for ''aeRecord''. See also: ''HighestOverrideOrSelf''.}}
|}
 
==== IwbGroupRecord ====
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
|- align="left"
! scope="col" style="background-color: #DDDDDD" | Function
! scope="col" style="background-color: #DDDDDD" | Returns
! scope="col" style="background-color: #DDDDDD" | Arguments
! scope="col" style="background-color: #DDDDDD" | Description
{{TES5Edit function row|even
  |ChildrenOf|IwbMainRecord|aeGroup: IwbGroupRecord
  |If ''aeGroup'' is a child group, this function returns the main record that it is associated with. For example, a [[Topic|Dialogue Topic]] (DIAL) is followed by a group (GRUP) that contains its [[Topic Info|Infos]] (INFO); and passing that GRUP to this function would retrieve the DIAL. [[Cell]]s (CELL) and [[Worldspace]]s (WRLD) have their contents set up similarly to Dialogue Topics, so this function will work with them as well.}}
{{TES5Edit function row|odd
  |FindChildGroup|IwbGroupRecord|aeGroup: IwbGroupRecord;<br/>aiType: integer;<br/> aeMainRecord: IwbMainRecord;<br/>
  |Unknown. The ''aiType'' value should match the group-type values used in [http://en.uesp.net/wiki/Tes5Mod:Mod_File_Format#Groups the file format]. The "Worldspace browser.pas" script uses <code>FindChildGroup(ChildGroup(cell), 9, cell);</code> to get the "Temporary" group within a CELL.}}
{{TES5Edit function row|even
  |GroupLabel|cardinal|aeGroup: IwbGroupRecord
  |Returns the raw group label, as specified in [http://en.uesp.net/wiki/Tes5Mod:Mod_File_Format#Groups the file format].}}
{{TES5Edit function row|odd
  |GroupType|integer|aeGroup: IwbGroupRecord
  |Returns the raw group type, as specified in [http://en.uesp.net/wiki/Tes5Mod:Mod_File_Format#Groups the file format].}}
{{TES5Edit function row|even
  |MainRecordByEditorID|IwbMainRecord|aeGroup: IwbGroupRecord;<br/> asEditorID: string
  |Searches ''aeGroup'' for a main record whose editor ID is ''asEditorID'' and returns the matching record or ''Nil''. This is not a performant function.}}
|}
 
==== IwbResource ====
These functions are used in "Assets browser.pas", "Assets manager.pas", and "Skyrim - List used scripts.pas".
 
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
|- align="left"
! scope="col" style="background-color: #DDDDDD" | Function
! scope="col" style="background-color: #DDDDDD" | Returns
! scope="col" style="background-color: #DDDDDD" | Arguments
! scope="col" style="background-color: #DDDDDD" | Description
{{TES5Edit function row|even
  |ResourceContainerList||akContainers: TwbFastStringList
  |Fills ''akContainers'' with the full filenames (directory + name) of all loaded BSA and BA2 files, as well as the name of the Data directory. ''akContainers'' can be a TwbFastStringList or a TStringList.}}
{{TES5Edit function row|odd
  |ResourceCopy||asContainerName: string;<br/> asFilename: string;<br/> asPathOut: string
  |Retrieves the resource named ''asFilename'' from the resource container named ''asContainerName'' (see ''ResourceContainerList''), and saves that resource to the specified file path ''asPathOut''. The "Assets browser.pas" script uses this to let users extract a resource from a BSA/BA2.}}
{{TES5Edit function row|even
  |ResourceCount|cardinal|asFilename: string;<br/> akContainers: TStrings
  |Fills ''akContainers'' with a list of the loaded containers (BSA, BA2, Data directory) that a file named ''asFilename'' appears in. The "Assets browser.pas" script uses this to allow users to decide which version of a file to view, when the file is overridden at least once within their load order.}}
{{TES5Edit function row|odd
  |ResourceExists|boolean|asFilename: string
  |Checks whether any loaded container has a file with the specified name.}}
{{TES5Edit function row|even
  |ResourceList||asContainerName: string;<br/> akContainers: TStrings
  |Accesses the container with the full filename ''asContainerName'' (see ''ResourceContainerList''), and adds a list of all contained filenames to ''akContainers''. Note that added entries are unsorted, and there may be duplicates among them.}}
{{TES5Edit function row|odd
  |ResourceOpenData|TBytesStream|asContainerName: string;<br/> asFilename: string
  |''asFilename'' should be formatted similar to the other Resource-oriented xEdit scripts. ''asContainerName'' should be filled with a string generated by the function ''ResourceContainerList''. The ''ResourceOpenData'' function should only be used in conjunction with ''NifTextureList'', as ''ResourceCopy'' removes any other need for this function.}}
|}
 
==== Misc functions ====
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
|- align="left"
! scope="col" style="background-color: #DDDDDD" | Function
! scope="col" style="background-color: #DDDDDD" | Returns
! scope="col" style="background-color: #DDDDDD" | Arguments
! scope="col" style="background-color: #DDDDDD" | Description
{{TES5Edit function row|even
  |LocalizationGetStringsFromFile||asFilename: string;<br/> akListOut: TStrings
  |}}
{{TES5Edit function row|odd
  |wbAlphaBlend|boolean|akDestinationDeviceContext: unknown;<br/> aiDestinationX: integer;<br/> aiDestinationY: integer;<br/> aiDestinationWidth: integer;<br/> aiDestinationHeight: integer;<br/> akSourceDeviceContext: unknown;<br/> aiSourceX: integer;<br/> aiSourceY: integer;<br/> aiSourceWidth: integer;<br/> aiSourceHeight: integer;<br/> aiAlpha: integer
  |A wrapper for ''Windows.AlphaBlend'' which returns its result.}}
{{TES5Edit function row|even
  |wbBlockFromSubBlock|TwbGridCell|akSubBlock: TwbGridCell
  |See also: ''wbPositionToGridCell'', ''wbSubBlockFromGridCell'', ''wbGridCellToGroupLabel'', ''wbIsInGridCell''.}}
{{TES5Edit function row|odd
  |wbCRC32Data|cardinal|akData: TBytes
  |See also: ''wbCRC32File'', ''wbSHA1Data'', ''wbSHA1File'', ''wbMD5Data'', ''wbMD5File''.}}
{{TES5Edit function row|even
  |wbCRC32File|cardinal|asFilename: string
  |See also: ''wbCRC32Data'', ''wbSHA1Data'', ''wbSHA1File'', ''wbMD5Data'', ''wbMD5File''.}}
{{TES5Edit function row|odd
  |wbCRC32Resource|cardinal|asContainerName: string; asFileName: string
  |}}
{{TES5Edit function row|even
  |wbFindREFRsByBase||aeREFR: IwbMainRecord;<br/> asSignatures: string;<br/> aiFlags: integer;<br/> akOutList: TList
  |Searches for sibling records to ''aeREFR'' whose base records' signatures match ''asSignatures'', and adds them to ''akOutList''. Further filtering can be done with ''aiFlags'': specify 1 to exclude deleted references, 2 to exclude initially disabled references, and 4 to exclude references that have an enable parent.}}
{{TES5Edit function row|odd
  |wbFlipBitmap||akBitmap: TBitmap;<br/> aiAxes: integer
  |Flips the image data contained in ''akBitmap'' based on the specified axes. Specify 1 to flip horizontally, 2 to flip vertically, or 0 to flip on both axes.}}
{{TES5Edit function row|even
  |wbGetSiblingRecords||aeRecord: IwbElement;<br/> asSignatures: string;<br/> abIncludeOverrides: boolean;<br/> akOutList: TList
  |Adds sibling records of ''aeRecord'' to ''akOutList'' if their signatures match ''asSignatures''. If ''abIncludeOverrides'' is not ''True'', then overrides will not be included in the result.}}
{{TES5Edit function row|odd
  |wbGridCellToGroupLabel|cardinal|akGridCell: TwbGridCell
  |Returns an integer of the format 0xXXXXYYYY. See also: ''wbBlockFromSubBlock'', ''wbPositionToGridCell'', ''wbIsInGridCell'', ''wbSubBlockFromGridCell''.}}
{{TES5Edit function row|even
  |wbIsInGridCell|boolean|akPosition: TwbVector;<br/> akGridCell: TwbGridCell
  |See also: ''wbBlockFromSubBlock'', ''wbGridCellToGroupLabel'', ''wbPositionToGridCell'', ''wbSubBlockFromGridCell''.}}
{{TES5Edit function row|odd
  |wbMD5Data|cardinal|akData: TBytes
  |See also: ''wbCRC32Data'', ''wbCRC32File'', ''wbMD5File'', ''SHA1Data'', ''wbSH1Data''.}}
{{TES5Edit function row|even
  |wbMD5File|cardinal|asFilename: string
  |Calculation time is about 2.5 times longer than CRC32. See also: ''wbCRC32Data'', ''wbCRC32File'', ''wbMD5Data'', ''SHA1Data'', ''wbSH1Data''.}}
{{TES5Edit function row|odd
  |wbNormalizeResourceName|string|asResourceName: string; akResourceType: TGameResourceType
  |''akResourceType'' can be any of the following values: ''resMesh'', ''resTexture'', ''resSound'', ''resMusic''.}}
{{TES5Edit function row|even
  |wbPositionToGridCell|TwbGridCell|akPosition: TwbVector
  |Converts ''akPosition'' to grid coordinates. In practice, this is done by dividing the physical coordinates by 4096, the lateral length and width of a cell. See also: ''wbBlockFromSubBlock'', ''wbGridCellToGroupLabel'', ''wbIsInGridCell'', ''wbSubBlockFromGridCell''.}}
{{TES5Edit function row|odd
  |wbSHA1Data|cardinal|akData: TBytes
  |See also: ''wbCRC32Data'', ''wbCRC32File'', ''SHA1File'', ''wbMD5Data'', ''wbMD5File''.}}
{{TES5Edit function row|even
  |wbSHA1File|cardinal|asFilename: string
  |Calculation time is about two times longer than CRC32. See also: ''wbCRC32Data'', ''wbCRC32File'', ''SHA1Data'', ''wbMD5Data'', ''wbMD5File''.}}
{{TES5Edit function row|odd
  |wbStringListInString|integer|akList: TStringList; asSubstring: string
  |Checks if any of the strings in ''akList'' contains ''asSubstring''. Returns the index of the first matching entry, or -1. Checks are case-insensitive.}}
{{TES5Edit function row|even
  |wbSubBlockFromGridCell|TwbGridCell|akGridCell: TwbGridCell
  |See also: ''wbBlockFromSubBlock'', ''wbGridCellToGroupLabel'', ''wbIsInGridCell'', ''wbPositionToGridCell''.}}
|}
 
===== NIF functions =====
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
|- align="left"
! scope="col" style="background-color: #DDDDDD" | Function
! scope="col" style="background-color: #DDDDDD" | Returns
! scope="col" style="background-color: #DDDDDD" | Arguments
! scope="col" style="background-color: #DDDDDD" | Description
{{TES5Edit function row|even
  |NifBlockList|boolean|akData: TBytes;<br/> akListOut: TStrings
  |Retrieves block information from the NIF file in ''akData'', and adds it to ''akListOut''. Each added index in ''akListOut'' will match up with a string key of the form "BlockName{{=}}BlockType" and (as an object) a pointer to the NIF block's index number. Returns ''True'' if the operation succeeded.}}
{{TES5Edit function row|odd
  |NifTextureList|boolean|akData: TBytes;<br/> akListOut: TStrings
  |Searches the NIF file in ''akData'' for all texture paths, and adds them to ''akListOut''. Returns ''True'' if the operation succeeded.}}
{{TES5Edit function row|even
  |NifTextureListResource|boolean|akData: variant;<br/> akListOut: TStrings
  |Searches the NIF file in ''akData'' for all texture paths, and adds them to ''akListOut''. Returns ''True'' if the operation succeeded.}}
{{TES5Edit function row|odd
  |NifTextureListUVRange|boolean|akData: TBytes;<br/> afUVRange: Single;<br/> akListOut: TStrings
  |Searches the NIF file in ''akData'' for all texture paths, and adds them to ''akListOut''. Textures are only added if none of the relevant NiTriShape's UV sets have UVs greater than ''afUVRange'' or less than ''-afUVRange''. Returns ''True'' if the operation succeeded.}}
|}
 
===== DDS functions =====
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
|- align="left"
! scope="col" style="background-color: #DDDDDD" | Function
! scope="col" style="background-color: #DDDDDD" | Returns
! scope="col" style="background-color: #DDDDDD" | Arguments
! scope="col" style="background-color: #DDDDDD" | Description
{{TES5Edit function row|even
  |wbDDSStreamToBitmap|boolean|akStream: TStream;<br/> akBitmapOut: TBitmap
  |Modifies ''akBitmapOut'' to contain the DDS information sourced from ''akStream''. Returns ''True'' if the operation succeeds.}}
{{TES5Edit function row|odd
  |wbDDSDataToBitmap|boolean|akData: TBytes;<br/> akBitmapOut: TBitmap
  |Modifies ''akBitmapOut'' to contain the DDS information sourced from ''akData''. Returns ''True'' if the operation succeeds.}}
{{TES5Edit function row|even
  |wbDDSResourceToBitmap|boolean|akUnknown;<br/> akBitmapOut: TBitmap
  |Modifies ''akBitmapOut'' to contain the DDS information sourced from the resource ''akUnknown''. Returns ''True'' if the operation succeeds.}}
|}
 
=== 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.
 
*''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 [https://github.com/matortheeternal/TES5EditScripts/blob/master/trunk/Edit%20Scripts/mteFunctions.pas mtefunctions.pas] for examples as well.
{| 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>TButton</b> || [http://docs.embarcadero.com/products/rad_studio/delphiAndcpp2009/HelpUpdate2/EN/html/delphivclwin32/StdCtrls_TButton.html TButton] || Button || Assets browser.pas || The button doesn't automatically expand its width to accommodate its contents.
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>TCheckBox</b> || [http://docs.embarcadero.com/products/rad_studio/delphiAndcpp2009/HelpUpdate2/EN/html/delphivclwin32/StdCtrls_TCheckBox.html TCheckBox] || Checkbox || none || You can apply a label using the <code>Caption</code> property; you don't need to make your own TLabel. Note, for more advanced scripts, that <code>OnChange</code> is not supported; use <code>OnClick</code> (which listens for more than just clicks) instead. Manually changing the <code>Checked</code> property will also fire an OnClick event; to avoid recursion where needed, you can set <code>OnClick</code> to <code>nil</code>, change <code>Checked</code>, and then restore <code>OnClick</code>'s value.
|- 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 || 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] || 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. Not particularly useful.
|}
 
 
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 TXT 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.txt';
AddMessage('Saving NPC list to ' + filename);
NPCList.SaveToFile(filename);
NPCList.Free;
end;
 
end.
</pre>
 
=== Pascal implementation ===
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: however, it lacks support for certain Delphi 5 language features (e.g. <code>var PerInitialisedVariable: Integer = 42;</code>); and it has scripts return values by assigning to <code>Result</code>, while Borland Delphi 5 (released in 1999) has authors assign to the function name instead.
 
The standard libraries offered by JvInterpreter directly wrap whatever libraries the containing application (xEdit) was compiled with; however, wrappers only exist for the functions offered in Delphi 5. This means that the API (the selection of functions and the arguments they support) is limited to Delphi 5 with extra quirks introduced by JvInterpreter, but the internal behavior of the functions depends on what version of Delphi xEdit was compiled with (possibly Delphi 10).
 
No online documentation of language reference appears to be available for Borland Delphi 5. 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 xEdit!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.
* TES5Edit's Pascal implementation does not appear to support constructions such as <code>TList&lt;Integer&gt;</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.
* JvInterpreter throws an error if any identifiers in the global scope are redeclared; reportedly, this differs from the behavior that Delphi has shown since 1987, wherein global identifiers in later-included files shadow those in earlier-included files. Defining them in <code>implementation</code> blocks doesn't make any difference.
** In addition to this, including a unit multiple times triggers these errors, as its own definitions conflict with themselves. This may be a standard Delphi limitation if [http://stackoverflow.com/questions/11258996/delphi-xe-dcc-error-e2004-identifier-redeclared-system the behavior of the System unit] is of any indication, but literally no official or unofficial documentation on the Internet mentions it as a general rule.
*** And no, Delphi has no equivalent to <code>#pragma once</code>, and JvInterpreter wouldn't support it anyway
* According to Delphi documentation across the web, Const directives inside of functions and procedures are supposed to define static local variables: these variables are not supposed to be constants, and their values are supposed to persist until the script has finished executing. However, in JvInterpreter, Const directives in functions and procedures just define ordinary local variables, whose values will be lost the instant the function or procedure finishes executing. Among other things, this means you can't use getters with static variables to work around the issues with global variables.
 
==== 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>Pred</code> instead of <code>System.Pred</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 ''[xEdit doesn't offer the module itself; only these functions are provided]''
** ''function'' Ceil
** ''function'' Floor
** ''function'' IntPower
** ''function'' Max ''(note: this casts its arguments to integers before comparing them)''
** ''function'' Min ''(note: this casts its arguments to integers before comparing them)''
** ''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%
!style="text-align:left;"|Feature
!style="text-align:left;"|Details
|-
|anonymous methods
|Refer to the [http://docwiki.embarcadero.com/RADStudio/XE8/en/Anonymous_Methods_in_Delphi Embarcadero documentation].
|-
|array arguments
|A function cannot accept an argument with a type like <code>array of integer</code>.
|-
|function overloading
|Allows the same function to have multiple sets of arguments.
|-
|object types
|The <code>object</code> 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 [http://docwiki.embarcadero.com/RADStudio/XE8/en/Procedural_Types Embarcadero documentation].
|-
|structured types
|Refer to the [http://docwiki.embarcadero.com/RADStudio/XE8/en/Structured_Types Embarcadero documentation].
|-
|subclasses
|The <code>constructor</code> keyword isn't implemented. Subclasses without a constructor can be defined, but attempts to instantiate them (<code>MyClass.Create</code>) will always break.
|-
|try
|Doesn't catch all runtime errors.
|-
|}
 
==== Unsupported operators ====
{|class="wikitable" width =100%
!style="text-align:left;"|Operator
!style="text-align:left;"|Description
|-
|&
|Prefix; suppresses parsing of a keyword (e.g. <code>&For</code> is a variable named "For").
|-
|@
|Prefix; retrieves the address of a variable for use as a pointer; compare to <code>&</code> in C++.
|-
|^
|Dereferences a pointer; compare to <code>*</code> in C++.
|-
|<<
|Used for bit shifting, but returns a junk result in xEdit. Use <code>Shl</code> instead.
|-
|>>
|Used for bit shifting, but returns a junk result in xEdit. Use <code>Shr</code> instead.
|-
|}
 
==== Unsupported keywords ====
{|class="wikitable" width =100%
!style="text-align:left;"|Keyword
!style="text-align:left;"|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 <code>TObject</code>, you can use the <code>ClassName</code> method instead.
|-
|object
|Used to create [http://docwiki.embarcadero.com/RADStudio/Berlin/en/Classes_and_Objects_(Delphi)#Object_Types 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 ====
{|class="wikitable" width =100%
!style="text-align:left;"|Feature
!style="text-align:left;"|Description
|-
|[http://docwiki.embarcadero.com/RADStudio/XE2/en/Variant_Support_Routines Variant support routines]
|Makes it easier to identify a variant's current type, and cast variants. Relevant type keywords like <code>varInteger</code> 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.
|-
|}

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"