From 2cafa9fe6e51cb0fac0b660608ac999419fb9399 Mon Sep 17 00:00:00 2001 From: Abhinav Date: Sat, 11 Jul 2026 12:02:05 +0530 Subject: [PATCH 1/2] Document AssetBundle dependency references --- Documentation/assetbundle-format.md | 46 +++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/Documentation/assetbundle-format.md b/Documentation/assetbundle-format.md index 15f0620..ca1575d 100644 --- a/Documentation/assetbundle-format.md +++ b/Documentation/assetbundle-format.md @@ -40,6 +40,48 @@ understand them for normal use, but they show up throughout UnityDataTool output - The Scriptable Build Pipeline / Addressables uses `CAB-`. - The Multi-Process Build Pipeline (2023.1+) uses `CAB-`. +## Bundle dependencies and object references + +AssetBundle dependencies exist at two related but different levels: + +- The AssetBundle object records bundle-level dependencies by name in `m_Dependencies`. +- Serialized objects record object-level references as `PPtr`s, which point to a file and a local + object id. + +The bundle filename itself is not written into every object reference. Instead, loading a bundle +mounts its archive and makes the SerializedFiles inside it available to Unity's object resolver. +When Unity follows a `PPtr`, it resolves the reference through the current SerializedFile and that +file's external reference table. + +A `PPtr` has two important fields: + +- `m_FileID` - `0` means the target object is in the same SerializedFile. Values `1`, `2`, and so on + refer to entries in that SerializedFile's external reference table. +- `m_PathID` - the target object's local object id inside the resolved SerializedFile. + +This means that two different bundles can have different filenames while still referencing each +other through the SerializedFiles mounted from those bundles. The AssetBundle object's +`m_Dependencies` list tells Unity which other bundles must be loaded so those external +SerializedFiles are available. The object references then point into those files by `m_FileID` and +`m_PathID`. + +For example, if an object in `characters.bundle` references a material in `materials.bundle`, the +object's `PPtr` does not usually contain the string `materials.bundle`. The source SerializedFile +contains an external reference entry that identifies the target SerializedFile, and the AssetBundle +object records `materials.bundle` as a bundle dependency so Unity knows which archive to mount. + +In UnityDataTool output, these layers appear in different places: + +- The containing archive or bundle file appears as `archive` in `object_view`. +- The mounted SerializedFile appears as `serialized_file` in `object_view`. +- Object-to-object references appear in the `refs` table when `analyze` runs with reference + extraction enabled. +- Preload relationships from the AssetBundle object and scene `PreloadData` appear in + `preload_dependencies`. + +Keeping those layers separate helps explain why a query over `refs` may show cross-bundle +relationships without directly mentioning an AssetBundle filename on each reference row. + ## Inspecting a bundle with UnityDataTool The [`archive`](command-archive.md) command lists or extracts the files inside a bundle, and @@ -238,6 +280,10 @@ large dependency graphs by loading some assets on demand (via Addressables, Asse The [`analyze`](analyzer.md) command turns the above into queryable tables: +- Each object is linked to both its `serialized_file` and, when applicable, its containing `archive` + in `object_view`. +- Object references extracted from `PPtr` fields become rows in `refs`; these rows are resolved to + analyzer object ids rather than storing AssetBundle filenames directly. - Each explicit `m_Container` asset becomes a row in `assetbundle_assets`, and its preload slice becomes rows in `preload_dependencies`. - Because a scene has no Unity object, `analyze` synthesizes a "Scene" object per scene to stand in From ac063f794517ec4d6db96e81f2fd9f6b10c59097 Mon Sep 17 00:00:00 2001 From: Abhinav Date: Mon, 13 Jul 2026 19:51:24 +0530 Subject: [PATCH 2/2] Clarify AssetBundle dependency loading docs --- Documentation/assetbundle-format.md | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/Documentation/assetbundle-format.md b/Documentation/assetbundle-format.md index ca1575d..f85389e 100644 --- a/Documentation/assetbundle-format.md +++ b/Documentation/assetbundle-format.md @@ -44,7 +44,9 @@ understand them for normal use, but they show up throughout UnityDataTool output AssetBundle dependencies exist at two related but different levels: -- The AssetBundle object records bundle-level dependencies by name in `m_Dependencies`. +- The AssetBundle object records bundle-level dependencies in `m_Dependencies`: as AssetBundle + names for `BuildPipeline.BuildAssetBundles`, or as internal SerializedFile names for Scriptable + Build Pipeline / Addressables builds. - Serialized objects record object-level references as `PPtr`s, which point to a file and a local object id. @@ -60,15 +62,22 @@ A `PPtr` has two important fields: - `m_PathID` - the target object's local object id inside the resolved SerializedFile. This means that two different bundles can have different filenames while still referencing each -other through the SerializedFiles mounted from those bundles. The AssetBundle object's -`m_Dependencies` list tells Unity which other bundles must be loaded so those external -SerializedFiles are available. The object references then point into those files by `m_FileID` and -`m_PathID`. +other through the SerializedFiles mounted from those bundles. The application is still responsible +for loading dependency bundles. With `BuildPipeline.BuildAssetBundles`, the `AssetBundleManifest` +tells the application which bundles to load; with Addressables, the Addressables catalog does that +job. Unity's runtime does not auto-load bundles from `m_Dependencies`. + +At runtime, `m_Dependencies` is used only in narrower lookup paths, such as searching already-loaded +dependency bundles for preload objects. If a named dependency bundle is not loaded, Unity skips it +rather than loading it automatically. Once the needed SerializedFiles are mounted, object references +point into those files by `m_FileID` and `m_PathID`. For example, if an object in `characters.bundle` references a material in `materials.bundle`, the -object's `PPtr` does not usually contain the string `materials.bundle`. The source SerializedFile -contains an external reference entry that identifies the target SerializedFile, and the AssetBundle -object records `materials.bundle` as a bundle dependency so Unity knows which archive to mount. +object's `PPtr` does not contain the string `materials.bundle`. The source SerializedFile contains +an external reference entry that identifies the target SerializedFile by its internal path, for +example `archive:/CAB-/CAB-`. The dependency relationship in `m_Dependencies` helps +Unity search among already-loaded dependency bundles for preload objects, but the application still +uses the AssetBundleManifest or Addressables catalog to decide which archive files to load. In UnityDataTool output, these layers appear in different places: @@ -105,7 +114,9 @@ exposes and what each of them needs preloaded. Its important fields are: `preloadIndex`/`preloadSize` range describing that asset's dependencies (see below). - `m_PreloadTable` - a flat list of `PPtr`s. Each container entry references a contiguous slice of this list. -- `m_Dependencies` - the names of other bundles this bundle depends on. +- `m_Dependencies` - the other bundles or internal SerializedFiles this bundle depends on, stored + as AssetBundle names for `BuildPipeline.BuildAssetBundles` or as internal SerializedFile names + for Scriptable Build Pipeline / Addressables builds. - `m_IsStreamedSceneAssetBundle` - true for scene bundles. - `m_SceneHashes` - for scene bundles, a map from each scene path to the SerializedFile that holds it (populated by SBP/Addressables only; see [Scenes in AssetBundles](#scenes-in-assetbundles)).