UnityDataTools

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 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. See the Documentation section below for guides to Unity's content formats and to using the tool.

It is designed to scale for large build outputs and has been used to fine-tune big Unity-based games.

The tool also provides comprehensive analysis of Unity Addressables build reports, automatically detecting and parsing Addressables JSON build outputs to extract detailed information about bundles, assets, dependencies, file sizes, and build performance metrics. See the Addressables Build Report Analysis documentation for complete details.

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.

Install

Builds for Windows, macOS (Apple Silicon) and Linux are attached to every release. They are self-contained: a zip holds the UnityDataTool executable, the native UnityFileSystemApi library it uses, and an offline copy of this README and the Documentation/ folder. Nothing else needs to be installed, not even a .NET runtime.

The commands below download the latest release, unzip it, and print the version. They install into %LOCALAPPDATA%\Programs\UnityDataTool on Windows and ~/.local/share/UnityDataTool on macOS and Linux; set dest to something else to install anywhere you like, such as a shared tools directory.

Windows (PowerShell)

$dest = "$env:LOCALAPPDATA\Programs\UnityDataTool"
Invoke-WebRequest https://github.com/Unity-Technologies/UnityDataTools/releases/latest/download/UnityDataTool-windows-x64.zip -OutFile "$env:TEMP\UnityDataTool.zip"
Expand-Archive "$env:TEMP\UnityDataTool.zip" -DestinationPath $dest -Force
& "$dest\UnityDataTool.exe" --version

macOS (Apple Silicon)

dest=~/.local/share/UnityDataTool
curl -fsSL -o /tmp/UnityDataTool.zip https://github.com/Unity-Technologies/UnityDataTools/releases/latest/download/UnityDataTool-macos-arm64.zip
unzip -oq /tmp/UnityDataTool.zip -d "$dest" && "$dest/UnityDataTool" --version

Linux (x64)

dest=~/.local/share/UnityDataTool
curl -fsSL -o /tmp/UnityDataTool.zip https://github.com/Unity-Technologies/UnityDataTools/releases/latest/download/UnityDataTool-linux-x64.zip
unzip -oq /tmp/UnityDataTool.zip -d "$dest" && "$dest/UnityDataTool" --version

Add the install directory to your PATH to run the tool as UnityDataTool from anywhere. The releases/latest/download/ links always resolve to the newest release, and checksums.txt on the release page holds the SHA-256 of each zip.

A few things worth knowing:

• To upgrade, run the same commands again. They overwrite everything the new release ships, but they do not remove a file that it has dropped, so a renamed documentation page can survive as a stale copy. Delete the install directory first for an install that matches the release exactly.
• On macOS, downloading with curl avoids the quarantine flag that a browser download sets. After a browser download, macOS may refuse to load UnityFileSystemApi.dylib until it is allowed under System Settings > Privacy & Security.
• Intel Macs have no published build; build from source instead.
• Each release describes what changed. For changes that are not in a release yet, see the commit history and build from source.

Documentation

New to Unity's data files or to UnityDataTool? These topics are a good place to start.

Understanding Unity content

Topic	Description
Overview of Unity Content	The core file types (SerializedFiles and Unity Archives), TypeTrees, and how Player and AssetBundle builds are laid out.
AssetBundle Format	A hands-on look inside AssetBundles: the AssetBundle object, preload tables, and how scenes are stored.
Player Build Format	The Player build layout, compression, built-in resource files, and tips for inspecting Player content (including Android and Web).
Content Directory Format	Content directory builds (Unity 6.6+): what they produce, the build history, and inspecting them with UnityDataTool.
ContentLayout.json	The build layout file that maps content directory build output back to source assets.

Using UnityDataTool

Topic	Description
Command-line tool	All commands and their options.
Analyzer	The library behind analyze, and where each part of the database is documented.
Database schema	Reference for the tables and views that analyze produces.
Example queries	Worked examples of querying the analyze database.
Using UnityDataTool with an AI agent	The recommended workflow for AI agents (and scripts) analyzing a build.
Comparing builds	Finding what changed between two builds.
Addressables build reports	Analyzing Addressables JSON build reports.
Build reports	Importing a Unity BuildReport to map build output back to source assets.

Repository content

The solution is organised in three layers. At the base are the libraries that read Unity's binary formats. On top of those sit the feature libraries that turn that raw data into something useful (a database, a text dump, a reference graph). And at the top is the command-line tool that exposes all of that functionality to users.

flowchart TD
    CLI["<b>UnityDataTool</b><br/>command-line tool"]

    Analyzer["<b>Analyzer</b><br/>SQLite database"]
    TextDumper["<b>TextDumper</b><br/>human-readable dump"]
    ReferenceFinder["<b>ReferenceFinder</b><br/>reference chains"]
    Archive["<b>Archive</b><br/>inspect / extract archives"]
    SerializedFile["<b>SerializedFile</b><br/>inspect SerializedFiles"]

    UnityFileSystem["<b>UnityFileSystem</b><br/>C# wrapper +<br/>UnityFileSystemApi (native)"]
    UnityBinaryFormat["<b>UnityBinaryFormat</b><br/>C# parsers &amp; helpers<br/>for Archives / SerializedFiles"]
    UnityDataModels["<b>UnityDataModels</b><br/>schemas for build reporting file formats"]

    CLI --> Analyzer
    CLI --> TextDumper
    CLI --> ReferenceFinder
    CLI --> Archive
    CLI --> SerializedFile

    Analyzer --> UnityFileSystem
    Analyzer --> UnityBinaryFormat
    Analyzer --> UnityDataModels
    TextDumper --> UnityFileSystem
    TextDumper --> UnityBinaryFormat
    Archive --> UnityFileSystem
    Archive --> UnityBinaryFormat
    SerializedFile --> UnityFileSystem
    SerializedFile --> UnityBinaryFormat
    UnityBinaryFormat --> UnityFileSystem

    ReferenceFinder -. "reads the SQLite database" .-> Analyzer

Command-line tool

• UnityDataTool: the command-line tool. It wires the feature libraries together and exposes them as commands (analyze, dump, find-refs, archive, serialized-file, and more), so most users only ever interact with this executable.

Feature libraries

• Analyzer: extracts key information from Unity data files into a SQLite database for detailed analysis. It also parses Addressables build reports.
• TextDumper: dumps SerializedFiles into a human-readable format (similar to Unity's binary2text).
• ReferenceFinder: experimental; finds reference chains from one object to another by querying a database produced by the Analyzer (a data dependency rather than a code one).
• Archive: inspects and extracts the contents of Unity Archives (AssetBundles and web platform .data files) — the archive command.
• SerializedFile: inspects the header, metadata, object list, and external references of a SerializedFile — the serialized-file command.

Base libraries

• UnityFileSystem: a .NET class library, with source and binaries, that wraps the native UnityFileSystemApi to mount Unity Archives and read SerializedFiles.
• UnityBinaryFormat: C# parsers and helpers for reading data out of Unity Archives and SerializedFiles.
• UnityDataModels: shared C# models for the reading JSON format files produced by the build (Addressables BuildLayout.json, Content Directory ContentLayout.json).

Purpose of UnityFileSystemApi

UnityFileSystemApi is compiled from the Unity source code and exposes the core functionality to open and read the Unity Archive and Serialized File formats as a flexible, performant library. It exposes the ability to navigate the TypeTrees inside a SerializedFile so objects can be read generically, without hardcoded type knowledge.

It enables custom tools for binary2text-like output and efficient SQLite database generation.

Tests and test data

The automated tests are not shown in the diagram above. Each library has its own test project, and the shared test data doubles as convenient sample content for ad hoc use of the tool.

• TestCommon: a helper library whose Data/ folder holds small reference files extracted from real Unity builds (Player, AssetBundles, content directory etc). These back the automated tests and are also handy for trying out the tool by hand.
• Analyzer.Tests, UnityDataTool.Tests, UnityFileSystem.Tests: the per-library test suites.
• UnityProjects: two Unity projects (Baseline and LeadingEdge) used to regenerate some of the test data as Unity evolves.

Getting UnityFileSystemApi

UnityDataTool uses the pre-compiled UnityFileSystemApi library to read Unity Archives and SerializedFiles. Normally you don't need to do anything with this library. The repository already includes a recent Windows, Mac, and Linux copy in the UnityFileSystem/ directory, and using that bundled copy is the recommended way to run the tool.

The library is backward compatible but not forward compatible: a given version can read content from the same or older Unity versions, but may be unable to read content produced by a newer Unity Editor than the library itself. The bundled copy is updated periodically as Unity evolves, so in practice it can read content from just about any Unity version.

UnityFileSystemApi is also distributed in the Data/Tools/ folder of the Unity Editor (for all versions since 2022.1.0a14). In the rare case that you need to read content from a Unity version newer than the bundled library, copy the matching file from your Unity Editor installation ({UnityEditor}/Data/Tools/) into the UnityFileSystem/ directory before building:

• Windows: UnityFileSystemApi.dll
• Mac: UnityFileSystemApi.dylib
• Linux: UnityFileSystemApi.so

How to Build

1. Clone or download this repository.
2. Install the .NET 9.0 SDK.
3. (Optional) Overwrite the checked in version of the UnityFileSystemApi library with one from your Unity Editor installation, as described above.
4. Build using dotnet build -c Release or your preferred IDE (tested with Visual Studio and Rider on Windows/Mac).

On Windows, the executable is written to UnityDataTool\bin\Release\net9.0. Add this location to your system PATH for convenient access.

See the command-line tool documentation for usage instructions.

Maintainers: see Releasing UnityDataTool for how a release is cut and published.

Origins

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.

UnityDataTools and UnityFileSystemApi were created to overcome these issues, providing fast, reliable access to Unity data files and enabling advanced analysis.

Disclaimer

This project is provided on an "as-is" basis and is not officially supported by Unity. It is an experimental tool and example of UnityFileSystemApi usage. Bug reports and pull requests are welcome, but support is not guaranteed.