Viewer

esx scene says what a weapon or a mesh consists of: each mesh, each material and each texture, with the file that the game uses for it. It reads the plugin, its masters, the loose files and the archives. It starts no game.

The answer is the scene document. It is the data of the JSON output, and -o writes it into a file. An output file that exists needs --overwrite.

What a weapon consists of

esx scene weapon Fallout4.esm 10mm
esx scene weapon MyGun.esp MyGun -o MyGun.scene.json

The text output has one row for each part, then each file with its source, then the findings:

MyGun [WEAP:00000806] (MyGun.esp)
  model: meshes/weapons/mygun/gun.nif
  SLOT             PART                      NAME               MESH
  ap_gun_Barrel    GunBarrelShort (default)  Short barrel       meshes/weapons/mygun/barrelshort.nif
  ap_gun_Barrel    GunBarrelLong             Long barrel        meshes/weapons/mygun/barrellong.nif
  ap_gun_receiver  GunReceiver (default)     Standard receiver  meshes/weapons/mygun/receiver.nif
Meshes: 4
  loose  meshes/weapons/mygun/gun.nif
  loose  meshes/weapons/mygun/barrelshort.nif
  loose  meshes/weapons/mygun/barrellong.nif
  loose  meshes/weapons/mygun/receiver.nif
Materials: 4
  loose  materials/weapons/mygun/barrel.bgsm
  loose  materials/weapons/mygun/barrellong.bgsm
  loose  materials/weapons/mygun/paint.bgsm
  loose  materials/weapons/mygun/receiver.bgsm
Textures: 4
  loose    textures/weapons/mygun/barrel_d.dds
  loose    textures/weapons/mygun/shared_n.dds
  MISSING  textures/weapons/mygun/nofile_n.dds
  loose    textures/weapons/mygun/receiver_d.dds
Findings: 0 errors, 1 warnings, 0 notes
  warning SCENE_TEXTURE_MISSING: materials/weapons/mygun/barrellong.bgsm names the texture textures/weapons/mygun/nofile_n.dds, and the data folders and the archives do not have this file

The document has these fields:

Field	Content
kind	weapon or mesh.
subject	The plugin, the editor ID and the FormID of the weapon.
root_mesh	The index in meshes of the model of the weapon. null for a weapon with no model.
slots	One entry for each attach point: attach_point, default and parts.
meshes	Each mesh file one time: resource, sha256 and source.
materials	Each material file one time: resource, source and textures.
textures	Each texture file one time: resource, source, format, width, height, mip_levels and cube_map.
findings	The faults and the limits.

A slot has its default part first, then each part that fits the weapon. A part fits when one keyword of its MNAM is a keyword of the weapon, so the list has each part that the workbench can show, not only the parts of the default combination. The default part comes from the default combination of the object template. --combination selects a different combination by its name or by its index from 0. For a mod collection the default part is its first member.

{
  "attach_point": "ap_gun_Barrel",
  "default": "GunBarrelShort",
  "parts": [
    {"record": "GunBarrelShort", "name": "Short barrel", "mesh": 1, "attach_parent_slots": [], "material_swaps": []},
    {"record": "GunBarrelLong", "name": "Long barrel", "mesh": 2, "attach_parent_slots": [],
     "material_swaps": [{"original": "materials/weapons/mygun/barrellong.bgsm",
                         "replacement": "materials/weapons/mygun/paint.bgsm"}]}
  ]
}

mesh is an index in meshes, and it is null for a part with no model. attach_parent_slots has the slots that the part gives to other parts. material_swaps comes from the field MODS of the model of the part and from each property MaterialSwaps of the part.

The files

resource is the Data path in lower case with /. source is the copy that the game uses, as esx resource where gives it:

{"kind": "loose", "path": "/path/to/project/Meshes/Weapons/MyGun/BarrelShort.nif"}
{"kind": "archive", "archive": "/path/to/Fallout 4/Data/Fallout4 - Meshes.ba2", "entry": "Meshes\\Weapons\\10mmPistol\\10MMPistol.nif"}

source is null for a file that no folder and no archive has. A program that reads the document needs no plugin: it reads the bytes of each source.

textures of a material goes from the slot name to an index in textures. The slot names are those of esx material show: diffuse, normal, smooth_specular, grayscale, environment and glow, and base and environment_mask of an effect material.

A shape that names no material file gets a material from its shader block. Such a material has shader with the index of the mesh and the index of the block, source is null, and textures has the textures of the block.

How the parts join

A mesh with the child point C-Barrel goes to the parent point P-Barrel of a mesh that has its place. The case does not count, and the first two characters do not count: 10 vanilla meshes have a child point that starts with P-. The model of the weapon is the first mesh. The transform of a part is the transform of the mesh that has the parent point, then the transform of the node that the point names, then the transform of the point.

A part with a child point and no partner is at the origin, with the finding SCENE_POINT_NO_PARENT. The parts of the slots of such a part join it, so a weapon with no model keeps its form.

On the 268 weapons of Fallout4.esm and of four Creation Club plugins, the rule gives no such finding for the 178 weapons that have a model. The other 90 weapons have no model: they are weapons of robots, turrets and creatures. 13 of them have default parts with meshes, and they have the 21 findings of this code.

Findings

Code	Severity	Condition
SCENE_MESH_MISSING	Error	A model path of the weapon or of a part resolves to no file.
SCENE_MESH_UNREADABLE	Error	esx cannot read the mesh. block has the index of the block, when the reader names one.
SCENE_MATERIAL_MISSING	Warning	A shape names a material file that resolves to no file. The game shows such a shape in pink.
SCENE_MATERIAL_UNREADABLE	Warning	esx cannot read the material file.
SCENE_TEXTURE_MISSING	Warning	A material names a texture that resolves to no file.
SCENE_TEXTURE_UNREADABLE	Warning	The file of a texture is not a DDS file that esx can read.
SCENE_PATH_ABSOLUTE	Warning	A material path or a texture path has a drive letter or starts with / or \. Such a path works only on the computer of the author.
SCENE_POINT_NO_PARENT	Warning	The mesh of a default part has a child point, and no mesh of the other default parts has the parent point of that name.
SCENE_SHAPE_NO_DATA	Note	A shape has no geometry in the file. In the vanilla weapon meshes these are the emitter shapes of effects.
SCENE_NOT_DRAWN	Note	A material has a feature that the renderer does not draw: subsurface light, anisotropic light, back light, rim light, wetness, or an effect material beyond its base texture.

A finding has code, severity, message, part (the editor ID of the first part that uses the file), resource and block. The exit code is 0 when the document has findings.

esx plugin check-weapons checks the records of a weapon: the slots, the recipes and the loose mods. esx scene weapon checks its files. See Meshes and materials.

What a mesh consists of

esx scene mesh Meshes/Weapons/MyGun/Receiver.nif
esx --data '/path/to/Fallout 4/Data' scene mesh Weapons/10mmPistol/10mmPistol.nif -o 10mm.scene.json

The argument is a file on disk, or a Data path that the resource lookup finds. For a file below a folder with the name Meshes, the folder above it is a Data folder, and its materials and textures come first. So a mesh of a project resolves its own files with no option.

The document has one mesh, no subject and no slot:

  model: meshes/weapons/mygun/receiver.nif
Meshes: 1
  loose  meshes/weapons/mygun/receiver.nif
Materials: 1
  loose  materials/weapons/mygun/receiver.bgsm
Textures: 2
  loose  textures/weapons/mygun/receiver_d.dds
  loose  textures/weapons/mygun/shared_n.dds
Findings: 0 errors, 0 warnings, 0 notes

Limits

• The scene of a weapon has the third person model. It does not have the first person model.
• A material swap has the two material paths. It does not have the color remapping index of the swap record.
• esx scene writes a document and draws nothing. esx render draws a picture of a scene: see “Make a picture”. The graphical interface shows a scene and lets you turn it: see “The viewer”.

Make a picture

esx render draws a weapon, a mesh, a material or a texture to a PNG file. It opens no window and starts no game.

esx render weapon Fallout4.esm 10mm --sheet -o build/10mm.png
esx render weapon Fallout4.esm 10mm --part ap_gun_Muzzle=mod_10mm_Muzzle_Suppressor --view side -o build/10mm-quiet.png
esx render mesh assets/Meshes/Weapons/MyGun/MyGun.nif --view side --overlay points -o build/MyGun.png
esx render material assets/Materials/Weapons/MyGun/MyGun.bgsm -o build/MyGun-material.png
esx render texture assets/Textures/Weapons/MyGun/MyGun_s.dds --channel g -o build/MyGun-gloss.png

Option	Meaning
--view	side, other, front, back, top, quarter, or YAW,PITCH in degrees. Repeat it for one file for each view: OUT-side.png, OUT-front.png. Default: quarter.
--sheet	One file with each view in a grid. With no --view, the sheet has the six named views.
--size WxH	The size of a picture, or of one cell of a sheet. Default: 1280x720. Each side is from 1 to 8192.
--channel	lit (default), diffuse, normal, specular, gloss, alpha, vertex-color, uv or parts.
--overlay	A list of points, nodes, bounds and wire.
--background	RRGGBB, or transparent. Default: 141311.
--part	For render weapon: ATTACH_POINT=PART with two editor IDs puts this part into its slot. Repeat it for more slots. esx scene weapon lists the slots and the parts of each.
--overwrite	Replace the output file.

In the side view the camera is on the +X side of the subject, +Y is to the right of the picture and +Z is up. The yaw turns the camera about Z from +X to +Y, and the pitch lifts it. The camera moves back until the subject fills the picture.

A channel shows data in place of the lit material. In normal, specular, gloss, alpha, vertex-color and uv, a byte of the picture is the value of the data. normal is the direction of the surface after the normal map: red is X, green is Y, blue is Z. uv is a grid of 8 by 8 cells for each unit of UV. parts gives each mesh its own color.

An overlay is on top of each shape. A parent connect point is a filled diamond and a child connect point is a square, both in the accent color #ff6a1a. A node has its three axes: X in red, Y in green, Z in blue.

The JSON result:

Key	Content
pictures	The path, the width, the height and the view of each file. A sheet has cells with the place of each view.
scene.meshes	Each mesh with its source, its parent points and its child points.
scene.placements	The place of each mesh, and join: the child point, the parent point and its node.
scene.materials, scene.textures	Each file with its source. A texture has loaded.
scene.shapes	Each shape with its mesh, its block, its material, and pixels: the number of pixels that show it in each view.
markers	The pixel position of each connect point and each node in each picture.
findings	The findings of the scene, with the codes of esx scene.
adapter, times	The graphics adapter, and the time of each step in milliseconds.

A material file that is missing and a diffuse texture that is missing are pink, as in the game. findings has SCENE_MATERIAL_MISSING or SCENE_TEXTURE_MISSING with the path.

esx render texture writes the pixels of a DDS file with no light: --channel rgb, r, g, b or a, --mip N for a mip level, and --face N for one face of a cube map. With no --face, a cube map gives its six faces in one picture. This command needs no graphics adapter.

The other three commands need a graphics adapter: Vulkan on Linux, DirectX 12 on Windows. With no adapter the error has the reason RENDER_NO_ADAPTER. On a computer with no graphics card, install a software adapter (vulkan-swrast on Arch Linux, mesa-vulkan-drivers on Ubuntu). ESX_RENDER_ADAPTER=software selects it when the computer has both.

The viewer

The viewer is a view of the graphical interface esx-gui: see Interface. It shows the scene of esx scene with the renderer of esx render, so a person sees the picture that an AI agent gets from the command. Start it with esx gui, then select Viewer (Ctrl+1).

Open a subject

Type into the line Open and press Enter.

Text	Subject	What the viewer runs
Fallout4.esm 10mm	A weapon: a plugin and an editor ID or a FormID.	esx scene weapon Fallout4.esm 10mm
Meshes/Weapons/10mmPistol/10mmPistol.nif	A mesh: a file on disk, or a Data path.	esx scene mesh with the path
Materials/Weapons/10mmPistol/10mmPistol.BGSM	A material on a sphere: a file on disk, or a Data path.	esx render material with the path. The command finds the textures of the material.
assets/Textures/Weapons/MyGun/MyGun_d.dds	A texture: a file on disk.	Nothing. The viewer reads the file.

Put quotes around a path with a space. With an open project, a path is a path in the project folder, and each command runs in that folder.

With an open project that has a release, the left panel also has the weapons of the plugin of the release: esx plugin records build/release/MyMod.esp --sig WEAP gives the list. Type in the filter (the key /) and select a weapon. A project with no release shows NOT_BUILT: build the project first.

The viewer reads each file that the scene document names: a loose file, or an entry of an archive of the game. It reads the installed game and does not write into it.

The window of the viewer

Area	Content
Left panel	The line Open, the weapons of the project, and one group for each slot of the weapon with its parts.
Picture	The subject, with two rows below it: the six views and the four overlays, then the nine channels. The word Preview is at the right: the picture is not the renderer of the game.
Lines below the picture	The esx render command that gives the same picture, the number of mesh files, joins and texture files, the findings, and the size of the picture with the time of the draw.
Right panel	The material with its textures, the findings, the nodes of one mesh, and the values of the material.

Ctrl+[ closes or opens the left panel, and Ctrl+] the right panel.

Slots and parts

A click on a part puts it into its slot. The picture changes with no new command: the scene document has each part that fits the weapon. The keys [ and ] select the last and the next part of the slot of your last click.

A slot is in the list when no part gives it, or when the part of a slot in the list gives it. The muzzle parts of the 10mm pistol are in the list because each barrel gives the slot ap_gun_Muzzle. For a receiver that gives no barrel slot, the list has no barrels.

The picture has the placements of esx render weapon with one --part option for each part that is not the default part. The two use the same join. The picture also shows the default part of a slot that is not in the list, as esx render weapon does.

The camera

Input	Effect
A drag with the left button	Turns the subject.
The wheel	Moves the camera near and far.
A drag with the middle button	Moves the point that the camera looks at.
1, 2, 3, 4	The views side, front, top and quarter. The row below the picture also has other and back.
F	The subject fills the picture again.

The renderer draws on its own thread, and the view shows the last picture until the next one is ready. The viewer measures the time from a camera change to the paint of the new picture. When that time is more than 33 ms, a drag draws at half size, and the picture has its full size again at the end of the drag.

Channels, overlays and marks

C and Shift+C select the next and the last channel. P, N, W and B switch the overlays points, nodes, wire and bounds. The channels and the overlays are those of esx render: see “Make a picture”.

The right panel has the tree of one mesh: each node with its shapes and its parent points, and the child points of the mesh. A click on a node or on a point puts a ring at its place in the picture. A click on a shape in the picture marks the shape in the tree, and the material panel shows the material of that shape. The tree shows the mesh of the mark, or the mesh of the part of your last click.

The material panel

The panel shows one material: its file name and its source, and each texture with its slot, its format, its size, a small picture and its source. A source is a path in the project, a path on disk, or the file name of a game archive such as Fallout4 - Textures3.ba2. A texture or a material with no file is red and has the text missing. The section Material values has each field that the renderer uses, with the names of esx material show.

The scene of a material file comes from esx render material, which gives no texture format. So the panel of a material file shows the size of each texture and not its format.

Findings

The right panel has each finding of esx scene, the errors first. A click on a finding goes to its subject: the node or the shape of its block, its material, its texture, or its part. SCENE_POINT_NO_PARENT shows for the parts of your selection, not only for the default parts.

The command and the picture file

Copy esx render command puts the command line below the picture into the clipboard:

esx render weapon Fallout4.esm 10mm --part ap_gun_Barrel=mod_10mm_Barrel_LightPortedShort --part ap_gun_Muzzle=mod_10mm_Muzzle_Suppressor --view side --overlay points -o 10mm.png

The command has the parts, the yaw and the pitch of the view, the channel and the overlays. esx render has no option for a camera distance, so its picture shows the full subject also when you moved the camera near.

Save picture asks for a file and writes the picture of the view as a PNG file. The viewer does not write a picture into the game folder of the settings.

File changes

The viewer watches the folder of each loose file of its scene. When a mesh, a material or a texture changes on disk, the viewer runs its command again and reads the files again. The camera, the parts, the channel and the mark stay.

What the viewer does not do

• It shows no animation, no collision, no first person view and no armor on a body: see “What the picture does not show”.
• It does not mark a selected shape in the picture. The tree and the material panel show it.
• It has no test in a real window. The tests draw the view with no window on Linux.

What the picture does not show

The picture is a preview. It is not the renderer of the game, and the result has preview: true.

Subject	In the picture
Light	One key light above the camera and to its left, one fill light, and the cube map of the material. The lights move with the camera. The game has the light of its cell, so a game picture of the same weapon is darker and has another tint.
Material features	Diffuse, normal map, specular and glossiness, grayscale to palette, cube map, alpha test, alpha blend, two sided, glow, UV offset and scale.
Not drawn	Subsurface light, anisotropic light, back light, rim light, wetness, and an effect material (BGEM) beyond its base texture. findings has SCENE_NOT_DRAWN for each.
Parts of a weapon	The default part of each slot, or the part of --part ATTACH_POINT=PART. A part that is a material swap changes the material of each mesh.
A shape with no material file	A material from the values and the textures of its shader block.
Skin	A skinned mesh is drawn in the pose of its file, with no bone transform. Armor on a body is not possible.
Collision, animation, the first person view, the scope view, the item name	Not in the picture.

For a check of the palette lookup, the picture of the vanilla 10mm pistol was compared with a picture from the game: the steel and the rust areas are at the same places.

A game test with esx probe stays the proof. See Game test.