An asset can be assigned a catalog. Similar to files on disk, where a file can only exist in a single directory at a time (ignoring hard-links), an asset can only be associated with a single catalog at a time.
These catalogs are independent of the on-disk organisation of asset library files. This means that assets can be freely moved between blend files while staying in the same catalog, and vice versa.
Introduced in Blender 3.0.
Components of a Catalog
Each catalog consists of a catalog path, a UUID, and a simple name.
The path of a catalog determines where in the catalog hierarchy the catalog is shown. Examples are
Multiple catalogs can have the same path; in other words, multiple UUIDs can map to the same path. This is likely to happen with generic paths like
Materials/Metal when combining assets from various sources. These catalogs are unified and shown as one catalog in the user interface.
Each catalog has a UUID. This is what is stored in the asset, and what determines the "identity" of the catalog. As a result, a catalog can be renamed or moved around (i.e. you can change its path), and all assets that are contained in it will move along with it. This only requires a change to the catalog itself, and not to any asset blend file.
When creating a new catalog, Blender assigns it a random UUID. However, any valid, non-nil UUID can be used for catalogs. An asset can be assigned to the nil UUID, which means it's not contained in any catalog.
Each catalog has an optional simple name. This name is stored along with the UUID in each asset. The purpose is to make it possible for humans to recognise the catalog the asset was assigned to, even when the catalog definition file (see below) is lost.
Catalog Definition Files
Asset catalogs are stored in Catalog Definition Files (CDFs). Currently, each asset library has one CDF,
Catalog Definition Files (CDFs) are relatively simple text files, encoded in UTF-8.
Each CDF consists of a version indicator, and a line of text per catalog.
Each catalog line is colon-separated, of the form
Multiple catalogs can have the same path, as described above. If there are multiple catalog definitions with the same UUID, the first one "wins" and the rest is ignored.
For example, this is a valid catalog definition file:
# This is an Asset Catalog Definition file for Blender. # # Empty lines and lines starting with `#` will be ignored. # The first non-ignored line should be the version indicator. # Subsequent lines are of the format "CATALOG_UUID:catalog/path/for/assets:simple catalog name" VERSION 1 cd66bf52-58f4-45cb-a4e2-dc0e0ee8f3fe:/character/Elly/poselib:POSES_ELLY 4eb44ec6-3424-405b-9782-ca006953e799:character/Elly/poselib/white space:POSES_ELLY_WHITESPACE ee9c7b60-02f1-4058-bed6-539b8d2a6d34:/character/Elly/poselib/:POSES_ELLY_TRAILING_SLASH b63ed357-2511-4b96-8728-1b5a7093824c:character/Ružena/poselib:Ružena pose library fb698f2e-9e2b-4146-a539-3af292d44899:character/Ružena/poselib/hand:Ružena hands dcdee4df-926e-4d72-b995-33106983bb9a:character/Ružena/poselib/face:Ružena face 313ea471-7c81-4de6-af81-fb04c3535d0e:catalog/without/simple/name
After reading it, Blender will reformat it to look like this:
# This is an Asset Catalog Definition file for Blender. # # Empty lines and lines starting with `#` will be ignored. # The first non-ignored line should be the version indicator. # Subsequent lines are of the format "CATALOG_UUID:catalog/path/for/assets:simple catalog name" VERSION 1 313ea471-7c81-4de6-af81-fb04c3535d0e:catalog/without/simple/name: ee9c7b60-02f1-4058-bed6-539b8d2a6d34:character/Elly/poselib:POSES_ELLY_TRAILING_SLASH cd66bf52-58f4-45cb-a4e2-dc0e0ee8f3fe:character/Elly/poselib:POSES_ELLY 4eb44ec6-3424-405b-9782-ca006953e799:character/Elly/poselib/white space:POSES_ELLY_WHITESPACE b63ed357-2511-4b96-8728-1b5a7093824c:character/Ružena/poselib:Ružena pose library dcdee4df-926e-4d72-b995-33106983bb9a:character/Ružena/poselib/face:Ružena face fb698f2e-9e2b-4146-a539-3af292d44899:character/Ružena/poselib/hand:Ružena hands
Valid Catalog Paths
Catalog paths in the catalog definition files have to follow the following rules:
- All paths are absolute, so there is no difference between
/as separator (no
\; think less filesystem path and more URL).
- Not empty (it's required for a valid catalog).
- No empty components (so not
- Invalid characters:
- Paths are always interpreted as UTF-8.
When the asset system reads the catalog definitions, or when the paths where changed in another way (e.g. by renaming catalogs in the UI), the paths are "normalized" by doing the following:
- Remove any leading or trailing
/characters are escaped by replacing them with
The asset system code only uses this "normalized" version of the path.
Writing to Disk
Catalogs are written to disk when the blend file is saved (this is still under consideration and can change). At this moment only a single catalog definition file (CDF) per asset library is supported; CDFs are always named
The location of the CDF is chosen as follows. The first rule that describes the situation "wins" and determines the location:
- If the catalogs were loaded from disk (for example by selecting an existing library with existing catalogs in the asset browser), any changes/additions are written to the same file.
- If the blend file is saved in a known asset library (i.e. configured in the preferences), any changes/additions are written to the top-level directory of that asset library.
- Otherwise the CDF is saved in the same directory as the blend file.