# UAssetGUI
[](https://github.com/atenfyr/UAssetGUI/releases/latest)
[](https://github.com/atenfyr/UAssetGUI/releases)
[](https://github.com/atenfyr/UAssetGUI/issues)
[](https://github.com/atenfyr/UAssetGUI/actions)
[](https://github.com/atenfyr/UAssetGUI/blob/master/LICENSE.md)
UAssetGUI is a tool designed for low-level examination and modification of Unreal Engine game assets by hand.
## Installation
You can find pre-built binaries of UAssetGUI in the [Releases tab of this repository](https://github.com/atenfyr/UAssetGUI/releases).
An experimental release of UAssetGUI is published with every new commit. If you have issues with the stable release of UAssetGUI, you may wish to try to use the experimental release. You can download the experimental release here: https://github.com/atenfyr/UAssetGUI/releases/tag/experimental-latest.
### Linux Setup
If you would like to set up UAssetGUI for Linux (through Wine), perform the following steps:
1. If needed, download the latest UAssetGUI.exe binary through the Releases page of this repository.
2. If needed, install the latest version of Wine. See this guide: https://gitlab.winehq.org/wine/wine/-/wikis/Download. These instructions were tested using Wine 11.0.
3. Install the latest version of winetricks. See this guide: https://github.com/Winetricks/winetricks?tab=readme-ov-file#installing. If you are on Debian/Ubuntu, you should perform the steps under "Manual Install" on the winetricks GitHub page to make sure that winetricks is up-to-date.
4. To install necessary pre-requisites, execute `winetricks dotnetdesktop10 micross` on the command line and go through all prompts that appear.
* For UAssetGUI v1.1.0 and lower, instead execute `winetricks dotnetdesktop8 micross`
* For UAssetGUI v1.0.0.0-alpha.8 and lower, instead execute `winetricks dotnet472 micross`
5. Open UAssetGUI through Wine: `wine UAssetGUI.exe`
## Command line arguments
You can run the program with command line arguments to perform various tasks, such as exporting and importing from UAssetAPI JSON without opening the GUI.
In the following cases, the engine version can either be specified in `major.minor` string notation (e.g. `4.23` or `5.3`, only available in v1.1.1+), an EngineVersion enum entry (e.g. `VER_UE4_23` to refer to 4.23, `VER_UE5_0` to refer to 5.0, etc., available in all versions) or as an integer (e.g. `23` to refer to 4.23, `29` to refer to 5.0, etc., available in all versions).
Specifying a set of mappings is optional, but if specified, must be the path to a mappings file on disk with extension (only available in v1.1.1+) or the name of a file within the UAssetGUI Mappings config directory with no extension (available in all versions).
### Export to JSON
```
UAssetGUI tojson [mappings name]
```
Example 1: `UAssetGUI tojson A.uasset B.json 5.1 "C:\Mappings.usmap"` (only in v1.1.1+)
Example 2: `UAssetGUI tojson A.uasset B.json VER_UE5_1`
Example 3: `UAssetGUI tojson A.uasset B.json 27 Astro`
### Import from JSON
```
UAssetGUI fromjson [mappings name]
```
Example 1: `UAssetGUI fromjson B.json A.umap`
Example 2: `UAssetGUI fromjson B.json A.umap ./Mappings.usmap` (only in v1.1.1+)
Example 3: `UAssetGUI fromjson B.json A.umap Outriders`
### Open a specific file in the GUI
```
UAssetGUI [file name] [engine version] [mappings name]
```
Example 1: `UAssetGUI` (to simply open the GUI without opening a file)
Example 2: `UAssetGUI test.uasset`
Example 3: `UAssetGUI test.uasset 23`
Example 4: `UAssetGUI test.uasset VER_UE5_4 Bellwright`
### Portable mode
If desired, you may wish to use UAssetGUI in portable mode. In portable mode, all configuration files, saved mappings, etc. are stored in a "Data" folder adjacent to the executable file, allowing UAssetGUI to be used on a USB drive or other portable media. This feature is only available in v1.1.0 or higher.
To set up portable mode, execute UAssetGUI with the following command line parameter. Once UAssetGUI has been launched in portable mode at least once, UAssetGUI can be executed normally (with no parameters) and it will remain in portable mode. To disable portable mode and return to normal operation, simply delete the "Data" folder adjacent to the UAssetGUI executable file.
Usage: `UAssetGUI portable`
## Compilation
If you'd like to compile UAssetGUI for yourself, read on:
### Prerequisites
* Visual Studio 2026 or later, with .NET 10.0 SDK
* Git
### Initial Setup
1. Clone the UAssetGUI repository:
```sh
git clone https://github.com/atenfyr/UAssetGUI.git
```
2. Switch to the new UAssetGUI directory:
```sh
cd UAssetGUI
```
3. Pull the required submodules:
```sh
git submodule update --init
```
4. Open the `UAssetGUI.sln` solution file in Visual Studio, right-click on the UAssetGUI project in the Solution Explorer, and click "Set as Startup Project."
5. Right-click on the solution name in the Solution Explorer, and press "Restore Nuget Packages."
6. Press the "Start" button or press F5 to compile and open UAssetGUI.
## Contributing
Any contributions, whether through pull requests or issues, that you may make are greatly appreciated.
If you have an Unreal Engine .uasset file that displays "failed to maintain binary equality," feel free to submit an issue on [the UAssetAPI issues page](https://github.com/atenfyr/UAssetAPI/issues) with a copy of the asset in question along with the name of the game, the Unreal Engine version that it was cooked with, and a mappings file for the game, if needed.
Please note: Your issue will NOT be reviewed if no test asset(s) are provided (unless the issue is completely unrelated to asset parsing).
We currently do not accept AI-generated code on the UAssetAPI or UAssetGUI repositories. UAssetGUI is mature, stable software, so all changes must be thoroughly tested and reviewed by a human. Pull requests containing AI-generated code, text, documentation, or other AI-generated assets will not be reviewed.
## Source
Source code for UAssetGUI is available on GitHub: https://github.com/atenfyr/UAssetGUI
## License
UAssetAPI and UAssetGUI are distributed under the MIT license, which you can view in detail in the [LICENSE file](LICENSE).
## Installation
You can find pre-built binaries of UAssetGUI in the [Releases tab of this repository](https://github.com/atenfyr/UAssetGUI/releases).
An experimental release of UAssetGUI is published with every new commit. If you have issues with the stable release of UAssetGUI, you may wish to try to use the experimental release. You can download the experimental release here: https://github.com/atenfyr/UAssetGUI/releases/tag/experimental-latest.
### Linux Setup
If you would like to set up UAssetGUI for Linux (through Wine), perform the following steps:
1. If needed, download the latest UAssetGUI.exe binary through the Releases page of this repository.
2. If needed, install the latest version of Wine. See this guide: https://gitlab.winehq.org/wine/wine/-/wikis/Download. These instructions were tested using Wine 11.0.
3. Install the latest version of winetricks. See this guide: https://github.com/Winetricks/winetricks?tab=readme-ov-file#installing. If you are on Debian/Ubuntu, you should perform the steps under "Manual Install" on the winetricks GitHub page to make sure that winetricks is up-to-date.
4. To install necessary pre-requisites, execute `winetricks dotnetdesktop10 micross` on the command line and go through all prompts that appear.
* For UAssetGUI v1.1.0 and lower, instead execute `winetricks dotnetdesktop8 micross`
* For UAssetGUI v1.0.0.0-alpha.8 and lower, instead execute `winetricks dotnet472 micross`
5. Open UAssetGUI through Wine: `wine UAssetGUI.exe`
## Command line arguments
You can run the program with command line arguments to perform various tasks, such as exporting and importing from UAssetAPI JSON without opening the GUI.
In the following cases, the engine version can either be specified in `major.minor` string notation (e.g. `4.23` or `5.3`, only available in v1.1.1+), an EngineVersion enum entry (e.g. `VER_UE4_23` to refer to 4.23, `VER_UE5_0` to refer to 5.0, etc., available in all versions) or as an integer (e.g. `23` to refer to 4.23, `29` to refer to 5.0, etc., available in all versions).
Specifying a set of mappings is optional, but if specified, must be the path to a mappings file on disk with extension (only available in v1.1.1+) or the name of a file within the UAssetGUI Mappings config directory with no extension (available in all versions).
### Export to JSON
```
UAssetGUI tojson