Skip to content

command-analyze.md

Latest commit

 

History

History
234 lines (172 loc) · 12.3 KB

command-analyze.md

File metadata and controls

234 lines (172 loc) · 12.3 KB
Raw

analyze Command

The analyze command extracts information from Unity Archives (e.g. AssetBundles) and SerializedFiles and dumps the results into a SQLite database.

Quick Reference

UnityDataTool analyze <paths>... [options]
Option Description Default
<paths>... One or more files or directories to analyze. Directories are scanned; files are analyzed directly. (required)
-o, --output-file <file> Output database filename database.db
-p, --search-pattern <pattern> File search pattern applied when scanning directories (* and ? supported) *
-s, --skip-references Do not extract references (smaller DB, no refs table). CRC is still computed. false
--skip-crc Skip the CRC32 checksum calculation (faster; objects.crc32 will be 0) false
-v, --verbose Show more information during analysis false
--no-recurse Do not recurse into sub-directories when scanning directories false
-d, --typetree-data <file> Load an external TypeTree data file before processing (Unity 6.5+) —
--build-history <folder> Build history folder of the project (e.g. Library/BuildHistory). The build folder matching the analyzed build is located automatically and its ContentLayout.json and build report are included in the analysis. See ContentDirectory builds —

There is no way to append to an existing database, so every file you want in the results must be included in a single analyze invocation. Pass multiple paths to combine files from more than one location into the same database.

Examples

Analyze all files in a directory:

UnityDataTool analyze /path/to/asset/bundles

Analyze a single file (no need for . plus -p):

UnityDataTool analyze /path/to/asset/bundles/my.bundle

Combine a build output directory with a build report file kept in a separate location:

UnityDataTool analyze /path/to/build/output /path/to/Library/LastBuild.buildreport

Analyze a ContentDirectory build together with its build history (the matching layout and build report are located automatically):

UnityDataTool analyze /path/to/ContentDirectory --build-history /path/to/Library/BuildHistory

Analyze only .bundle files and specify a custom database name:

UnityDataTool analyze /path/to/asset/bundles -o my_database.db -p "*.bundle"

Fastest analysis (skip both reference extraction and CRC):

UnityDataTool analyze /path/to/bundles --skip-references --skip-crc

See also Analyze Examples.

What Can Be Analyzed

Each path may be an individual file or a directory. Directories are scanned (honoring --search-pattern and --no-recurse); individually-named files are always analyzed. The analyze command works with the following types of input:

Input Type Description
AssetBundle build output The output path of an AssetBundle build
Addressables folder StreamingAssets/aa folder from a Player build, including BuildLayout files
Player Data folder The Data folder of a Unity Player build
Compressed Player builds The data.unity3d file will be analyzed like AssetBundles
ContentDirectory build output The output of BuildPipeline.BuildContentDirectory (Unity 6.6+), ideally together with its build history folder. See ContentDirectory builds
ContentLayout.json The layout file of a ContentDirectory build, imported into dedicated tables. Also useful on its own for querying a large layout with SQL. See ContentLayout in the Analyze Database
BuildReport files The build report is typically found inside Library/BuildHistory or at Library/LastBuild.buildreport. It is a binary serialized file
Entities content StreamingAssets/ContentArchives folder for Entities projects
AssetDatabase Artifacts The tool will work to some extent with serialized files created in the AssetDatabase artifact storage, inside the Library folder

Note: Some platforms require extracting content from platform-specific containers first (e.g., .apk files on Android).

ContentDirectory builds

Analyze a ContentDirectory build together with its ContentLayout.json by passing the build output folder and the project's build history with --build-history:

UnityDataTool analyze /path/to/ContentDirectory --build-history /path/to/Library/BuildHistory -o database.db

Analyze locates the build's own folder inside the build history and includes its ContentLayout.json and .buildreport in the analysis, so there is no need to identify the correct build folder by hand. Alternatively, pass the build folder (or the layout file itself) as a regular input:

UnityDataTool analyze /path/to/ContentDirectory /path/to/Library/BuildHistory/<build-directory> -o database.db

The layout provides the source-asset mapping (imported as the content_layout tables, see ContentLayout in the Analyze Database) and the dependency information that resolves the references between the build's Content Files (see Content Directory Format). Without it, cross-file references cannot be resolved and are recorded in dangling_refs.

A ContentLayout.json is only used when its BuildManifestHash matches the analyzed build's BuildManifestHash.txt (a file guaranteed to exist in the build output folder, which analyze picks up automatically). This exact-match rule prevents a stale or unrelated layout from silently producing misleading results. It is also how --build-history finds the build's folder: the folder whose ContentLayout.json matches the hash is used (the most recent one, if the same content was built several times). --build-history does not search recursively — the build folders must be direct children of the given path (or the path may be a build folder itself).

How the input combinations behave:

Input Result
ContentDirectory only Analyzed, with a warning that the analysis is incomplete (broken references, no source mapping)
Subset of files from a ContentDirectory Same as above; recognized by the .cf extension
ContentDirectory + matching ContentLayout.json Analyzed with resolved references and source mapping
ContentDirectory + --build-history The build's folder is located in the history; its layout and build report are analyzed too. Error when no folder matches
--build-history without a ContentDirectory build in the input Error — only ContentDirectory builds can be matched against a build history
Subset of ContentDirectory files + ContentLayout.json Works when a BuildManifestHash.txt can be found for the hash match; error when the layout cannot be validated
ContentDirectory + multiple ContentLayout.json The one matching the build is used, the rest are ignored; error when none match
ContentLayout.json only Imported on its own (layout tables only)
Multiple ContentDirectory builds Error — analyze a single build at a time
Non-ContentDirectory content + ContentDirectory Allowed, e.g. a Player build and a ContentDirectory together for duplicate detection

Output Database

The analysis creates a SQLite database that can be explored using tools like DB Browser for SQLite or the command line sqlite3 tool.

Refer to the Analyzer documentation for the database schema reference and information about extending this command.

Troubleshooting

File Loading Warnings

Failed to load 'C:\....\MyData.db'. File may be corrupted or was serialized with a newer version of Unity.

These warnings occur when the tool encounters non-Unity files in the analyzed directory. They are usually harmless—the analyze process continues and produces a valid database.

Solutions:

  • Use -p "*.bundle" to filter by file extension
  • Use --no-recurse to limit directory depth
  • Use -v (verbose) to see which files are ignored

The tool automatically ignores common non-Unity file types (.txt, .json, .manifest, etc.).

TypeTree Errors

Error processing file: C:\...\TestProject_Data\level0
System.ArgumentException: Invalid object id.

This error occurs when SerializedFiles are built without TypeTrees. The command will skip these files and continue.

Solutions:

  • Enable ForceAlwaysWriteTypeTrees in your Unity build settings. See Unity Content Format for details.
  • If your bundles were built with external TypeTree data (Unity 6.5+), use the --typetree-data option to load the TypeTree data file before analysis:
UnityDataTool analyze /path/to/bundles --typetree-data /path/to/typetree.bin

Duplicate SerializedFile name / Duplicate archive name

Skipping build2\level0: Duplicate SerializedFile name 'level0'. Only a single build can be analyzed at a time; the same SerializedFile name cannot be analyzed twice.

or

Skipping build2\assetbundle: Duplicate archive name 'assetbundle'. Each analyzed archive must have a unique name; only a single build can be analyzed at a time.

analyze only supports a single build at a time. Unity resolves references between SerializedFiles by file name, so two files that share a name are indistinguishable to those references — there is no way to tell which copy a reference points at. For that reason each SerializedFile name (and each archive name) may appear only once in a database.

When analyze encounters a second file or archive with a name it has already processed, it prints one of the messages above, skips that file or archive (counting it as a failed file), and continues with the rest of the input. The already-analyzed copy is kept; the duplicate's content is ignored.

This is expected when the input contains more than one build, and in these common cases:

Cause What to do
Multiple builds passed together (or nested in one directory) Analyze each build into its own database
AssetBundle variants (same content, different variant) Analyze each variant separately
Hashed AssetBundle file names across two builds The file names differ but the inner SerializedFile (CAB-<hash>) is shared — analyze each build separately
Player scenes with the same file name (level0, …) from different builds Analyze each build separately

To compare two builds, analyze each into a separate database and query across them — see Comparing Builds.

Slow Analyze times, large output database

Two independent flags reduce analyze time and database size:

  • --skip-crc skips the CRC32 calculation. This is usually the largest time saver, because computing a CRC requires reading the full content of every object, including large texture, mesh and audio data in companion .resS/.resource files.
  • --skip-references skips reference extraction, which is the largest contributor to database size (the refs table). The references are not needed for core asset inventory and size information.

For the fastest, smallest result, combine them.

A real life analyze of a big Addressables build, skipping both references and CRC, shows how large a difference this can make:

  • 208 seconds and produced a 500MB database (default)
  • 9 seconds and produced a 68 MB file (with --skip-references --skip-crc)

When --skip-references is used, some functionality is lost:

  • the find-refs command will not work
  • view_material_shader_refs and view_material_texture_refs will be empty
  • script_object_view will be empty
  • dangling_refs will be empty
  • Queries that look at the relationship between objects will not work. For example the refs table is required to link between a MonoBehaviour and its MonoScript.

When --skip-crc is used, the objects.crc32 column will be 0 for all objects. This means:

  • No detection of identical objects by content hash (See Comparing Builds)
  • The view_potential_duplicates view relies partially on CRC32 to distinguish true duplicates