Interface

esx-gui is the graphical interface of esx. It is a second program beside esx. The interface changes a project only through commands of esx, and it shows the command line of each action. An AI agent and a person can then do the same work: the agent runs the commands, and the person sees the result.

This version has the shell (the window, the command list and the settings), the project view with the build of a project and its checks, and the viewer. The changes view shows what changed since the last build and since the last commit. The game test view has a place in the navigation and no content.

Install

A release package has the two programs, esx and esx-gui, in one folder. Keep them together.

esx-gui looks for esx in three places, in this order:

1. The folder of esx-gui.
2. The path of esx in the settings.
3. Each folder of the PATH variable.

On Linux the interface needs a Vulkan driver and the libraries of X11 or Wayland of the desktop. esx needs none of them.

Start

esx gui
esx gui path/to/mymod
esx-gui path/to/mymod

esx gui looks for esx-gui beside esx and then in each folder of PATH. It starts the program and ends. The interface runs on its own. The variable ESX_GUI_PROGRAM names the program and stops the search.

With no esx-gui program the command gives the code NOT_FOUND, the exit code 3 and the reason GUI_NOT_INSTALLED:

{"ok":false,"command":"gui","error":{"code":"NOT_FOUND","message":"the program esx-gui was not found, so the graphical interface is not installed","hint":"put esx-gui beside esx or into a folder of the path, or name it with the variable ESX_GUI_PROGRAM. A release package has the two programs","details":{"reason":"GUI_NOT_INSTALLED","searched":["/opt/esx/esx-gui"]}}}

The window

Area	Content
Top bar	The logo, one link for each view, the project folder, Commands, Settings and one button. The button is Open project with no project and Build with a project.
View	The content of the selected view.
Status line	The plugin of the project, the state of the plan, the issues of the checks, the result of the last command and the version of esx. A click on the result of the last command shows it again.

Open a project

A project is a folder with the sources of one mod. See Project.

Select Open project (Ctrl+O) and select the folder, or give the folder to esx gui. The interface runs esx build --dry-run in the folder and shows the plan: each source, each step with its inputs and outputs, and each file of the release. The dry run writes nothing and starts no command.

The interface watches the project folder. When a source file changes, it reads the plan again. It does not read a change in build/cache or in .git. F5 reads the plan again at each time.

Build (Ctrl+B) runs esx build --progress in the project folder. The project view shows one row for each step and then the checks of the release. See Build and check a project.

A project can have shell commands of its author in the [build] table of esx.toml. Before the first build of such a project, the interface shows each command and asks. It keeps the answer for that folder and that text. A change of the commands asks again.

The command list

Ctrl+K opens the list. It has each command of esx commands with its help. Type words to filter the list: each word must be in the name or in the help of a command. Enter opens the page of the selected command.

The page of a command has its help, its usage line, an argument line, its examples and its arguments. Type the arguments as in a terminal, with quotes around a value that has a space. A click on an example puts its arguments into the line. Enter or Run starts the command. The interface gives --format json to the command. With an open project the command runs in the project folder.

The result has these parts:

Part	Content
Command line	The full command line of the process. Copy as command line puts it into the clipboard.
Result	ok with the time, or the error code with the exit code.
Error	The code, the message, the hint and the reason of error.details.reason.
Warnings	The code and the message of each warning.
Result tree	The JSON data as a tree. A click opens or closes an object or an array. An object or an array shows 200 entries.

Stop ends the process of a command that runs. One command runs at a time: a second command waits.

The viewer

Viewer (Ctrl+1) shows a weapon, a mesh, a material or a texture. Type a file, or a plugin and a weapon, into the line Open and press Enter: Fallout4.esm 10mm. With an open project that has a release, the left panel has the weapons of its plugin.

The viewer runs esx scene weapon or esx scene mesh, reads each file that the scene document names, and draws the picture with the renderer of esx render. A click on a part of a slot changes the picture with no new command. The right panel has the material with each texture, the findings, and the tree of a mesh with its nodes and its connect points.

A drag turns the subject, the wheel moves the camera near and far, and a drag with the middle button moves the point that the camera looks at. The line below the picture is the esx render command that gives the same picture. Copy esx render command puts it into the clipboard. Save picture writes the picture into a PNG file that you select. It does not write into the game folder.

The picture is a preview. It is not the renderer of the game. Viewer has each function of the view in the section “The viewer”.

Safety

• The interface writes two things of its own: its settings file, and files in its cache folder. Each other write is a command of esx.
• The interface never gives --allow-game-folder, and it has no setting for it. A command line with that option does not start. A command that fails with GAME_FOLDER_WRITE shows the reason and its command line.
• The interface gives --overwrite only after a question. A command that fails with OUTPUT_EXISTS gives the question “Replace the file?” with the file name. Replace runs the command again with --overwrite. A command line that has --overwrite gives the question before the command starts.

Build and check a project

The project view (Ctrl+2) has the composition of a build: the sources at the left, the build in the center, the release at the right, and the checks below.

Area	Content
Your project	Each source by its place: the manifest, the base plugin, the item files, the records files, the behavior sources, the asset folders and the Papyrus sources. A source has the accent line while its step runs.
The build	Before the first build, the plan of esx build --dry-run. After a build, one row for each step with its state, its main number and its time. The last line is the command that Build runs.
Your release	Each file of build/release with its size, the state of the ID lock, the count of new records against the light plugin limit, and the result of the checks.
Checks	One row for each section of esx release check, with its result and its first finding.

A click on an asset folder shows its first 40 files. A click on a text source shows its first 400 lines in the panel at the right. A click on a mesh, a material or a texture gives the file to the viewer.

Build

Build (Ctrl+B) runs esx build --progress in the project folder. Three options change the line:

Option	Effect
--full	The build reuses nothing.
--until STEP	The build stops after this step.
--skip STEP	The build leaves this step out. Select more than one step if necessary.

The states of a row are waits, runs, the main number of the step, skipped, not selected, failed, stopped and not reached. A step that took its output from an earlier build has reused or reused in part after its number. Stop ends the process of the build. The step that ran is then stopped.

A click on a row opens the report of the step below the build: its inputs, its outputs, its warnings, its error and its short report as a tree. When a step before check fails, its report opens at once. The error line of the build has the error code and the reason of error.details.reason, for example ISSUES_FOUND RELEASE_ISSUES.

When a project opens, the interface reads build/reports/build.json and build/reports/check.json. So the view shows the last build and its checks, also when a terminal or an agent ran that build. F5 reads the two files again.

Checks

The last step of a build runs each check, and the interface reads its report from build/reports/check.json. Check the release runs esx release check on the plugin in build/release. With no release it uses the plugin in build/candidate.

The table has the checks with an issue first, then the checks with a warning, then the others. A section that this version of the interface does not know shows its issue count, and a click opens its report as a tree.

A click on a row opens the check below the table and its first finding in the panel at the right. The panel has these parts:

Part	Content
Finding	Issue or Warning, the code and the text. A finding with no code of esx has the word of the report, for example missing.
Links	Each record and each file of the finding.
Command of the full report	The command of the section, for example esx plugin assets build/candidate/MyMod.esp --recursive --include-companions.

A link to a record runs esx record show PLUGIN RECORD --compact and shows each value with the path that record set takes. A link to a mesh, a material or a texture opens the viewer. When an asset folder of the project has the file, the viewer gets that file. Esc closes the panel. In a window of less than 1280 pixels the panel is above the right part of the view.

The status line has the number of issues and the count of new records, for example 1 issue 19 of 2,048 records.

Settings

Settings (Ctrl+,) has three values.

Value	Use
Path of esx	The esx program, when it is not beside esx-gui and not on the path.
Game folder	The folder with Fallout4.exe. Each command gets the Data folder of it in ESX_DATA. The interface reads the game and does not write into it.
Scale of the text	90, 100, 110, 125 or 150 percent.

System	Settings file	Cache folder
Linux	~/.config/esx/gui.toml	~/.cache/esx/gui
Windows	%APPDATA%\esx\gui.toml	%LOCALAPPDATA%\esx\gui\cache

On Linux, XDG_CONFIG_HOME and XDG_CACHE_HOME replace ~/.config and ~/.cache. The variables ESX_GUI_CONFIG_DIR and ESX_GUI_CACHE_DIR replace the two folders. You can delete the cache folder at each time.

See what changed

The changes view (Ctrl+4) shows what changed in the project: files, records and pictures. A person who works with an AI agent sees the changes of the agent there. The line at the top counts them: 2 files changed since the build of 14:02. 2 records and 1 picture changed in that build.

List	Content	Source
Files	The source files that changed since the last build that passed, or since the last commit. A is a new file, M a changed file, D a removed file and R a file with a new name.	The size and the time of each file, or git status --porcelain=v1
Records	The records that the last build added (+), changed (~) or removed (-), against the build before it.	esx plugin diff
Pictures	Each mesh and each material of the release that the last build added, changed or removed.	The general archive of each of the two builds

Select the start of the file list in the left panel: The last build or The last commit. The second choice is there when the project folder is in a git repository and the computer has git. The interface starts git status with a time limit of 5 seconds. It reads the repository and writes nothing into it. The output folder of the build and the folder .git are not sources.

A click on a row shows its details in the right panel:

Row	Details
A text file	The first 120 lines of the file.
A mesh, a material or a texture of the sources	The file opens in the viewer.
A changed record	Each changed field with its path, its value before and its value after.
A mesh or a material of the Pictures list	The picture before and the picture after, each 512 by 512 pixels, and the button Open in the viewer.

esx render mesh and esx render material draw the two pictures from the archives of the two builds. The view shows the command line of each picture and of esx plugin diff. A picture is a preview, as in the viewer.

The two builds in the cache folder

A build is new when build/state.json has a new key of the check step. See What a build reuses. The interface then puts the files of build/release/ into its cache folder, and it keeps the build before it. So the view compares the last two builds that the interface saw while a project was open. The build can come from the Build button, from a terminal or from an agent. With one build in the cache, the Records list and the Pictures list say that the next build fills them. Settings has the place of the cache folder. You can delete it.

The view reads no file content for the Files list. For a project with 1,000 asset files of 761 MB, one read takes 3 ms, and 17 ms with git status. A new build with 500 meshes and materials in its archive takes 110 ms one time, because the view reads that archive. state.json has the SHA-256 of each archive, so two builds with the same archives need no read.

Keys

Key	Action
Ctrl+K	The command list
Ctrl+O	Open a project
Ctrl+B	Build the project
Ctrl+,	The settings
Ctrl+1	The viewer
Ctrl+2	The project view
Ctrl+3	The game test view
Ctrl+4	The changes view
F5	Read the project again
Ctrl+Shift+C	Copy the command line of the last action
Esc	Close a question, a command page or a panel
Arrow keys, Enter	Move in the command list and open a command
Tab, Shift+Tab	The next and the last control

The viewer has these keys while it is the view. A key has no effect while you type in a text line of the viewer.

Key	Action
1, 2, 3, 4	The side view, the front view, the top view and the three quarter view
F	Fit the picture to the subject
P, N, W, B	The connect points, the axes of each node, the wireframe and the bounds
C, Shift+C	The next and the last channel
], [	The next and the last part of the active slot
Ctrl+[, Ctrl+]	Close or open the left panel and the right panel
/	The filter of the weapon list

The changes view has these keys while it is the view.

Key	Action
Down, Up	The next row and the row before, through the three lists
Enter	Open the selected file or asset in the viewer
Ctrl+[, Ctrl+]	Close or open the left panel and the right panel

What this version does not do

• The viewer shows no animation, no collision and no armor on a body. See Viewer.
• It does not write the ID lock. Run esx build --update-lock in a terminal or from the command list.
• It does not accept a finding of the release check. The [release] table of esx.toml declares the loose files and the overrides that a mod needs.
• It does not show the pictures of a game test. See Game tests.
• The changes view shows no difference of the text of a file, and no picture of a changed texture. git diff shows the text.
• The changes view compares only builds that the interface saw. A build that ran while no project was open in the interface is not kept.
• It does not edit a record. Each edit is a command: see Editing.
• It has no test in a real window on Windows or on Wayland yet.