Bulk edits

A bulk edit changes many records by one rule. You write the edit rule in a Rhai file. esx rhai run runs the Rhai file on the records of a plugin. The functions have the same names as in xEdit. esx does not run Pascal source from xEdit. Port the syntax to Rhai and check each function with esx rhai api.

For Papyrus, see the Papyrus commands.

Run

esx rhai api
esx rhai run MyPatch.esp prefix.rhai --sig WEAP --param 'prefix="Patched "'
esx rhai run MyPatch.esp prefix.rhai --sig WEAP --param 'prefix="Patched "' --apply -o Edited.esp

The first run is a preview. It changes records in memory only. Add --apply to save. esx saves only if the whole Rhai file succeeds. A compile error, a runtime error, a nonzero hook result or an operation limit prevents the save. Messages from print, debug and AddMessage appear in the JSON report.

Example

let changed = 0;

fn Initialize() {
    AddMessage("Starting");
    return 0;
}

fn Process(e) {
    if ElementExists(e, "FULL") {
        let old = GetElementEditValues(e, "FULL");
        SetElementEditValues(e, "FULL", params.prefix + old);
        changed += 1;
    }
    return 0;
}

fn Finalize() {
    AddMessage(`Changed ${changed} records`);
    return 0;
}

Global code runs once. Then the hooks run in this order: Initialize(), Process(record) for each selected record, and Finalize(). Each hook returns () or 0. An error stops the run at once.

Select records

By default, the Rhai file processes the non-header records of the target plugin.

Option	Effect
--sig WEAP	Process one signature.
--record edid:MyWeapon	Process one record. Repeat the option for more records.
--param key=value	Set a value in params.
--max-operations N	Set the operation limit.

If you use --sig and --record together, esx selects the records that match both. esx selects the records before the run starts. A copy that the edit rule creates does not get a Process call.

Reports

A Rhai file can also read records and change none. Then the run is a read-only report. Write each result with AddMessage, and do not add --apply.

fn Process(record) {
    let count = ReferencedByCount(record);
    AddMessage(`${Name(record)}: ${count} incoming references`);
}

esx rhai run MyMod.esp references.rhai --sig WEAP

The JSON report has the lines in messages. Without --apply, esx saves nothing.

Not supported

Pascal source and the full xEdit and VCL API are not supported.