The UnityDataTool is a command line tool and showcase of the UnityFileSystemApi native dynamic library. The main purpose is for analysis of the content of Unity data files, for example AssetBundles and Player content.
The command line tool runs directly on Unity data files, without requiring the Editor to be running. It covers functionality of the Unity tools WebExtract and binary2text, with better performance. And it adds a lot of additional functionality, for example the ability to create a SQLite database for detailed analysis of build content. It is designed to scale for large build outputs and has been used to fine-tune big Unity-based games.
The command line tool uses the UnityFileSystemApi library to access the content of Unity Archives and Serialized files, which are Unity's primary binary formats. This repository also serves as a reference for how this library could be used as part of incorporating functionality into your own tools.
The repository contains the following items:
- UnityDataTool: a command-line tool providing access to the Analyzer, TextDumper and other class libraries.
- Analyzer: a class library that can be used to extract key information from Unity data files and output it into a SQLite database.
- TextDumper: a class library that can be used to dump SerializedFiles into a human-readable format (similar to binary2text).
- ReferenceFinder: a class library that can be used to find reference chains from objects to other objects using a database created by the Analyzer
- UnityFileSystem: source code and binaries of a .NET class library exposing the functionalities or the UnityFileSystemApi native library.
- UnityFileSystem.Tests: test suite for the UnityFileSystem library.
- UnityFileSystemTestData: the Unity project used to generate the test data.
- TestCommon: a helper library used by the test projects.
The UnityFileSystemApi library is distributed in the Tools folder of the Unity editor (starting in
version 2022.1.0a14). For convenience this repository includes a copy of the Unity 2022 Windows, Mac and Linux builds of the
library, in the UnityFileSystem/ directory. The library is somewhat backward compatible,
which means that it can read data files generated by any previous version of
Unity. Ideally, you should copy UnityFileSystemApi (.dll/.dylib) from Unity Editor install path
Data/Tools/ subfolder to UnityDataTool/UnityFileSystem/ of an Engine version that produced
serialized data you want to analyze.
Currently, we do not host builds of UnityDataTools, you will need to clone or download this repo and build it yourself.
- The projects in this solution require the .NET 9.0 SDK.
- Copy
UnityFileSystemApilibrary from your Unity Editor installation, in{UnityEditor}/Data/Tools/toUnityDataTool/UnityFileSystem/. This step is typically optional, because a previously built version of the library is included in the repo that can read the output from most Unity Versions. - Build using
dotnet build -c Release
Note: Alternatively you can build with your favorite IDE. This was tested with Visual Studio and Rider on Windows and Rider on Mac.
See the documentation page for the command line tool for information about how to run the tool after you have built it.
The purpose of the UnityFileSystemApi is to expose the functionalities of the WebExtract and binary2text tools, but in a more flexible way.
To better understand the files and data formats that the Unity supports in the runtime see this topic.
This tool is the evolution of the AssetBundle Analyzer written by Francis Pagé.
That project was the first to introduce the SQLite database analysis of Unity build output to address the difficulty of diagnosing build issues through the raw binary2text output, which is large and difficult to navigate.
The AssetBundle Analyzer was quite successful, but it has several issues. It is extremely slow as it runs WebExtract and binary2text on all the AssetBundles of a project and has to parse very large text files. It can also easily fail because the syntax used by binary2text is not standard and can even be impossible to parse in some occasions.
To address those problems @faelenor established this UnityDataTools repository and the UnityFileSystemApi library was created within Unity, to replace the usage of WebExtract and binary2text functionalities. With the library, it becomes very easy to create a binary2text-like tool that can output the data in any format, as well as the fast and simpler code for generating the SQLite output.
This tool continues to be useful in recent Unity versions, for example Unity 6.
This project is provided on an "as-is" basis and is not officially supported by Unity. It is an experimental tool provided as an example of what can be done using the UnityFileSystemApi. You can report bugs and submit pull requests, but there is no guarantee that they will be addressed.
