[#130] Explain SerializeReference in the dump docs, and say the format once

The dump page now leads with what a reader sees - a managedReference field holds
a rid, not an object - and shows a script whose three fields demonstrate the
points being made: two assigned the same instance, one left null. The previous
example had a single field called "reference" of type "managedReference", which
made it hard to tell which name came from the script and which from the format.

The format itself was explained in five places in near-identical words. The full
explanation now lives once, beside ProcessManagedReferenceRegistry, which is the
code that needs it. ManagedReferenceRegistry keeps a shorter one because it is
public API of the UnityFileSystem library and has to stand alone; the three
walkers just say what their own line does.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: SkowronskiAndrew

Analyzer/PPtrAndCrcProcessor.cs

@@ -99,10 +99,9 @@ public uint Process(long objectId, long offset, long size, TypeTreeNode node)
 
         foreach (var child in node.Children)
         {
-            // From SerializedFile version 25 the registry is a frame leading the C# class's data,
-            // which no node describes; the flag marks the field it precedes. Only a root object's
-            // fields carry one. The frame is not part of that field, so its references get their own
-            // path root, named after the registry as the node-described versions are.
+            // A version 3 registry sits here rather than in a node (see
+            // ProcessManagedReferenceRegistry). It is not part of the field that follows it, so its
+            // references get their own path root, named as the node-described versions are.
             if (child.HasSerializedRefs)
             {
                 m_StringBuilder.Clear();
@@ -345,10 +344,17 @@ private void ProcessArray(TypeTreeNode node, bool isManagedReferenceRegistry, bo
     //   version 1 - entries stored back to back and terminated by a sentinel type (see
     //               ProcessManagedReferenceData); the rid is implied by position.
     //   version 2 - entries stored as a "RefIds" array, each element carrying its own rid.
-    //   version 3 - from SerializedFile version 25 (Unity 6.7). No longer a node at all: the
-    //               registry is a self-delimiting frame in the object's data, ahead of the field
-    //               flagged HasSerializedRefs, holding a table of type names and a table of
-    //               records that index it. See ProcessManagedReferenceFrame.
+    //   version 3 - from SerializedFile version 25 (Unity 6.7). No node describes it at all: the
+    //               registry is a self-delimiting frame of raw bytes leading the C# class's own
+    //               data, so it sits after the built-in fields (m_GameObject, m_Name, ...) and
+    //               before the first field the script declares - which is the field flagged
+    //               HasSerializedRefs, whether or not that field is itself a reference. It holds a
+    //               table of type names and a table of records indexing into it; a record can be a
+    //               null entry, which v1 and v2 could not express. Only a root object's data
+    //               carries a frame: the same TypeTree used to lay out an instance's data inside
+    //               the registry keeps the flag but has no frame, which is why every walker honours
+    //               it only while iterating a root object's fields.
+    //               ManagedReferenceRegistry reads it; see ProcessManagedReferenceFrame here.
     private void ProcessManagedReferenceRegistry(TypeTreeNode node)
     {
         if (node.Children.Count < 2)

Documentation/command-dump.md

@@ -183,30 +183,80 @@ ID: -8138362113332287275 (ClassID: 135) SphereCollider
     z float 0
 ```
 
-A MonoBehaviour or ScriptableObject with `[SerializeReference]` fields also gets a `references`
-section. The fields themselves only store a `rid`; the instance each one points at is listed once in
-`references`, with its concrete C# type and its values:
+### `[SerializeReference]` fields
+
+A field marked `[SerializeReference]` in C# appears in the dump with the type **`managedReference`**,
+and its value is not the object - it is a number called a **`rid`** (reference id). The objects
+themselves are listed together in a `references` section, once each, with their concrete C# type and
+their field values.
+
+Take this script:
+
+```csharp
+public class Inventory : MonoBehaviour
+{
+    [Serializable]
+    public class Item
+    {
+        public string name;
+        public int count;
+    }
+
+    [SerializeReference] public Item primary;
+    [SerializeReference] public Item backup;
+    [SerializeReference] public Item spare;
+}
+```
+
+with `primary` and `backup` both assigned the *same* `Item`, and `spare` left null. Dumping it:
 
 ```
-  m_Name (string) ScriptableObjectWIthSerializeReference
+ID: 3862108129085620391 (ClassID: 114) MonoBehaviour
+  m_GameObject (PPtr<GameObject>)
+    m_FileID (int) 0
+    m_PathID (SInt64) -5904263129458716409
+  m_Enabled (UInt8) 1
+  m_Script (PPtr<MonoScript>)
+    m_FileID (int) 1
+    m_PathID (SInt64) 1197423208934291241
+  m_Name (string)
   references (ManagedReferenceRegistry)
     version (int) 3
-    rid(6911265806470873295) ReferencedObject
+    rid(-2) ReferencedObject
+      null
+    rid(3218405420927320064) ReferencedObject
       type (ReferencedManagedType)
-        class (string) Data
-        ns (string) MyNamespace
+        class (string) Inventory/Item
+        ns (string)
         asm (string) Assembly-CSharp
       data ReferencedObjectData
-        Info (string) Some info
-        Flag (UInt8) 1
-  reference (managedReference)
-    rid (SInt64) 6911265806470873295
+        name (string) Health potion
+        count (int) 3
+  primary (managedReference)
+    rid (SInt64) 3218405420927320064
+  backup (managedReference)
+    rid (SInt64) 3218405420927320064
+  spare (managedReference)
+    rid (SInt64) -2
 ```
 
-Two fields assigned the same instance share a `rid`, so it still appears only once. A field set to
-null shows `rid (SInt64) -2`, listed as a `null` entry. The `version` line reflects how the registry
-is stored, which changed in Unity 6.7 - the entries mean the same thing either way, but the section
-appears after the referencing fields in older files and before them in 6.7 and later.
+Reading it:
+
+* **`primary` and `backup` show the same `rid`.** They are two references to one object, so the
+  object is listed once and the sharing is visible - this is the whole point of
+  `[SerializeReference]` over a plain serialized field, which would have stored two independent
+  copies.
+* **`spare` shows `rid (SInt64) -2`**, the marker for null, and the matching entry is listed as
+  `null` with no type or data.
+* **`class` is the concrete runtime type**, which can be a subclass of the field's declared type -
+  that is what `[SerializeReference]` is for. Nested classes use a `/`, as in `Inventory/Item`.
+* The entries are listed in the order the file stores them, which is not necessarily the order the
+  fields appear in.
+
+The `version` line describes how the registry is stored rather than anything about your data. It is
+`3` for content built with Unity 6.7 or newer and `2` before that, and in older files the
+`references` section appears *after* the fields instead of before them. The entries mean the same
+thing either way.
 
 **Refer to the [TextDumper documentation](textdumper.md) for detailed output format explanation.**
 

TextDumper/TextDumperTool.cs

@@ -340,9 +340,8 @@ void RecursiveDump(TypeTreeNode node, ref long offset, int level, int arrayIndex
         {
             foreach (var child in node.Children)
             {
-                // From SerializedFile version 25 the registry is a frame leading the C# class's
-                // data, described by no node; the flag marks the field it precedes. Only a root
-                // object's data carries one; the same tree read as a registry blob is frameless.
+                // A version 3 registry sits in the data before this field, with no node of its
+                // own. Only a root object carries one, hence isRootObject.
                 if (isRootObject && child.HasSerializedRefs)
                     DumpManagedReferenceFrame(ref offset, level + 1);
 
@@ -488,8 +487,7 @@ void DumpManagedReferenceRegistry(TypeTreeNode node, ref long offset, int level)
         }
     }
 
-    // Dumps a version 3 registry, which is a frame in the object's data rather than a node. The
-    // output is shaped like the version 1 and 2 dumps above so the three stay comparable.
+    // Shaped like the version 1 and 2 dumps above, so the three stay comparable in a diff.
     void DumpManagedReferenceFrame(ref long offset, int level)
     {
         var registry = ManagedReferenceRegistry.ReadFrame(m_Reader, offset, m_ObjectEnd - offset);

UnityFileSystem/ManagedReferenceRegistry.cs

@@ -23,20 +23,16 @@ public sealed class ManagedReferenceEntry
     public long DataOffset { get; init; }
 }
 
-// The [SerializeReference] instances owned by one serialized object.
+// The [SerializeReference] instances owned by one serialized object, however the file stores them.
 //
-// From SerializedFile version 25 the registry is a self-delimiting frame leading the C# class's own
-// data - after the built-in fields, before the first field the script declares, which is the one
-// flagged HasSerializedRefs. It is the first piece of object layout no TypeTree node describes, so
-// the tables inside it cannot be walked the way every other field is.
+// From SerializedFile version 25 they live in a self-delimiting frame of raw bytes that no TypeTree
+// node describes, sitting immediately before the field flagged HasSerializedRefs. Earlier files
+// describe the registry with nodes, and callers read those through the node walk into these same
+// entries.
 //
-// They are not parsed here either: UFS_GetRegistryFrame* wraps the engine's own frame parser, so
-// this class calls into the one implementation that exists rather than becoming a second one. Only
-// the 8-byte header is read directly, in GetFrameSize, which is all a walker needs to step over a
-// frame it does not want to read.
-//
-// Earlier files describe the registry with TypeTree nodes instead (versions 1 and 2 of the registry
-// itself), which the callers read through the node walk and present as the same entries.
+// The frame's tables are not parsed here: UFS_GetRegistryFrame* wraps the engine's own parser, so
+// this calls the one implementation that exists rather than becoming a second one. Only the 8-byte
+// header is read directly, in GetFrameSize.
 public sealed class ManagedReferenceRegistry
 {
     // The only frame layout the native parser accepts. Unrelated to the serialized file version.

UnityFileSystem/TypeTreeNode.cs

@@ -49,9 +49,9 @@ public class TypeTreeNode
     // True if the field is a ManagedReferenceRegistry
     public bool IsManagedReferenceRegistry => ((int)Flags & (int)TypeTreeFlags.IsManagedReferenceRegistry) != 0;
 
-    // True if the [SerializeReference] registry frame precedes this field's data. The flag rides
-    // the first field of the declaring class, whether or not that field is itself a reference. Only
-    // set on a root object's fields; the same tree read as a registry blob carries no frame.
+    // True if a version 3 [SerializeReference] registry sits in the data immediately before this
+    // field. The flag rides the declaring class's first field, reference or not, and is meaningful
+    // only when the tree is read as an object root. See ManagedReferenceRegistry.
     public bool HasSerializedRefs => ((int)Flags & (int)TypeTreeFlags.HasSerializedRefs) != 0;
 
     // True if the node stands in for a compound the file stores once and shares between types

UnityFileSystem/TypeTreeReaders/RandomAccessReader.cs

@@ -27,8 +27,7 @@ public class RandomAccessReader : IEnumerable<RandomAccessReader>
     Dictionary<string, RandomAccessReader> m_ChildrenCacheObject;
     List<RandomAccessReader> m_ChildrenCacheArray;
     private TypeTreeNode m_TypeTreeNode;
-    // Only an object's root data carries a [SerializeReference] registry frame; the same type tree
-    // read as a registry blob does not, so the frame is honoured in root context only.
+    // A registry frame is honoured in root context only; a referenced instance's data has none.
     bool m_IsRoot;
     ManagedReferenceRegistry m_Registry;
     // Where this object's registry frame starts, once the field walk has passed it. -1 until then,
@@ -351,9 +350,8 @@ RandomAccessReader GetChild(string name)
         {
             var child = m_TypeTreeNode.Children[i];
 
-            // From SerializedFile version 25 the registry is a frame leading the C# class's data,
-            // described by no node, so the marked field's data starts past it. Only its size is
-            // needed to get there; Registry reads the tables if anyone asks for them.
+            // A version 3 registry sits in the data before this field, so the field starts past
+            // it. Only its size is needed to get there; Registry reads the tables on demand.
             if (m_IsRoot && child.HasSerializedRefs)
             {
                 m_RegistryFrameOffset = offset;