Main Table Of Contents

xEdit Scripting Functions

Contents...

•  13.1 Description

•  13.2 Using the Delphi IDE to Edit TES5Edit Scripts

•  13.3 Instructions to get started editing xEdit scripts with Delphi

•  13.4 TES5Edit Global Variables

•  13.5 TES5Edit Scripting Functions

•  13.6 Global functions

•  13.7 IwbElement

•  13.8 IwbContainer

•  13.9 IwbFile

•  13.10 IwbMainRecord

•  13.11 IwbGroupRecord

•  13.12 IwbResource

•  13.13 Misc functions

•  13.14 NIF functions

•  13.15 DDS functions

•  13.16 Script Structure

•  13.17 Base Script Functions

•  13.18 Hotkeys

•  13.19 Script References

•  13.20 Script User Interface

•  13.21 Simple Script Sample

•  13.22 Pascal implementation

•  13.23 xEdit extensions to JvInterpreter

•  13.24 Unsupported language features

•  13.25 Unsupported operators

•  13.26 Unsupported keywords

•  13.27 Unsupported classes and tools

13.1 - 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.

13.2 - Using the Delphi IDE to Edit TES5Edit Scripts

As of TES5Edit version 3.2.1, there is a file in the Edit Scripts directory called xEditAPI.pas

The contents of that file match what is published here. The xEditAPI.pas includes xEdit API declarations to be used for editing scripts using Delphi. With this file you can now edit xEdit scripts using Delphi. This gives you full IDE benefits like checking for warnings and errors before executing your script, as well as intellisense and code insights.

For example purposes in this documentation, we assume a user created xEdit script named GreatScript.pas. However, you can name your script almost anything. There are some limitations though, because the name of the script must match the unit declaration of the script, and unit names have limitations. See Delphi Identifiers

13.3 - Instructions to get started editing xEdit scripts with Delphi

•  Download the free Delphi Starter edition, called RAD Studio (current version is 10.2) from Embarcadero Delphi Starter

•  Create new console application project named GreatScriptApp

•  Add the files xEditAPI.pas and GreatScript.pas to the project (menu Project -> Add to project)

•  At the top of the script, modify or add the unit clause. The name of the unit must match exactly the filename of your script without the .pas extension.

•  Then add/update the interface, implementation, and uses clauses to your script below. Afterwards, the top of your script file should look like this:

  unit GreatScript;

  interface
  implementation
  uses xEditAPI, Classes, SysUtils, StrUtils, Windows;

•  You can add additional Delphi units to the uses clause needed, for example IniFiles if script works with them.

•  Check that project can be compiled Ctrl+F9 and the same script can be applied in xEdit without errors.

•  While editing your script, before running it in xEdit, press Ctrl+F9 in Delphi to compile and ensure that the code is valid.

•  You can also modify the GreatScriptApp file and have it run your xEdit script from Delphi by pressing F9. Make GreatScriptApp look something like this:

program GreatScriptApp;

  {$APPTYPE CONSOLE}

  {$R *.res}

  uses
    Windows,
    Winapi.ShellApi,
    System.SysUtils,
    xEditAPI in 'C:\Games\FO4Edit 3.2\Edit Scripts\xEditAPI.pas';
    GreatScript in 'C:\Games\FO4Edit 3.2\Edit Scripts\GreatScript.pas',

  begin
    try
      ShellExecute(0, Nil, 'C:\Games\FO4Edit 3.2\FO4Edit.exe', '-script:"GreatScript.pas" -nobuildrefs', 'C:\Games\FO4Edit 3.2', SW_SHOWNORMAL);
    except
      on E: Exception do
        Writeln(E.ClassName, ': ', E.Message);
    end;
  end.

13.4 - TES5Edit Global Variables

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

13.5 - TES5Edit Scripting Functions

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).

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).

The relationships between internal types are as follows:

IwbElement

+  IwbContainerBase

+  IwbContainer

| + IwbDataContainer

| | + IwbFileHeader

| | + IwbRecord

| | + IwbGroupRecord

| | + IwbMainRecord

| | + IwbSubRecord

| |

| + IwbFile

|

+  IwbContainerElementRef

IwbResource

IwbResourceContainer

+  IwbBA2File

+  IwbBSAFile

+  IwbFolder

Other Types Used but Unknown

+  TwbDefType

+  TwbElementState

+  TwbElementType

+  TwbGridCell

+  TwbVector

+  TwbFastStringList

+  TGameResourceType

Misc functions

+  DDS

+  NIF

13.6 - Global functions

These functions can be called on anything and should return a meaningful result.

13.7 - IwbElement

These functions can be called on any IwbElement IInterface.

    BeginUpdate(e);
    try
        // do things with e
    finally
        EndUpdate(e);
    end;

    BeginUpdate(e);
    try
        // do things with e
    finally
        EndUpdate(e);
    end;

13.8 - IwbContainer

13.9 - IwbFile

13.10 - IwbMainRecord

13.11 - IwbGroupRecord

13.12 - IwbResource

These functions are used in "Assets browser.pas", "Assets manager.pas", and "Skyrim - List used scripts.pas".

13.13 - Misc functions

13.14 - NIF functions

13.15 - DDS functions

13.16 - Script Structure

13.17 - 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.

13.18 - Hotkeys

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

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

13.19 - 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.

13.20 - Script User Interface

• 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.

TES5Edit appears to provide the following variables:

13.21 - 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.

13.22 - Pascal implementation

TES5Edit uses JvInterpreter from JVCL to execute Delphi as a scripting language. The standard libraries offered by JvInterpreter directly wrap whatever libraries the containing application (xEdit) was compiled with.

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 contain nil 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 implementation 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.

    • And no, Delphi has no equivalent to #pragma once, 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.

• The scripting environment will not throw errors upon encountering the interface or implementation keywords, but it also does not honor them: definitions within the implementation will be available to a file's users. It appears that these keywords are purely semantic.

  • JvInterpreter may encounter parser errors if it finds a forward-declared function or procedure, owing to the lack of Begin and End keywords.
  • JvInterpreter does not throw errors if you redefine a function within the same file, even if the redefinition changes that function's signature. Sometimes, it uses the last definition; other times, however, it uses the first definition.

• JvInterpreter doesn't throw errors if multiple files use the same unit name, but having multiple files use the same unit name will break the parser. Errors like "Error in unit 'UnitName' on line 42: 'begin' expected but 'x' found", where "x" is the middle of another keyword, a variable name, or even a string, are common in this situation.

• JvInterpreter does not short-circuit conditions such as If Assigned(myList) And (myList.IndexOf('Test')) Then; even if the first clause fails, the second will still execute (and end up throwing an exception). You need to nest the conditions: If A Then If B Then C;.

  • A simpler example: If (myInt = 0) Or (otherInt Mod myInt = 0) will yield a divide-by-zero error.

• Be careful when refactoring your code. If you move functions between units, JvInterpreter will not handle this sanely; calling the function on the old unit (i.e. WrongUnit.SomeFunction;) is likely to cause a memory access violation without any intelligible explanation.

13.23 - 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. Pred instead of System.Pred).

The following classes are also extended (or simply offered, if JvInterpreter didn't already offer them):

13.24 - Unsupported language features

13.25 - Unsupported operators

13.26 - Unsupported keywords

13.27 - Unsupported classes and tools