catalog.json

catalog.json is a JSON file used by the com.unity.addressables package in the Unity game engine. It is a list of all assets used in a game.

The name of the file can be different in each game. Most often it is catalog_data.json, but other options like catalog_catalog.json have also been found. The suffix (like data or catalog) can be chosen by the game developer, and some games can even have multiple content catalogs with different suffixes.

In Unity, the contents of the catalog.json file can be accessed through the ContentCatalogData class.

JSON structure

• (root)
  • m_LocatorId (string) - Name of this catalog, for example: AddressablesMainContentCatalog
  • m_BuildResultHash (string) - Hash of the catalog build, for example: 71d0441090abbc8f1a7305f2ea3c8b62. Notably, it seems to be different from catalog.hash.
  • m_InstanceProviderData (provider object) - InstanceProvider information. See #Provider object structure for details.
  • m_SceneProviderData (provider object) - SceneProvider information. See #Provider object structure for details.
  • m_ResourceProviderData (array) - All available resource providers.
    • (provider object) - A ResourceProvider. See #Provider object structure for details.
  • m_ProviderIds (array) - List of some of the IDs from m_ResourceProviderData.
    • (string) - An ID of a resource provider, for example: UnityEngine.ResourceManagement.ResourceProviders.AssetBundleProvider.
  • m_InternalIds (array) - List of all internal IDs. These IDs are most likely used by the game, and this list is used to find details about the asset.
    • (string) - An internal ID. May be a weird path, for example: {UnityEngine.AddressableAssets.Addressables.RuntimePath}/Android/crilocaldata_assets_all.bundle; a 32-character-long hexadecimal string, for example: 033f3660efceadd40b8cd2845b485652; an asset path, for example: Assets/CriData/Addressables/dice20.daily.0.acb=4493e0.asset; a short name, for example: EfficientBlur; a URL, for example: http://rizastcdn.pigeongames.cn/default/Android/1a2a40bd550976c58c842045215f204e.bundle; and it probably can be any other UTF-8 string.
  • m_KeyDataString (string) - Base64 encoded string containing binary data. See #Key data binary format for details.
  • m_BucketDataString (string) - Base64 encoded string containing binary data. See #Bucket data binary format for details.
  • m_EntryDataString (string) - Base64 encoded string containing binary data. See #Entry data binary format for details.
  • m_ExtraDataString (string) - Base64 encoded string containing binary data. See #Extra data binary format for details.
  • m_resourceTypes (array) - A list of all of the types of assets in the catalog. (This field is lowercase.)
    • (object type object) - An object type, for example: {"m_AssemblyName": "UnityEngine.CoreModule, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null", "m_ClassName": "UnityEngine.TextAsset"}. See #Object type object structure for details.
  • m_InternalIdPrefixes (array) - Unknown. The array was found empty.

Provider object structure

• (root)
  • m_Id (string) - ID of this provider, for example: UnityEngine.ResourceManagement.ResourceProviders.AssetBundleProvider.
  • m_ObjectType (object type object) - Object type of this provider, for example: {"m_AssemblyName": "Unity.ResourceManager, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null", "m_ClassName": "UnityEngine.ResourceManagement.ResourceProviders.AssetBundleProvider"}. See #Object type object structure for details.
  • m_Data (string) - Additional data for this provider. So far, only empty strings have been found.

Object type object structure

• (root)
  • m_AssemblyName (string) - Assembly name of the object's class, for example: Unity.ResourceManager, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null.
  • m_ClassName (string) - This object's class name, for example: UnityEngine.ResourceManagement.ResourceProviders.AssetBundleProvider.

Binary formats

Note: All values are in little endian.

Key data binary format

Keys are mostly string values that identify a bucket uniquely. They are only used by buckets, and are not used by any other part of the format. Compared to UTF-8 and UTF-16 keys, very few keys actually use numeric values. For example, in Rizline, as of Asset Version 20.1.2.7.1fd57802dc, the catalog_catalog.json file contains 2879 keys; out of them, 2828 keys are in UTF-8, 42 keys are UTF-16 (these are keys that include non-ASCII characters), and only 9 keys are numeric.

• (root)
  • key_count (uint32) - 4-byte integer, indicating the amount of keys stored in the whole structure.
  • keys (array) - A list of keys. The length of the list can be determined by either using the key_count field, or reading until the end of the binary data.
    • (struct) - A key. The size of the struct is variable.
      • key_type (uint8) - 1-byte number, indicating the type of the key. Known key types are: 0 - UTF-8 key; 1 - UTF-16 key; 4 - int32 key.
      • key_content (union)
        • text_content (sized string struct) - Only present if key type is 0 or 1. The type of the string is UTF-8 if key_type is 0 and UTF-16 (little endian) if key_type is 1. This field is the key's name. See #Sized string binary format for details.
        • numeric_content (uint32) - Only present if key type is 4. This field is the key's name.

Bucket data binary format

A bucket can be thought of as an arbitrary list of addressable entries with a name (key) attached to it. What the list actually means must be determined separately.

• (root)
  • bucket_count (uint32) - 4-byte integer, indicating the amount of buckets stored in the whole structure.
  • buckets (array) - A list of buckets. The length of the list can be determined by either using the bucket_count field, or reading until the end of the binary data.
    • (struct) - A bucket. The size of the struct is variable.
      • key_offset (uint32) - 4-byte integer, offset into the KeyData binary blob. Points to the beginning of a key entry associated with this bucket. The key can be thought of as being owned by this bucket, as no other bucket owns the same key, and the keys in the KeyData blob are not being pointed to by any other part of the system.
      • entry_count (uint32) - 4-byte integer, determining the amount of entries in the entries array.
      • entry_indices (array) - Array of 4-byte indices. The length of this array is determined by the entry_count field.
        • (uint32) - An index. This value is used to index the array that is contained within the binary blob encoded in m_EntryDataString. The index points to an Entry, that is in this bucket.

Entry data binary format

• (root)
  • addressable_entry_count (uint32) - 4-byte integer, indicating the amount of entries stored in the whole structure.
  • addressable_entries (array) - A list of addressable entries. The length of the list can be determined by either using the addressable_entry_count field, or reading until the end of the binary data.
    • (struct) - An addressable entry. The size of one entry is always 28 bytes (7 * 4 bytes).
      • internal_id_index (uint32) - 4-byte integer, index into the m_InternalIds array inside the parent catalog.json file.
      • resource_provider_index (uint32) - 4-byte integer, index into the m_ProviderIds array inside the parent catalog.json file.
      • dependencies_bucket_index (uint32) - 4-byte integer, index into the array that is contained within the binary blob encoded in m_BucketDataString. The referenced bucket contains this entry's dependencies - indices of other addressable entries, that need to be downloaded for this one to work properly.
      • bundled_asset_provider_crc (uint32) - 4-byte integer. This field is used only if the resource provider for this asset is UnityEngine.ResourceManagement.ResourceProviders.BundledAssetProvider. If that is the case, this field's value is seemingly random, ranging from 0 to 4294967295, most likely being some kind of CRC check. If the resource provider is different, this field's value is 0. ^[verify]
      • extra_data_block_offset (uint32) - 4-byte integer, offset into the ExtraData binary blob. Points to the beginning of an extra data entry associated with this entry.
      • siblings_bucket_index (uint32) - 4-byte integer, index into the array that is contained within the binary blob encoded in m_BucketDataString. The referenced bucket contains the family of this addressable entry - the key is like a name for the content of this entry, and other addressable entries that are in the bucket are the "siblings". Siblings ultimately point to the same asset, but have different resource types. For example, an image asset might have two family members: a UnityEngine.Texture2D entry, and a UnityEngine.Sprite entry.
      • resource_type_index (uint32) - 4-byte integer, index into the m_resourceTypes array inside the parent catalog.json file.

Extra data binary format

Extra data is a binary blob, that contains additional information for the entries. For example, if an entry is an Asset Bundle entry, ^[verify] the entry's extra_data_offset field points to a structure in this blob to determine the asset bundle name, the asset bundle hash, as well as download options for the asset bundle.

• (root)
  • extra_data_entries (array) - A list of entries. The length of this list should be determined by reading until the end of the binary data. This structure is probably not guaranteed to be an actual list, where each element is right next to another one -- it should be thought of as a heap of arbitrary data, with pointers stored in the extra_data_block_offset field within the EntryData binary.
    • (struct) - An entry with extra data. The size of the struct is variable.
      • magic_value (uint8) - 1-byte integer, always 7. The purpose of this value is unknown. ^[verify]
      • assembly_name_length (uint8) - 1-byte integer, length of the following string.
      • assembly_name (string) - UTF-8 string, the length is stored in the assembly_name_length field.
      • class_name_length (uint8) - 1-byte integer, length of the following string.
      • class_name (string) - UTF-8 string, the length is stored in the class_name_length field.
      • payload (sized string struct) - A little endian UTF-16 string containing JSON data. The JSON structure is described below. See #Sized string binary format and #AssetBundleRequestOptions object structure for details.

AssetBundleRequestOptions object structure

AssetBundleRequestOptions is a JSON document embedded within the extra data entry. It provides more information about downloadable asset bundles, for example, the asset bundle name, asset bundle hash, the size of the bundle and, other information.

• (root)
  • m_Hash (string) - The asset bundle hash.
  • m_Crc (number) - A CRC checksum of the bundle. ^[verify]
  • m_Timeout (number) - How much time before timing out. The unit is unknown. ^[verify]
  • m_ChunkedTransfer (bool) - Whether to allow chunked transfer. ^[verify]
  • m_RedirectLimit (number) - How many redirects to allow. -1 to disable. ^[verify]
  • m_RetryCount (number) - How many times to retry the request if failed. ^[verify]
  • m_BundleName (string) - The asset bundle name.
  • m_AssetLoadMode (number) - Unknown; always 0. ^[verify]
  • m_BundleSize (number) - The size of the bundle. The unit is unknown. ^[verify]
  • m_UseCrcForCachedBundles (bool) - Unknown; always true. ^[verify]
  • m_UseUWRForLocalBundles (bool) - Unknown; always false. ^[verify]
  • m_ClearOtherCachedVersionsWhenLoaded (bool) - Whether to delete old versions of this bundle when downloading an update.

Sized string binary format

• (root)
  • length (uint32) - 4-byte integer, determines the amount of bytes in the text field.
  • text (array) - Byte array with the contents of the string. The exact format (UTF-8 vs UTF-16) must be determined separately.
    • (uint8) - A byte of the string.