Editing records

Every command on this page saves the plugin. Add --dry-run to test a change first.

Create and change

esx record create MyMod.esp KYWD --edid MyKeyword
esx record set MyMod.esp edid:MyWeapon 'DNAM\Damage' 42
esx record remove MyMod.esp edid:OldThing

record create fills the new record with the default values from its definition. Set the other fields before you use the record in the game.

Copy

By default, record copy makes an override. Add --as-new to make a new record. esx adds the missing masters. It also copies parent records, such as the CELL of a reference, as overrides.

esx record copy MyMod.esp edid:SourceCell --from Source.esp
esx record copy MyMod.esp edid:SourceCell --from Source.esp --as-new --deep --edid CopiedCell

--deep copies the child groups. It also remaps the references inside the copy.

FormIDs and references

esx record change-formid MyMod.esp edid:MyItem 01000F00
esx record retarget MyMod.esp edid:OldKeyword edid:NewKeyword
esx plugin renumber MyMod.esp

change-formid updates the overrides and all references in the loaded plugins. retarget replaces references to the first record with references to the second.

Deleted and partial records

esx record set-deleted MyMod.esp 0001F4A2 true
esx record set-partial MyMod.esp edid:MyQuest true

Use false as the value to restore the record.

Batch

esx batch runs a list of changes from a JSON file. All changes use one session and one save. If one change fails, esx saves nothing. Use --keep-going to change this behavior.

A batch file can make the records of a mod without a Rhai file. This example makes a weapon from the vanilla .44, with its own ammunition and keyword:

{
  "plugin": "MyMod.esp",
  "ops": [
    { "op": "create", "signature": "KYWD", "edid": "MyFamily" },
    { "op": "copy", "record": "edid:Ammo44", "from": "Fallout4.esm", "as_new": true, "edid": "MyAmmo" },
    { "op": "copy", "record": "edid:44", "from": "Fallout4.esm", "as_new": true, "edid": "MyGun" },
    { "op": "set", "record": "edid:MyGun", "path": "FULL", "value": "My Gun" },
    { "op": "set", "record": "edid:MyGun", "path": "DNAM\\Ammo", "value": "edid:MyAmmo" },
    { "op": "set_native", "record": "edid:MyGun", "path": "DNAM\\Capacity", "value": 6 },
    { "op": "set_flag", "record": "edid:MyGun", "path": "DNAM\\Flags", "flag": "Bolt Action", "value": false },
    { "op": "append", "record": "edid:MyGun", "path": "Keywords\\KWDA", "value": "edid:MyFamily" }
  ]
}

esx batch changes.json --dry-run
esx batch changes.json

Operation	Effect
set	Set the edit value of each element that the path selects.
set_native	Set each selected element’s native value to a number, text or bool.
set_flag	Set one named flag with true or clear it with false. The other flags do not change. The result lists the changed flags and all flags that are set.
add	Add a member, such as a subrecord, to a record or a struct.
append	Add an entry at the end of a list: empty, or a copy of the entry at from. Then set its value and its fields.
remove_element	Remove each element that the path selects.
create	Make a new record with the default values of its definition, as record create.
copy	Copy a record as an override, or as a new record with as_new and edid. An optional set map then sets values in the copy.
remove_record	Remove a record.
change_formid	Change the FormID of a record and of the references to it.
add_masters, clean_masters, sort_masters	Change the master list.
clean	Remove identical-to-master records and undelete references.

A value edid:Name in a FormID field refers to the record with that editor ID. See Records and paths. Create or copy a record before an operation refers to it. Paths take the entry selectors of Records and paths.

append can copy an entry and change it in one operation:

{ "op": "append", "record": "edid:MyMod", "path": "DATA\\Properties",
  "from": "DATA\\Properties\\[Property=Keywords]",
  "fields": { "Value 1": "edid:MyNode" } }

In fields, text is an edit value, and a number or bool is a native value.

copy takes a set map with the same value rule. Paths refer to fields in the copy. esx sets their values in document order:

{ "op": "copy", "record": "edid:Ammo44", "from": "Fallout4.esm", "as_new": true, "edid": "MyAmmo",
  "set": { "FULL": "My rounds", "DATA\\Value": 3 } }

One records file for each build folder

A records file is a batch document that makes the records of a mod. --plugin PATH overrides the document’s plugin value, which you can then omit. A top-level create object makes the plugin if its file does not exist. It accepts the options of plugin create as keys. Each key is optional:

{
  "create": { "masters": ["Fallout4.esm"], "light": true, "esm": false, "author": "Me" },
  "ops": []
}

esx batch records.json --plugin MyMod.esp -o build/MyMod.esp

The new file goes to -o. Without -o, esx uses the plugin path as written. A bare plugin name goes into the --data folder if supplied, or the current directory otherwise. This follows the same rules as plugin create. When the plugin file exists, create does nothing.

In a project folder, put the records files in records/. esx build makes the plugin and applies each file in file name order. Then a records file needs no plugin value and no create object.