"Dump" command supports outputing a single object (#30)

Support dump filtering by objectid

Example:

UnityDataTool dump imagelist.bundle -i -8066222900050932585

Author: SkowronskiAndrew

Documentation/comparing-builds.md

@@ -164,6 +164,8 @@ As expected, it's only fields on the MonoBehaviour and one of the Transforms tha
 
 In a normal case we would not know exactly what changed in the build, so rather than confirming the expected changes we probably would be working in the other direction - using comparison technique to see which objects and values changed and try to build an understanding of whether this is "expected" or not.
 
+Note: When you know the id of the object that has changed you can pass the `--objectid` argument to the `dump` command to only dump that object.  This can be useful for large Serialized Files with many objects, where you want to focus on changes to a single object.
+
 # Example 2 - Changes in a texture
 
 The previous example covers the common case where the changes are limited to serialized values directly inside Serialized Files.  However its also common that data inside the auxiliary .resS and .resource files can change, based on changes to textures, meshes, audio or video.  This can also cause the AssetBundle content to change, even if the Serialized Files themselves are unchanged.

TextDumper/README.md

@@ -5,11 +5,11 @@ file (AssetBundle or SerializedFile) into human-readable yaml-style text file.
 
 ## How to use
 
-The library consists of a single class called [TextDumperTool](./TextDumperTool.cs). It has a single 
-method named Dump and takes three parameters:
+The library consists of a single class called [TextDumperTool](./TextDumperTool.cs). It has a method named Dump and takes four parameters:
 * path (string): path of the data file.
 * outputPath (string): path where the output files will be created.
 * skipLargeArrays (bool): if true, the content of arrays larger than 1KB won't be dumped.
+* objectId (long, optional): if specified and not 0, only the object with this signed 64-bit id will be dumped. If 0 (default), all objects are dumped.
 
 ## How to interpret the output files
 

TextDumper/TextDumperTool.cs

@@ -13,14 +13,16 @@ public class TextDumperTool
     SerializedFile m_SerializedFile;
     StreamWriter m_Writer;
 
-    public int Dump(string path, string outputPath, bool skipLargeArrays)
+    public int Dump(string path, string outputPath, bool skipLargeArrays, long objectId = 0)
     {
         m_SkipLargeArrays = skipLargeArrays;
 
         try
         {
             try
             {
+                // Try the input as an unity archive, e.g. an AssetBundle
+                // In that case we dump each serialized file contained inside it.
                 using var archive = UnityFileSystem.MountArchive(path, "/");
                 foreach (var node in archive.Nodes)
                 {
@@ -30,7 +32,7 @@ public int Dump(string path, string outputPath, bool skipLargeArrays)
                     {
                         using (m_Writer = new StreamWriter(Path.Combine(outputPath, Path.GetFileName(node.Path) + ".txt"), false))
                         {
-                            OutputSerializedFile("/" + node.Path);
+                            OutputSerializedFile("/" + node.Path, objectId);
                         }
                     }
                 }
@@ -40,7 +42,7 @@ public int Dump(string path, string outputPath, bool skipLargeArrays)
                 // Try as SerializedFile
                 using (m_Writer = new StreamWriter(Path.Combine(outputPath, Path.GetFileName(path) + ".txt"), false))
                 {
-                    OutputSerializedFile(path);
+                    OutputSerializedFile(path, objectId);
                 }
             }
         }
@@ -340,7 +342,7 @@ bool DumpManagedReferenceData(TypeTreeNode refTypeNode, TypeTreeNode referencedT
         return true;
     }
 
-    void OutputSerializedFile(string path)
+    void OutputSerializedFile(string path, long objectId)
     {
         using (m_Reader = new UnityFileReader(path, 64 * 1024 * 1024))
         using (m_SerializedFile = UnityFileSystem.OpenSerializedFile(path))
@@ -355,15 +357,23 @@ void OutputSerializedFile(string path)
             }
             m_Writer.WriteLine();
 
+            bool dumpedObject = false;
             foreach (var obj in m_SerializedFile.Objects)
             {
+                if (objectId != 0 && obj.Id != objectId)
+                    continue;
+
                 var root = m_SerializedFile.GetTypeTreeRoot(obj.Id);
                 var offset = obj.Offset;
 
                 m_Writer.Write($"ID: {obj.Id} (ClassID: {obj.TypeId}) ");
                 RecursiveDump(root, ref offset, 0);
                 m_Writer.WriteLine();
+                dumpedObject = true;
             }
+
+            if (objectId != 0 && !dumpedObject)
+                m_Writer.WriteLine($"Object with ID {objectId} not found.");
         }
     }
 

UnityDataTool/Program.cs

@@ -75,17 +75,19 @@ public static async Task<int> Main(string[] args)
             var fOpt = new Option<DumpFormat>(aliases: new[] { "--output-format", "-f" }, description: "Output format", getDefaultValue: () => DumpFormat.Text);
             var sOpt = new Option<bool>(aliases: new[] { "--skip-large-arrays", "-s" }, description: "Do not dump large arrays of basic data types");
             var oOpt = new Option<DirectoryInfo>(aliases: new[] { "--output-path", "-o"}, description: "Output folder", getDefaultValue: () => new DirectoryInfo(Environment.CurrentDirectory));
+            var objectIdOpt = new Option<long>(aliases: new[] { "--objectid", "-i" }, () => 0, "Only dump the object with this signed 64-bit id (default: 0, dump all objects)");
 
             var dumpCommand = new Command("dump", "Dump the contents of an AssetBundle or SerializedFile.")
             {
                 pathArg,
                 fOpt,
                 sOpt,
                 oOpt,
+                objectIdOpt,
             };
             dumpCommand.SetHandler(
-                (FileInfo fi, DumpFormat f, bool s, DirectoryInfo o) => Task.FromResult(HandleDump(fi, f, s, o)),
-                pathArg, fOpt, sOpt, oOpt);
+                (FileInfo fi, DumpFormat f, bool s, DirectoryInfo o, long objectId) => Task.FromResult(HandleDump(fi, f, s, o, objectId)),
+                pathArg, fOpt, sOpt, oOpt, objectIdOpt);
 
             rootCommand.AddCommand(dumpCommand);
         }
@@ -173,14 +175,14 @@ static int HandleFindReferences(FileInfo databasePath, string outputFile, long?
         }
     }
 
-    static int HandleDump(FileInfo filename, DumpFormat format, bool skipLargeArrays, DirectoryInfo outputFolder)
+    static int HandleDump(FileInfo filename, DumpFormat format, bool skipLargeArrays, DirectoryInfo outputFolder, long objectId = 0)
     {
         switch (format)
         {
             case DumpFormat.Text:
             {
                 var textDumper = new TextDumperTool();
-                return textDumper.Dump(filename.FullName, outputFolder.FullName, skipLargeArrays);
+                return textDumper.Dump(filename.FullName, outputFolder.FullName, skipLargeArrays, objectId);
             }
         }
 

UnityDataTool/README.md

@@ -111,9 +111,10 @@ only supports the 'text' format, which is similar to the binary2text output form
 
 The command takes the path of the file to dump as argument. It also provides the following options:
 * -o, --output-path <output-path>  Output folder, default is the current folder.
-* -f, --output-format \<format\>: output format, default is 'text'.
+* -f, --output-format <format>: output format, default is 'text'.
 * -s, --skip-large-arrays: the contents of basic data type arrays with a large number of elements
   won't be dumped.
+* -i, --objectid <objectid>: only dump the object with this local file id. If not specified or 0, all objects will be dumped.
 
 Example: `UnityDataTool dump /path/to/file -o /path/to/output`