UAssetGUI: taking Unreal Engine assets apart by hand

Reaching inside a cooked .uasset without the editor

Unreal Engine packages its game content into binary assets. Textures, meshes, sound and level data land in .uasset and .umap files whose contents are not meant to be read by a person. UAssetGUI exists to break that barrier open. Its own description is narrow and worth repeating: a tool designed for low level examination and modification of Unreal Engine game assets by hand.

That is a different job from modding a game through a script or a framework. UAssetGUI does not ship level logic, spawn entities, or patch a running process. It parses a file into a structure a human can read, lets you change fields, and writes the file back. The topics the project lists confirm the shape of it: c-sharp, gui, json, modding, modding-tools and unreal-engine. A JSON topic next to a modding topic is the clearest hint of the workflow, because the JSON is the interchange step. A file goes in, a JSON document comes out, you edit the document, and the tool turns it back into an asset.

The audience is therefore narrow on purpose. Modders working on titles whose cooking rules are not public need a way to see what a cooked file actually contains. Engine programmers need to reproduce an asset problem outside the editor, where a real editor session would be slow and heavyweight. Both groups get the same low level access, and neither gets a content authoring workflow.

The tojson and fromjson pair replaces the GUI window

The interesting part of UAssetGUI is that the GUI is optional. The command line exposes an export and an import path, so an asset can be converted to JSON, edited with any text tool or script, and converted back, all without opening a window. The syntax is short:

UAssetGUI tojson <source> <destination> <engine version> [mappings name]

UAssetGUI fromjson <source> <destination> [mappings name]

Export takes the asset, the destination JSON path, and the engine version. Import takes the JSON and the destination asset path. The direction names mirror the two halves of a pipeline, which makes a script easy to read. A concrete pair from the documentation shows the intended cycle, exporting with a mappings file and then importing the result back into an asset name:

UAssetGUI tojson A.uasset B.json 5.1 "C:\Mappings.usmap"

UAssetGUI fromjson B.json A.umap ./Mappings.usmap

The second pair of examples uses the other style of version and of mappings reference:

UAssetGUI tojson A.uasset B.json VER_UE5_1

UAssetGUI fromjson B.json A.umap Outriders

One asymmetry is worth noticing. Export requires the engine version, import does not, because the version is already carried inside the JSON document that came out of the export. You can also point the GUI straight at a file:

UAssetGUI [file name] [engine version] [mappings name]

Passing a file name, a version and a mappings name in one launch, for example `UAssetGUI test.uasset VER_UE5_4 Bellwright`, is the fastest way to open the same asset the script would have processed.

Three ways to name the engine version, and what that costs you

Cooked assets are version specific, so the tool insists on knowing which engine version produced the file. Three notations are accepted, and they are not equally available. A string in major.minor form, such as `4.23` or `5.3`, works only in v1.1.1 and later. An EngineVersion enum entry, such as `VER_UE4_23` for 4.23 or `VER_UE5_0` for 5.0, works in every version. An integer also works everywhere, where `23` means 4.23 and `29` means 5.0.

That split is a real trap for anyone scripting against a pinned build. The v1.1.0 release is the current stable tag, and its era of the documentation does not include the readable minor version form. If your script says `5.1` and your users run the stable release, the call fails on syntax before it ever touches the asset. The enum form is the safe denominator, because it works in all versions.

The same versioning caveat applies to the mappings argument. A mappings file can be given as a path on disk with an extension, which the documentation marks as v1.1.1 and later only, or as the name of a file inside the UAssetGUI Mappings config directory with no extension, which works in every version. Note the third example above, `Astro` or `Outriders`, is that second form: a bare name, not a path. Mappings are optional, but when they are needed for a game with encrypted asset names, choosing the path form on an older build is another silent version mismatch.

On Linux the project routes you through Wine and winetricks

UAssetGUI is a Windows shaped tool, so the documented Linux route is Wine, and the setup is specific enough to copy. The instructions were tested using Wine 11.0. You need the latest UAssetGUI.exe binary from the Releases page, the latest Wine, and the latest winetricks. On Debian and Ubuntu the documentation tells you to follow the Manual Install steps on the winetricks page so the tool is current. Then you install the pre-requisites on the command line:

winetricks dotnetdesktop10 micross

The pre-requisite name changes with the build of the tool. For UAssetGUI v1.1.0 and lower the command is:

winetricks dotnetdesktop8 micross

And for UAssetGUI v1.0.0.0-alpha.8 and lower it is:

winetricks dotnet472 micross

After the prompts finish, the tool launches through Wine:

wine UAssetGUI.exe

The `micross` token is what the project tells people to install alongside the.NET desktop runtime. This is the price of using the tool on a non-Windows machine, and it is a real one: a.NET desktop runtime, a compatibility layer, and a dependency installer all have to behave correctly before the program starts. The stable Windows binary is the far simpler path, and the project also publishes an experimental build with every new commit, which the documentation suggests for people who hit problems with the stable release.

Portable mode keeps every setting in a Data folder beside the binary

UAssetGUI can be run without installing it into a user profile. In portable mode, all configuration files and saved mappings are stored in a Data folder next to the executable, which lets the tool run from a USB drive or other portable media. The feature is available in v1.1.0 and higher, so it is present in the current stable release but not in the older builds.

The switch is a single parameter:

UAssetGUI portable

The behaviour after that is slightly unusual and worth knowing. Once UAssetGUI has been launched in portable mode at least one time, it can be executed normally with no parameters and it stays in portable mode. So the first run is a one-time setup step, and every later launch is just the executable. Turning the feature off is also a file operation rather than a command: delete the Data folder next to the UAssetGUI executable and the tool returns to normal operation.

For a shared workstation this is the cleanest option, because nothing is written to the user profile. For scripted use it also means the mappings and configuration travel with the tool, so a mappings directory can be carried alongside the binary and referenced by bare name.

Compiling from source starts with Visual Studio 2026 and the .NET 10 SDK

Building the project yourself is a Visual Studio workflow rather than a dotnet CLI workflow. The listed prerequisites are Visual Studio 2026 or later with the .NET 10.0 SDK, and Git. The repository is cloned, submodules are pulled, and the solution is opened in the IDE:

git clone https://github.com/atenfyr/UAssetGUI.git

cd UAssetGUI

git submodule update --init

After that the steps are inside Visual Studio: open `UAssetGUI.sln`, right click the UAssetGUI project in the Solution Explorer and choose Set as Startup Project, right click the solution name and press Restore Nuget Packages, then press Start or F5. There is no headless build command in the documentation, so a continuous integration job on a machine without Visual Studio is not covered. The submodules step matters: the top level entries include a UAssetAPI directory and a `.gitmodules` file, and a clone without initialised submodules will not have the parsing layer the GUI depends on.

Building the GUI is not the same as building the parser. Bug reports about assets that fail to maintain binary equality are directed to the UAssetAPI issue tracker rather than the UAssetGUI one, which places the binary format work in the UAssetAPI project that sits inside this repository.

Where the round trip gets fragile: mappings and binary equality

The honest limit of UAssetGUI is that a parse and re-parse cycle has to reproduce the original bytes. The project names the failure mode directly: an asset can display failed to maintain binary equality. The documentation does not explain the cause, the tolerance, or the settings that affect it, so anyone building a pipeline on this needs to know that equality checking is part of the intended behaviour rather than a bug report waiting to happen.

Mappings are the other pressure point. A mappings file tells the tool how the game renamed assets, and it is optional only for games that do not need one. When a mappings file is required and missing, an asset will not parse into something meaningful, and the resulting JSON is the artifact you would hand to a human, so the failure is not always obvious at the point it happens. The documentation also states that an issue will not be reviewed if no test assets are provided, unless the issue is completely unrelated to asset parsing. In other words, the project expects you to bring the exact asset, the game name, the engine version it was cooked with, and a mappings file if needed.

The other limitation is scale and intent. UAssetGUI is for hand work on individual files. There is no bulk processing command, no asset validation pipeline, and no cooking. Anything requiring the engine's full serialization rules, or requiring a live editor session, belongs to Unreal Engine itself.

MIT licensing, two repositories, and a policy against generated patches

Licensing is simple and permissive. UAssetAPI and UAssetGUI are distributed under the MIT license, and the text sits in the LICENSE file at the top level of the repository. The project describes itself as mature, stable software, and the topics and release history are consistent with a tool that has been shipping for a while. The last push to the default branch was on 2026-10-19, and the stable tag v1.1.0 was published on 2026-05-01, with an experimental tag following the most recent commits. The README also states that UAssetGUI is mature, stable software.

Contributions follow a stricter path than the licence suggests. The project does not accept AI-generated code on the UAssetAPI or UAssetGUI repositories, and pull requests containing generated code, text or documentation will not be reviewed. All changes are expected to be tested and reviewed by a human. That is unusual but coherent for a parser whose correctness is measured in bytes, and it means a fork or a patch set is a more realistic route than an upstream pull request if you need a change.

For an engineering decision, the practical read is this. A permissive licence and a slow, careful review process mean the code is easy to adopt and hard to influence.

Editorial conclusion

UAssetGUI is worth adopting when a cooked asset has to be read or rewritten without launching the engine, and the JSON round trip fits into a script. It is the wrong tool when you need full editor semantics, live blueprint editing, or a working asset on a machine without the .NET desktop runtime and Wine. Before you commit, verify that your game version has a mappings file you can use, and that a re-exported asset still passes the binary equality check the project warns about.

Frequently asked questions

Official sources

1. atenfyr/UAssetGUI on GitHub
2. Issues
3. License: MIT
4. README
5. Releases