Established individual topic for each UnityDataTool command

UnityDataTool/Commands/analyze.md

@@ -0,0 +1,136 @@
+# 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 <path> [options]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `<path>` | Path to folder containing files to analyze | *(required)* |
+| `-o, --output-file <file>` | Output database filename | `database.db` |
+| `-p, --search-pattern <pattern>` | File search pattern (`*` and `?` supported) | `*` |
+| `-s, --skip-references` | Skip CRC and reference extraction (faster, smaller DB) | `false` |
+| `-v, --verbose` | Show more information during analysis | `false` |
+| `--no-recurse` | Do not recurse into sub-directories | `false` |
+
+## Examples
+
+Analyze all files in a directory:
+```bash
+UnityDataTool analyze /path/to/asset/bundles
+```
+
+Analyze only `.bundle` files and specify a custom database name:
+```bash
+UnityDataTool analyze /path/to/asset/bundles -o my_database.db -p "*.bundle"
+```
+
+Fast analysis (skip reference tracking):
+```bash
+UnityDataTool analyze /path/to/bundles -s
+```
+
+See also [Analyze Examples](../../Documentation/analyze-examples.md).
+
+---
+
+## What Can Be Analyzed
+
+The analyze command works with the following types of directories:
+
+| 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 |
+| **Entities content** | `StreamingAssets/ContentArchives` folder for [Entities](https://docs.unity3d.com/Packages/[email protected]/manual/content-management-intro.html) projects |
+| **Player Data folder** | The `Data` folder of a Unity Player build |
+| **Compressed Player builds** | The `data.unity3d` file will be analyzed like AssetBundles |
+| **BuildReport files** | The build report is typically found at a path like `Library/LastBuild.buildreport`and is a binary serialized file |
+| **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).
+
+---
+
+## Output Database
+
+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.
+
+**Refer to the [Analyzer documentation](../../Analyzer/README.md) 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.
+
+**Solution:** Enable **ForceAlwaysWriteTypeTrees** in your Unity build settings. See [Unity Content Format](../../Documentation/unity-content-format.md) for details.
+
+### SQL Constraint Errors
+
+```
+SQLite Error 19: 'UNIQUE constraint failed: objects.id'
+```
+or
+```
+SQLite Error 19: 'UNIQUE constraint failed: serialized_files.id'.
+```
+
+These errors occur when the same serialized file name appears in multiple sources:
+
+| Cause | Solution |
+|-------|----------|
+| Multiple builds in same directory | Analyze each build separately |
+| Scenes with same filename (different paths) | Rename scenes to be unique |
+| AssetBundle variants | Analyze variants separately |
+
+See [Comparing Builds](../../Documentation/comparing-builds.md) for strategies to compare different versions of builds.
+
+### Slow Analyze times, large output database
+
+Consider using the `--skip-references` argument.
+
+A real life analyze of a big Addressables build shows how large a difference this can make:
+
+* 208 seconds and producted a 500MB database (not specifying --skip-reference)
+* 9 seconds and produced a 68 MB file (with --skip-reference)
+
+The references are not needed for core asset inventory and size information. 
+
+Note: When specifying `--skip-reference` some functionality is lost:
+
+* the `find-refs` command will not work
+* `view_material_shader_refs` and `view_material_texture_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`.
+* The `objects.crc32` column will be NULL/0 for all objects. This means:
+  * No detection of identical objects by content hash (See [Comparing Builds](../../Documentation/comparing-builds.md))
+  * The `view_potential_duplicates` view relies partially on CRC32 to distinguish true duplicates
+
+Future work: The refs table contains a lot of repeated strings and could be made smaller and more efficient.  It might also be prudent to control the CRC32 calculation using an independent flag.
+

UnityDataTool/Commands/archive.md

@@ -0,0 +1,73 @@
+# archive Command
+
+The `archive` command provides utilities for working with Unity Archives (AssetBundles and web platform `.data` files).
+
+## Sub-Commands
+
+| Sub-Command | Description |
+|-------------|-------------|
+| [`list`](#list) | List contents of an archive |
+| [`extract`](#extract) | Extract contents of an archive |
+
+---
+
+## list
+
+Lists the SerializedFiles contained within an archive.
+
+### Quick Reference
+
+```
+UnityDataTool archive list <archive-path>
+```
+
+### Example
+
+```bash
+UnityDataTool archive list scenes.bundle
+```
+
+---
+
+## extract
+
+Extracts the contents of an archive to disk. This is similar to Unity's `WebExtract` tool.
+
+### Quick Reference
+
+```
+UnityDataTool archive extract <archive-path> [options]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `<archive-path>` | Path to the archive file | *(required)* |
+| `-o, --output-path <path>` | Output directory | `archive` |
+
+### Example
+
+```bash
+UnityDataTool archive extract scenes.bundle -o contents
+```
+
+**Output files:**
+```
+contents/BuildPlayer-SampleScene.sharedAssets
+contents/BuildPlayer-SampleScene
+contents/BuildPlayer-Scene2.sharedAssets
+contents/BuildPlayer-Scene2
+```
+
+> **Note:** The extracted files are binary SerializedFiles, not text. Use the [`dump`](dump.md) command to convert them to readable text format.
+
+---
+
+## Comparison: extract vs dump
+
+| Command | Output | Use Case |
+|---------|--------|----------|
+| `archive extract` | Binary SerializedFiles, .resS anything else inside the archive content | When you need all the raw files inside an archive |
+| `dump` | text | When you want to inspect object content |
+
+The `dump` command can directly process archives without extracting first.
+

UnityDataTool/Commands/dump.md

@@ -0,0 +1,111 @@
+# dump Command
+
+The `dump` command converts Unity SerializedFiles into human-readable text format. This is useful for inspecting the internal structure and properties of Unity assets.
+
+## Quick Reference
+
+```
+UnityDataTool dump <path> [options]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `<path>` | Path to file to dump | *(required)* |
+| `-o, --output-path <path>` | Output folder | Current folder |
+| `-f, --output-format <format>` | Output format | `text` |
+| `-s, --skip-large-arrays` | Skip dumping large arrays | `false` |
+| `-i, --objectid <id>` | Only dump object with this ID | All objects |
+
+## Examples
+
+Dump all objects in a file to the current directory:
+```bash
+UnityDataTool dump /path/to/file
+```
+
+Dump to a specific output folder:
+```bash
+UnityDataTool dump /path/to/file -o /path/to/output
+```
+
+Dump a single object by ID:
+```bash
+UnityDataTool dump /path/to/file -i 1234567890
+```
+
+Skip large arrays for cleaner output:
+```bash
+UnityDataTool dump /path/to/file -s
+```
+
+---
+
+## Archive Support
+
+When you pass an Archive file (like an AssetBundle), the command dumps all SerializedFiles inside.
+
+**Example:** For an AssetBundle `scenes.bundle` containing two scenes:
+
+```bash
+UnityDataTool dump scenes.bundle
+```
+
+**Output files:**
+```
+BuildPlayer-SampleScene.sharedAssets.txt
+BuildPlayer-SampleScene.txt
+BuildPlayer-Scene2.sharedAssets.txt
+BuildPlayer-Scene2.txt
+```
+
+---
+
+## Output Format
+
+The output is similar to Unity's `binary2text` tool. Each file begins with external references:
+
+```
+External References
+path(1): "Library/unity default resources" GUID: 0000000000000000e000000000000000 Type: 0
+path(2): "Resources/unity_builtin_extra" GUID: 0000000000000000f000000000000000 Type: 0
+path(3): "archive:/CAB-35fce856128a6714740898681ea54bbe/..." GUID: 00000000000000000000000000000000 Type: 0
+```
+
+Followed by object entries:
+
+```
+ID: -8138362113332287275 (ClassID: 135) SphereCollider 
+  m_GameObject PPtr<GameObject> 
+    m_FileID int 0
+    m_PathID SInt64 -1473921323670530447
+  m_Material PPtr<PhysicMaterial> 
+    m_FileID int 0
+    m_PathID SInt64 0
+  m_IsTrigger bool False
+  m_Enabled bool True
+  m_Radius float 0.5
+  m_Center Vector3f 
+    x float 0
+    y float 0
+    z float 0
+```
+
+**Refer to the [TextDumper documentation](../../TextDumper/README.md) for detailed output format explanation.**
+
+---
+
+## Understanding PPtrs
+
+PPtrs (Property Pointers) are Unity's mechanism for referencing objects:
+
+| Field | Description |
+|-------|-------------|
+| `m_FileID` | Index into External References list (0 = same file) |
+| `m_PathID` | Object's Local File Identifier (LFID) in that file |
+
+A null reference will have value m_FileID = 0, m_PathID = 0
+
+The external reference table is used to resolve cross-file references. It always starts at index 1.  m_FileID 0 is used for references within the current file.
+
+
+