Repository files navigation

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 andPlayer content.

Thecommand line tool runs directly on Unity data files, without requiring the Editor to be running. It covers most 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. Seeexamples andcomparing builds for examples of how to use the command line tool.

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 informationfrom Unity data files and output it into a SQLite database.
• TextDumper: a class library that can be used to dump SerializedFiles intoa human-readable format (similar to binary2text).
• ReferenceFinder: a class library that can be used to findreference 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 theUnityFileSystemApi 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 inversion 2022.1.0a14). For convenience this repository includes a copy of the Unity 2022 Windows, Mac and Linux builds of thelibrary, in theUnityFileSystem/ directory. The library is somewhat backward compatible,which means that it can read data files generated by any previous version ofUnity. Ideally, you should copy UnityFileSystemApi (.dll/.dylib) from Unity Editor install pathData/Tools/ subfolder toUnityDataTool/UnityFileSystem/ of an Engine version that producedserialized 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.

1. The projects in this solution require the.NET 9.0 SDK.
2. CopyUnityFileSystemApi library 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.
3. Build usingdotnet 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 thecommand 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 andbinary2text tools, but in a more flexible way.

To better understand the files and data formats that the Unity supports in the runtime seethis topic.

This tool is the evolution of theAssetBundle Analyzerwritten byFrancis Pagé.

That project was the first to introduce the SQLite database analysis of Unity build output to addressthe 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. Itis extremely slow as it runs WebExtract and binary2text on all the AssetBundles of a project andhas to parse very large text files. It can also easily fail because the syntax used by binary2textis not standard and can even be impossible to parse in some occasions.

To address those problems@faelenor established this UnityDataToolsrepository and the UnityFileSystemApi library was created within Unity, to replace the usage of WebExtract andbinary2text functionalities. With the library, it becomes very easy to create a binary2text-like toolthat 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 anexperimental tool provided as an example of what can be done using the UnityFileSystemApi. You canreport bugs and submit pull requests, but there is no guarantee that they will be addressed.