Skip to content

Commit df89176

Browse files
SkowronskiAndrewSkowronskiAndrew
committed
Established individual topic for each UnityDataTool command
1 parent 5d86f8f commit df89176

File tree

5 files changed

+509
-161
lines changed

5 files changed

+509
-161
lines changed

‎UnityDataTool/Commands/analyze.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# analyze Command
2+
3+
The `analyze` command extracts information from Unity Archives (e.g. AssetBundles) and SerializedFiles and dumps the results into a SQLite database.
4+
5+
## Quick Reference
6+
7+
```
8+
UnityDataTool analyze <path> [options]
9+
```
10+
11+
| Option | Description | Default |
12+
|--------|-------------|---------|
13+
| `<path>` | Path to folder containing files to analyze | *(required)* |
14+
| `-o, --output-file <file>` | Output database filename | `database.db` |
15+
| `-p, --search-pattern <pattern>` | File search pattern (`*` and `?` supported) | `*` |
16+
| `-s, --skip-references` | Skip CRC and reference extraction (faster, smaller DB) | `false` |
17+
| `-v, --verbose` | Show more information during analysis | `false` |
18+
| `--no-recurse` | Do not recurse into sub-directories | `false` |
19+
20+
## Examples
21+
22+
Analyze all files in a directory:
23+
```bash
24+
UnityDataTool analyze /path/to/asset/bundles
25+
```
26+
27+
Analyze only `.bundle` files and save to a custom database:
28+
```bash
29+
UnityDataTool analyze /path/to/asset/bundles -o my_database.db -p "*.bundle"
30+
```
31+
32+
Fast analysis (skip reference tracking):
33+
```bash
34+
UnityDataTool analyze /path/to/bundles -s
35+
```
36+
37+
---
38+
39+
## What Can Be Analyzed
40+
41+
The analyze command works with the following types of directories:
42+
43+
| Input Type | Description |
44+
|------------|-------------|
45+
| **AssetBundle build output** | The output path of an AssetBundle build |
46+
| **Addressables folder** | `StreamingAssets/aa` folder from a Player build |
47+
| **Entities content** | `StreamingAssets/ContentArchives` folder for [Entities](https://docs.unity3d.com/Packages/[email protected]/manual/content-management-intro.html) projects |
48+
| **Player Data folder** | The `Data` folder of a Unity Player build |
49+
| **Compressed Player builds** | The `data.unity3d` file will be analyzed like AssetBundles |
50+
51+
> **Note**: Some platforms require extracting content from platform-specific containers first (e.g., `.apk` files on Android).
52+
53+
---
54+
55+
## Output Database
56+
57+
The analysis creates a SQLite database that can be explored using tools like [DB Browser for SQLite](https://sqlitebrowser.org/) or the command line `sqlite3` tool.
58+
59+
**Refer to the [Analyzer documentation](../../Analyzer/README.md) for complete database schema reference and usage examples.**
60+
61+
See also: [Analyze Examples](../../Documentation/analyze-examples.md)
62+
63+
---
64+
65+
## Troubleshooting
66+
67+
### File Loading Warnings
68+
69+
```
70+
Failed to load 'C:\....\MyData.db'. File may be corrupted or was serialized with a newer version of Unity.
71+
```
72+
73+
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.
74+
75+
**Solutions:**
76+
- Use `-p "*.bundle"` to filter by file extension
77+
- Use `--no-recurse` to limit directory depth
78+
- Use `-v` (verbose) to see which files are ignored
79+
80+
The tool automatically ignores common non-Unity file types (`.txt`, `.json`, `.manifest`, etc.).
81+
82+
### TypeTree Errors
83+
84+
```
85+
Error processing file: C:\...\TestProject_Data\level0
86+
System.ArgumentException: Invalid object id.
87+
```
88+
89+
This error occurs when SerializedFiles are built without TypeTrees. The command will skip these files and continue.
90+
91+
**Solution:** Enable **ForceAlwaysWriteTypeTrees** in your Unity build settings. See [Unity Content Format](../../Documentation/unity-content-format.md) for details.
92+
93+
### SQL Constraint Errors
94+
95+
```
96+
SQLite Error 19: 'UNIQUE constraint failed: objects.id'
97+
```
98+
or
99+
```
100+
SQLite Error 19: 'UNIQUE constraint failed: serialized_files.id'.
101+
```
102+
103+
These errors occur when the same serialized file name appears in multiple sources:
104+
105+
| Cause | Solution |
106+
|-------|----------|
107+
| Multiple builds in same directory | Analyze each build separately |
108+
| Scenes with same filename (different paths) | Rename scenes to be unique |
109+
| AssetBundle variants | Analyze variants separately |
110+
111+
See [Comparing Builds](../../Documentation/comparing-builds.md) for strategies to compare different versions of builds.
112+

‎UnityDataTool/Commands/archive.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# archive Command
2+
3+
The `archive` command provides utilities for working with Unity Archives (AssetBundles and web platform `.data` files).
4+
5+
## Sub-Commands
6+
7+
| Sub-Command | Description |
8+
|-------------|-------------|
9+
| [`list`](#list) | List contents of an archive |
10+
| [`extract`](#extract) | Extract contents of an archive |
11+
12+
---
13+
14+
## list
15+
16+
Lists the SerializedFiles contained within an archive.
17+
18+
### Quick Reference
19+
20+
```
21+
UnityDataTool archive list <archive-path>
22+
```
23+
24+
### Example
25+
26+
```bash
27+
UnityDataTool archive list scenes.bundle
28+
```
29+
30+
---
31+
32+
## extract
33+
34+
Extracts the contents of an archive to disk. This is similar to Unity's `WebExtract` tool.
35+
36+
### Quick Reference
37+
38+
```
39+
UnityDataTool archive extract <archive-path> [options]
40+
```
41+
42+
| Option | Description | Default |
43+
|--------|-------------|---------|
44+
| `<archive-path>` | Path to the archive file | *(required)* |
45+
| `-o, --output-path <path>` | Output directory | `archive` |
46+
47+
### Example
48+
49+
```bash
50+
UnityDataTool archive extract scenes.bundle -o contents
51+
```
52+
53+
**Output files:**
54+
```
55+
contents/BuildPlayer-SampleScene.sharedAssets
56+
contents/BuildPlayer-SampleScene
57+
contents/BuildPlayer-Scene2.sharedAssets
58+
contents/BuildPlayer-Scene2
59+
```
60+
61+
> **Note:** The extracted files are binary SerializedFiles, not text. Use the [`dump`](dump.md) command to convert them to readable text format.
62+
63+
---
64+
65+
## Comparison: extract vs dump
66+
67+
| Command | Output | Use Case |
68+
|---------|--------|----------|
69+
| `archive extract` | Binary SerializedFiles | When you need the raw files |
70+
| `dump` | Human-readable text | When you need to inspect content |
71+
72+
The `dump` command can directly process archives without extracting first.
73+

‎UnityDataTool/Commands/dump.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# dump Command
2+
3+
The `dump` command converts Unity SerializedFiles into human-readable text format. This is useful for inspecting the internal structure and properties of Unity assets.
4+
5+
## Quick Reference
6+
7+
```
8+
UnityDataTool dump <path> [options]
9+
```
10+
11+
| Option | Description | Default |
12+
|--------|-------------|---------|
13+
| `<path>` | Path to file to dump | *(required)* |
14+
| `-o, --output-path <path>` | Output folder | Current folder |
15+
| `-f, --output-format <format>` | Output format | `text` |
16+
| `-s, --skip-large-arrays` | Skip dumping large arrays | `false` |
17+
| `-i, --objectid <id>` | Only dump object with this ID | All objects |
18+
19+
## Examples
20+
21+
Dump all objects in a file to the current directory:
22+
```bash
23+
UnityDataTool dump /path/to/file
24+
```
25+
26+
Dump to a specific output folder:
27+
```bash
28+
UnityDataTool dump /path/to/file -o /path/to/output
29+
```
30+
31+
Dump a single object by ID:
32+
```bash
33+
UnityDataTool dump /path/to/file -i 1234567890
34+
```
35+
36+
Skip large arrays for cleaner output:
37+
```bash
38+
UnityDataTool dump /path/to/file -s
39+
```
40+
41+
---
42+
43+
## Archive Support
44+
45+
When you pass an Archive file (like an AssetBundle), the command dumps all SerializedFiles inside.
46+
47+
**Example:** For an AssetBundle `scenes.bundle` containing two scenes:
48+
49+
```bash
50+
UnityDataTool dump scenes.bundle
51+
```
52+
53+
**Output files:**
54+
```
55+
BuildPlayer-SampleScene.sharedAssets.txt
56+
BuildPlayer-SampleScene.txt
57+
BuildPlayer-Scene2.sharedAssets.txt
58+
BuildPlayer-Scene2.txt
59+
```
60+
61+
---
62+
63+
## Output Format
64+
65+
The output is similar to Unity's `binary2text` tool. Each file begins with external references:
66+
67+
```
68+
External References
69+
path(1): "Library/unity default resources" GUID: 0000000000000000e000000000000000 Type: 0
70+
path(2): "Resources/unity_builtin_extra" GUID: 0000000000000000f000000000000000 Type: 0
71+
path(3): "archive:/CAB-35fce856128a6714740898681ea54bbe/..." GUID: 00000000000000000000000000000000 Type: 0
72+
```
73+
74+
Followed by object entries:
75+
76+
```
77+
ID: -8138362113332287275 (ClassID: 135) SphereCollider
78+
m_GameObject PPtr<GameObject>
79+
m_FileID int 0
80+
m_PathID SInt64 -1473921323670530447
81+
m_Material PPtr<PhysicMaterial>
82+
m_FileID int 0
83+
m_PathID SInt64 0
84+
m_IsTrigger bool False
85+
m_Enabled bool True
86+
m_Radius float 0.5
87+
m_Center Vector3f
88+
x float 0
89+
y float 0
90+
z float 0
91+
```
92+
93+
**Refer to the [TextDumper documentation](../../TextDumper/README.md) for detailed output format explanation.**
94+
95+
---
96+
97+
## Understanding PPtrs
98+
99+
PPtrs (Property Pointers) are Unity's mechanism for referencing objects:
100+
101+
| Field | Description |
102+
|-------|-------------|
103+
| `m_FileID` | Index into External References list (0 = same file) |
104+
| `m_PathID` | Object's Local File Identifier (LFID) in that file |
105+
106+
Use external references to resolve cross-file references.
107+

‎UnityDataTool/Commands/find-refs.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# find-refs Command
2+
3+
> ⚠️ **Experimental:** This command may not work as expected in all cases.
4+
5+
The `find-refs` command traces reference chains leading to specific objects. Use it to understand why an asset was included (and potentially duplicated) in a build.
6+
7+
## Quick Reference
8+
9+
```
10+
UnityDataTool find-refs <database> [options]
11+
```
12+
13+
| Option | Description | Default |
14+
|--------|-------------|---------|
15+
| `<database>` | Path to database from `analyze` command | *(required)* |
16+
| `-i, --object-id <id>` | ID of object to analyze (from `id` column) | — |
17+
| `-n, --object-name <name>` | Name of objects to analyze | — |
18+
| `-t, --object-type <type>` | Type filter when using `-n` | — |
19+
| `-o, --output-file <file>` | Output filename | — |
20+
| `-a, --find-all` | Find all chains instead of stopping at first | `false` |
21+
22+
> **Note:** Either `--object-id` or `--object-name` must be provided.
23+
24+
## Prerequisites
25+
26+
This command requires a database created by the [`analyze`](analyze.md) command **without** the `--skip-references` option.
27+
28+
---
29+
30+
## Examples
31+
32+
Find references to an object by name and type:
33+
```bash
34+
UnityDataTool find-refs my_database.db -n "MyTexture" -t "Texture2D" -o refs.txt
35+
```
36+
37+
Find references to a specific object by ID:
38+
```bash
39+
UnityDataTool find-refs my_database.db -i 12345 -o refs.txt
40+
```
41+
42+
Find all duplicate references (useful for finding why an asset is duplicated):
43+
```bash
44+
UnityDataTool find-refs my_database.db -n "SharedMaterial" -t "Material" -a -o all_refs.txt
45+
```
46+
47+
---
48+
49+
## Use Cases
50+
51+
| Scenario | Approach |
52+
|----------|----------|
53+
| **Why is this asset included?** | Use `-n` with the asset name |
54+
| **Why is this asset duplicated?** | Use `-n` to find all instances (same name, different IDs) |
55+
| **Trace specific object** | Use `-i` with the object ID from the database |
56+
| **Find all reference chains** | Add `-a` flag (may take longer) |
57+
58+
---
59+
60+
## Output Format
61+
62+
The output shows the reference chain from root assets to your target object:
63+
64+
```
65+
Reference chains to
66+
ID: 1234
67+
Type: Transform
68+
AssetBundle: asset_bundle_name
69+
SerializedFile: CAB-353837edf22eb1c4d651c39d27a233b7
70+
71+
Found reference in:
72+
MyPrefab.prefab
73+
(AssetBundle = MyAssetBundle; SerializedFile = CAB-353837edf22eb1c4d651c39d27a233b7)
74+
GameObject (id=1348) MyPrefab
75+
↓ m_Component.Array[0].component
76+
RectTransform (id=721) [Component of MyPrefab (id=1348)]
77+
↓ m_Children.Array[9]
78+
RectTransform (id=1285) [Component of MyButton (id=1284)]
79+
↓ m_GameObject
80+
GameObject (id=1284) MyButton
81+
...
82+
Transform (id=1234) [Component of MyButtonEffectLayer (1) (id=938)]
83+
84+
Analyzed 266 object(s).
85+
Found 1 reference chain(s).
86+
```
87+
88+
### Reading the Output
89+
90+
| Element | Description |
91+
|---------|-------------|
92+
| `↓ property_name` | The property containing the reference |
93+
| `[Component of X (id=Y)]` | Shows the GameObject for Components |
94+
| `[Script = X]` | Shows the script name for MonoBehaviours |
95+
96+
**Refer to the [ReferenceFinder documentation](../../ReferenceFinder/README.md) for more details.**
97+

0 commit comments

Comments
 (0)