Meshes and materials

esx reads Fallout 4 meshes (NIF) and materials (BGSM and BGEM). In a mesh it edits names, paths, node transforms, connect points and furniture markers. In a material it edits each field. esx does not edit geometry, collision or bone weights. Use a mesh tool for that work.

Each command that writes a file needs -o. Add --dry-run to see the result and write nothing. To read a file from an archive, extract it first with esx resource extract.

Read a mesh

esx nif show Gun.nif
esx nif show Gun.nif --asset-kind texture

nif show lists the blocks, the fields that esx can edit and the arrays that can get or lose an entry. --asset-kind shows the fields of one kind only. The kinds are texture, material and mesh.

A field has a path, for example blocks/0/NiNode/Name. The edit commands take these paths.

Change fields

nif set changes one field, or many fields in one call:

esx nif set Gun.nif blocks/0/NiNode/Name MyReceiver -o Fixed.nif
esx nif set Gun.nif \
  --edit 'blocks/9/BSShaderTextureSet/Textures/0=Textures/Gun/Gun_d.dds' \
  --edit 'blocks/9/BSShaderTextureSet/Textures/1=Textures/Gun/Gun_n.dds' -o Fixed.nif

--edit splits at the first =. --edits FILE takes a JSON list of {"field": ..., "value": ...} objects. Text fields take the text as you give it. Other fields take JSON: a vector is [x, y, z] and a quaternion is [w, x, y, z]. If one edit fails, esx writes no file.

nif set-paths changes path fields by rule. Use it when many fields have the same incorrect folder name:

esx nif set-paths Gun.nif --replace 'textures/OldMod/=textures/NewMod/' --asset-kind texture -o Fixed.nif --dry-run

Each --replace FROM=TO rule replaces FROM with TO in each path field, or in the fields of the --asset-kind that you give. FROM ignores letter case, and / and \ are equal. esx writes TO as you give it. The report lists each changed field with its value before and after.

Connect points

A connect point is the place where a weapon part or a workshop object attaches.

esx nif connect-points Receiver.nif
esx nif connect-points Receiver.nif --copy-from Donor.nif -o Receiver-new.nif --dry-run

Without --copy-from, the command lists the points of a node. With it, the command copies the points of the other mesh and makes the blocks that are missing. The copy keeps the parent names and the local transforms of the donor. Use a donor with the same layout, and check both meshes first. --source-node and --target-node select a node that is not the root.

nif insert adds one entry to an array, and nif remove removes one. nif show gives the array path and the fields of an entry:

esx nif insert Receiver.nif 'blocks/3/BSConnectPoint::Parents/Connect Points' \
  '{"Parent": "", "Name": "P-Scope", "Rotation": [1, 0, 0, 0], "Translation": [0, 2.5, 4], "Scale": 1}' \
  -o Receiver-new.nif
esx nif remove Receiver-new.nif 'blocks/3/BSConnectPoint::Parents/Connect Points' 1 -o Receiver-old.nif

Without --index, the new entry goes to the end. Indexes start at 0.

Furniture markers

esx nif furniture-markers Bench.nif
esx nif furniture-markers Bench.nif --copy-from Template.nif -o Bench-new.nif

The command lists the markers of a node, or copies them from a template mesh. It does not change the marker flags of the FURN record. nif insert and nif remove also work on a marker array.

Materials

esx material show Gun.bgsm
esx material create bgsm -o Gun.bgsm
esx material set Gun.bgsm textures/diffuse 'MyGun/Receiver_d.dds' -o Gun.bgsm --overwrite
esx material set Gun.bgsm two_sided true -o Gun.bgsm --overwrite --dry-run
esx material import bgsm Gun.json -o Gun.bgsm

material show lists each field with its type. material create makes a material with default values, so set its textures before you use it. material set changes one field and keeps the other bytes. A path field takes text, and the other fields take JSON. material import converts the JSON that the Creation Kit and xEdit tools write. The report lists the keys that it did not use.

esx supports material versions 0, 1 and 2. It does not show the result, so check each change in the game.

Find what a file needs

esx resource dependencies 'meshes/weapons/mygun/receiver.nif' --recursive --fail-on-missing

The command reads the textures and materials that a mesh names, and the textures that each material names. It finds each file in the loose folders and the archives, and it lists the files that are missing.