More accurate SerializedFile header parsing

SkowronskiAndrew · SkowronskiAndrew · commit d2a99cdac558 · 2026-02-20T06:31:50.000-05:00
diff --git a/Analyzer.Tests/FileDetectionTests.cs b/Analyzer.Tests/FileDetectionTests.cs
@@ -43,7 +43,7 @@ public void TryDetectSerializedFile_ValidPlayerDataFile_ReturnsTrue()
         Assert.That(info.FileSize, Is.EqualTo(31988UL), "FileSize should be 31988");
         Assert.That(info.MetadataSize, Is.EqualTo(24580UL), "MetadataSize should be 24580");
         Assert.That(info.DataOffset, Is.EqualTo(24640UL), "DataOffset should be 24640");
-        Assert.That(info.Endianness, Is.EqualTo((byte)1), "Endianness should be 1 (BigEndian)");
+        Assert.That(info.Endianness, Is.EqualTo((byte)0), "Endianness should be 0 (LittleEndian)");
         Assert.IsFalse(info.IsLegacyFormat, "Version 22 uses modern format (64-bit header)");
     }
 
@@ -64,7 +64,7 @@ public void TryDetectSerializedFile_SerializedFileInsideArchive_ReturnsTrue()
         Assert.That(info.FileSize, Is.EqualTo(595380UL), "FileSize should be 595380");
         Assert.That(info.MetadataSize, Is.EqualTo(61328UL), "MetadataSize should be 61328");
         Assert.That(info.DataOffset, Is.EqualTo(61360UL), "DataOffset should be 61360");
-        Assert.That(info.Endianness, Is.EqualTo((byte)1), "Endianness should be 1 (BigEndian)");
+        Assert.That(info.Endianness, Is.EqualTo((byte)0), "Endianness should be 0 (LittleEndian)");
         Assert.IsTrue(info.IsLegacyFormat, "Version 17 uses legacy format (32-bit header)");
     }
 
diff --git a/Analyzer/Util/SerializedFileDetector.cs b/Analyzer/Util/SerializedFileDetector.cs
@@ -19,33 +19,36 @@ public class SerializedFileInfo
 /// <summary>
 /// Utility for detecting Unity SerializedFile format by reading and validating the file header.
 ///
-/// Unity SerializedFiles have two different header formats based on version:
+/// Unity SerializedFiles have evolved through several format versions:
 ///
-/// Legacy Format (versions &lt; 22 / kLargeFilesSupport):
-///   - 20 byte header using 32-bit offsets/sizes
-///   - Endianness byte is stored at the END of the file, just before metadata
+/// Version &lt; 9:
+///   - 20-byte header (SerializedFileHeader32) with 32-bit offsets/sizes
+///   - Layout: [header][data][metadata]
+///   - Endianness byte stored at END of file, just before metadata
+///
+/// Version 9-21:
+///   - 20-byte header (SerializedFileHeader32) with 32-bit offsets/sizes
+///   - Layout: [header][metadata][data]
+///   - Endianness byte at offset 16 in header
 ///   - Limited to 4GB file sizes
 ///
-/// Modern Format (versions &gt;= 22 / kLargeFilesSupport):
-///   - 48 byte header using 64-bit offsets/sizes
-///   - Endianness byte is stored IN the header at offset 40
+/// Version &gt;= 22 (kLargeFilesSupport):
+///   - 48-byte header (SerializedFileHeader) with 64-bit offsets/sizes
+///   - Layout: [header][metadata][data]
+///   - Endianness byte at offset 40 in header
 ///   - Supports files larger than 4GB
 ///
-/// This implementation is based on Unity's SerializedFile.cpp::ReadHeader() from:
-/// D:\UnitySrc\unity\Runtime\Serialize\SerializedFile.cpp
+/// Important: The header itself is always stored in big-endian format on disk,
+/// but the m_Endianess byte indicates the endianness of the actual data section.
 /// </summary>
 public static class SerializedFileDetector
 {
-    // Version boundary where header format changed from 32-bit to 64-bit
-    // Corresponds to SerializedFileFormatVersion::kLargeFilesSupport
-    private const uint LargeFilesSupportVersion = 22;
-
-    // Version where endianness byte was moved into the header at offset 40
-    // Prior to this, even modern format files had endianness at the end of the file
-    private const uint EndiannessInHeaderVersion = 23;
+    // Version boundaries for format changes
+    private const uint NewLayoutVersion = 9;           // kUnknown_9: Changed from [header][data][metadata] to [header][metadata][data]
+    private const uint LargeFilesSupportVersion = 22;  // kLargeFilesSupport: Changed to 64-bit header
 
     // Reasonable version range for SerializedFiles
-    // Unity is currently in the 20s-30s range, so we accept 1-50
+    // Unity versions currently use values in the 20s-30s range
     private const uint MinVersion = 1;
     private const uint MaxVersion = 50;
 
@@ -54,8 +57,8 @@ public static class SerializedFileDetector
     private const byte BigEndian = 1;
 
     // Header sizes
-    private const int LegacyHeaderSize = 20;
-    private const int ModernHeaderSize = 48;
+    private const int LegacyHeaderSize = 20;  // SerializedFileHeader32
+    private const int ModernHeaderSize = 48;  // SerializedFileHeader
 
     /// <summary>
     /// Attempts to detect if a file is a Unity SerializedFile by reading and validating its header.
@@ -92,28 +95,27 @@ public static bool TryDetectSerializedFile(string filePath, out SerializedFileIn
             // STEP 1: Read version to determine header format
             // ============================================================
 
-            // The version field is at the same offset in both formats:
-            // - Legacy header: bytes 8-11 (UInt32)
-            // - Modern header: bytes 8-11 (UInt32)
+            // The version field is always at offset 8 in both header formats.
+            // The header itself is always stored in big-endian format on disk.
+            // On little-endian platforms (Windows, etc.), we need to swap the header fields.
             //
-            // We need to handle potential endianness swap. Try reading the version
-            // in little-endian first, and if it's out of range, try swapping.
+            // We try both interpretations to determine if swapping is needed:
             uint versionLE = BitConverter.ToUInt32(headerBytes, 8);
             uint versionBE = SwapUInt32(versionLE);
 
-            // Determine which endianness gives us a valid version
+            // Determine which interpretation gives us a valid version number
             uint version;
-            bool needsSwap;
+            bool needsSwap;  // Whether header fields need byte swapping
 
             if (versionLE >= MinVersion && versionLE <= MaxVersion)
             {
-                // Little-endian interpretation is valid
+                // Reading as little-endian gives valid version (header is in little-endian format)
                 version = versionLE;
                 needsSwap = false;
             }
             else if (versionBE >= MinVersion && versionBE <= MaxVersion)
             {
-                // Big-endian interpretation is valid
+                // Reading as big-endian gives valid version (header is in big-endian format)
                 version = versionBE;
                 needsSwap = true;
             }
@@ -123,26 +125,37 @@ public static bool TryDetectSerializedFile(string filePath, out SerializedFileIn
                 return false;
             }
 
+            // Determine header format based on version
             bool isLegacyFormat = version < LargeFilesSupportVersion;
 
             // ============================================================
-            // STEP 2: Determine endianness and swap if needed
+            // STEP 2: Read endianness byte
             // ============================================================
+            //
+            // The m_Endianess byte indicates the endianness of the DATA section
+            // (not the header, which is always big-endian on disk).
+            // Location depends on version:
+            // - Version < 9:   At end of file (before metadata) - we skip reading it for detection
+            // - Version 9-21:  At offset 16 in the 20-byte header
+            // - Version >= 22: At offset 40 in the 48-byte header
+            //
+            // The endianness byte is never swapped (it's a single byte).
 
             byte endianness;
-            if (isLegacyFormat)
+
+            if (version < NewLayoutVersion)
             {
-                // Legacy format: Endianness byte is at the END of the file
-                // It's located just before the metadata section
-                // For detection purposes, we already determined endianness from the version field
+                // Version < 9: Endianness is at the end of the file
+                // For detection purposes, we infer it from the header byte order
+                // (though this is technically the header's endianness, not the data's)
                 endianness = needsSwap ? BigEndian : LittleEndian;
             }
-            else if (version >= EndiannessInHeaderVersion)
+            else if (isLegacyFormat)
             {
-                // Modern format (version >= 23): Endianness byte is at offset 40 in the header
-                if (bytesRead >= 41)
+                // Version 9-21: Endianness is at offset 16 in SerializedFileHeader32
+                if (bytesRead >= 17)
                 {
-                    endianness = headerBytes[40];
+                    endianness = headerBytes[16];
 
                     // Validate endianness value
                     if (endianness != LittleEndian && endianness != BigEndian)
@@ -155,20 +168,18 @@ public static bool TryDetectSerializedFile(string filePath, out SerializedFileIn
             }
             else
             {
-                // Version 22: Uses 64-bit header but endianness byte is still at end of file
-                // For detection purposes, use what we determined from the version field
-                endianness = needsSwap ? BigEndian : LittleEndian;
-            }
+                // Version >= 22: Endianness is at offset 40 in SerializedFileHeader
+                if (bytesRead >= 41)
+                {
+                    endianness = headerBytes[40];
 
-            // Verify the endianness byte matches what we detected from the version field
-            // Only do this for versions where endianness is in the header (>= 23)
-            if (!isLegacyFormat && version >= EndiannessInHeaderVersion)
-            {
-                bool endiannessIndicatesSwap = (endianness == BigEndian);
-                if (endiannessIndicatesSwap != needsSwap)
+                    // Validate endianness value
+                    if (endianness != LittleEndian && endianness != BigEndian)
+                        return false;
+                }
+                else
                 {
-                    // Endianness byte doesn't match what we detected - suspicious
-                    return false;
+                    return false; // File truncated
                 }
             }
 
@@ -180,15 +191,16 @@ public static bool TryDetectSerializedFile(string filePath, out SerializedFileIn
 
             if (isLegacyFormat)
             {
-                // Legacy Header Layout (20 bytes total):
+                // SerializedFileHeader32 Layout (20 bytes total):
                 // Offset 0-3:   UInt32 m_MetadataSize
                 // Offset 4-7:   UInt32 m_FileSize
                 // Offset 8-11:  UInt32 m_Version
                 // Offset 12-15: UInt32 m_DataOffset
-                // Offset 16-19: Reserved/padding
+                // Offset 16:    UInt8  m_Endianess (only present for version >= 9)
+                // Offset 17-19: UInt8  m_Reserved[3]
                 //
-                // Note: m_Endianess is NOT in the header for legacy format!
-                // It's stored at the end of the file before metadata.
+                // Note: For version < 9, m_Endianess is NOT in the header.
+                //       It's stored at the end of the file, just before metadata begins.
 
                 uint metadataSize32 = ReadUInt32(headerBytes, 0, needsSwap);
                 uint fileSize32 = ReadUInt32(headerBytes, 4, needsSwap);
@@ -200,23 +212,22 @@ public static bool TryDetectSerializedFile(string filePath, out SerializedFileIn
                 dataOffset = dataOffset32;
 
                 // Special case: Legacy format used UInt32.MaxValue to indicate "unknown" file size
-                // In 64-bit representation, this should be handled
                 if (fileSize32 == uint.MaxValue)
                 {
                     fileSize = ulong.MaxValue;
                 }
             }
             else
             {
-                // Modern Header Layout (48 bytes total):
-                // Offset 0-7:   Reserved (8 bytes)
-                // Offset 8-11:  UInt32 m_Version
-                // Offset 12-15: Reserved (4 bytes)
-                // Offset 16-23: UInt64 m_MetadataSize
-                // Offset 24-31: UInt64 m_FileSize
-                // Offset 32-39: UInt64 m_DataOffset
-                // Offset 40:    UInt8 m_Endianess
-                // Offset 41-47: Reserved (7 bytes)
+                // SerializedFileHeader Layout (48 bytes total):
+                // Offset 0-7:   UInt8[8] m_Legacy (unused, allows struct alignment with SerializedFileHeader32)
+                // Offset 8-11:  UInt32   m_Version
+                // Offset 12-15: UInt8[4] m_Reserved0 (explicit padding)
+                // Offset 16-23: UInt64   m_MetadataSize
+                // Offset 24-31: UInt64   m_FileSize
+                // Offset 32-39: UInt64   m_DataOffset
+                // Offset 40:    UInt8    m_Endianess
+                // Offset 41-47: UInt8[7] m_Reserved1
 
                 metadataSize = ReadUInt64(headerBytes, 16, needsSwap);
                 fileSize = ReadUInt64(headerBytes, 24, needsSwap);
diff --git a/Documentation/command-serialized-file.md b/Documentation/command-serialized-file.md
@@ -2,6 +2,18 @@
 
 The `serialized-file` command (alias: `sf`) provides utilities for quickly inspecting SerializedFile metadata without performing a full analysis.
 
+This exposes information about the Binary SerializedFile format.  This format has evolved over time, but all recent versions have 
+* a small header section (exposed by the `header` subcommand)
+* a metadata section which contains summary of the data
+  * Unity Version and target platform
+  * typetree information
+  * the list of objects and offsets
+  * external references
+* the data section which contains the Unity objects in serialized form
+
+The 'externalrefs' and 'objectlist' sub-commands expose information from the metadata section.
+The `dump` command can be used to view the serialized objects.
+
 ## Sub-Commands
 
 | Sub-Command | Description |
@@ -175,7 +187,7 @@ UnityDataTool serialized-file header level0 --format json
   "fileSize": 31988,
   "metadataSize": 24580,
   "dataOffset": 24640,
-  "endianness": "Big Endian"
+  "endianness": "Little Endian"
 }
 ```
 
@@ -188,7 +200,7 @@ UnityDataTool serialized-file header level0 --format json
 | **File Size** | Total size of the SerializedFile in bytes. Padding might make the actual file size slightly larger. |
 | **Metadata Size** | Size of the metadata section containing type information and object indices. |
 | **Data Offset** | Byte offset where the object data section begins in the file. |
-| **Endianness** | Byte order of the file: "Little Endian" (x86, most platforms) or "Big Endian" (older console platforms). |
+| **Endianness** | Byte order of the data in the file: "Little Endian" (x86, most platforms) or "Big Endian" (older console platforms). |
 
 ---
 
diff --git a/TestCommon/Data/YamlFormat.asset b/TestCommon/Data/YamlFormat.asset
@@ -0,0 +1,15 @@
+%YAML 1.1
+%TAG !u! tag:unity3d.com,2011:
+--- !u!114 &11400000
+MonoBehaviour:
+  m_ObjectHideFlags: 0
+  m_CorrespondingSourceObject: {fileID: 0}
+  m_PrefabInstance: {fileID: 0}
+  m_PrefabAsset: {fileID: 0}
+  m_GameObject: {fileID: 0}
+  m_Enabled: 1
+  m_EditorHideFlags: 0
+  m_Script: {fileID: 11500000, guid: 070349760c9dbfd4e8318d73401cca23, type: 3}
+  m_Name: SimpleScriptableObjectAsset1
+  m_EditorClassIdentifier: 
+  Data: 67
