Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Library:Unity/Addressables catalog

From ReverseEngineering.wiki
Topic page of Library:Unity.

The Addressables content catalog (catalog.json or the binary catalog.bin, often wrapped in a bundle): how to recognise it, the JSON fields, the packed key/bucket/entry tables, the binary header and where bundle names, hashes and sizes are stored.

Overview

Unity Addressables (the com.unity.addressables package) loads content through a catalog that maps keys (addresses, labels, GUIDs) to resource locations: an internal id (a path or URL, usually of an AssetBundle), a provider class and dependencies. Local builds put it under StreamingAssets/aa/<platform>/ (catalog.json, catalog.bin, or catalog_<timestamp>.json/.bundle when remote and hashed) next to the bundles (<name>_assets_all_<hash>.bundle) and settings.json. A remote catalog may be a UnityFS bundle holding a single TextAsset. Format knowledge here comes from the MIT-licensed reader nesrak1/AddressablesTools; the Addressables package itself (Unity Companion License) was not copied.

Recognising the catalog type

  • JSON: the first non-blank byte is {.
  • Binary: the first four bytes are 42 89 E3 0D (int32 little endian 0x0DE38942); 0D E3 89 42 (0x4289E30D) would be a big-endian catalog, which AddressablesTools does not support.
  • Bundle: UnityFS magic (Format:Unity asset bundle (UnityFS)) with one serialized file and one TextAsset (name, then a size-prefixed byte array, 4-byte aligned) that holds either of the above.

Support matrix of the reader: JSON v1-v3, binary v1, v1.1, v2 (v3 read experimental).

JSON catalog (ContentCatalogData)

Fields: m_LocatorId, m_BuildResultHash (optional), m_InstanceProviderData, m_SceneProviderData, m_ResourceProviderData[] (each an object with id, object type and JSON data), m_ProviderIds[], m_InternalIds[], m_KeyDataString, m_BucketDataString, m_EntryDataString, m_ExtraDataString (four base64 strings), m_resourceTypes[], plus m_Keys[] in old versions (1.1.3 to 1.16.10) and m_InternalIdPrefixes[] in newer ones (1.16.10 to 1.21.3, when the catalog is compact).

Packed tables (little endian, after base64 decoding):

  • Bucket data: int32 count; per bucket int32 key offset (into the key data), int32 entry count, then that many int32 entry indices.
  • Key data: int32 count; each key is read at the offset of its bucket. A key is a type byte followed by its value (string, int, GUID-like string and so on, decoded by SerializedObjectDecoder).
  • Entry data: int32 count; each entry is seven int32: internal id index, provider index, dependency key index, dependency hash, data index (into extra data), primary key index, resource type index.
  • Extra data: per-entry serialized options; for AssetBundle locations this is the AssetBundleRequestOptions JSON: m_Hash (bundle hash), m_Crc, m_BundleName, m_BundleSize, plus timeouts and caching flags.
  • Internal id prefixes: when m_InternalIdPrefixes exists, an internal id of the form <n>#rest stands for m_InternalIdPrefixes[n] + rest.

So the bundle file name, its content hash, CRC and size are in the extra data of the entry whose provider is the AssetBundle provider; the internal id gives the path (often {UnityEngine.AddressableAssets.Addressables.RuntimePath}/<platform>/<name>.bundle).

Binary catalog

Header: int32 magic, int32 version (1 to 3 accepted by the reader), then uint32 offsets: keys, locator id, instance provider, scene provider, init objects array, and (not in the oldest v1 builds, recognised by keys offset 0x20) build result hash. Strings and arrays are read through these offsets; the tables are not base64.

Content state and hashes

Unverified: addressables_content_state.bin (in Assets/AddressableAssetsData/<platform>/ of the project, not shipped in the game) records every bundle's hash from the previous build so a content update only changes bundles whose content changed; the hash in the bundle file name comes from the build settings (hash appended to the file name, or the file name only). To check: compare a shipped catalog with the project's state file.

Tools

See Library:Unity for repositories (AddressablesTools, AssetRipper, AssetStudio, UnityPy). Bundles listed in a catalog are ordinary UnityFS bundles.

Related

Library:Unity, Library:Unity/Game folder layout.