2021-09-07 Asset Catalogs

Attendees: Jacques Lucke, Julian Eisel, Sybren Stüvel

Meeting to discuss and iterate on the technical design of asset catalog definitions.


  • Catalogs are introduced here: Asset Browser Workshop Outcomes — Blender Developers Blog
  • Asset catalogs are defined in catalog definition files in the asset library. E.g. a blender_assets.cats.txt file in the asset library’s root directory.
  • The files should be human readable and writable.
  • “Normal” users shouldn’t have to touch them. But e.g. TDs managing a studio’s assets may want to.
  • Blender is not allowed to touch external Blend files.

Current Design

  • Each catalog would be defined by a catalog ID and a path. For example POSES_ELLY /Character/Elly/Poses - POSES_ELLY is the catalog ID, the rest the path.
  • Assets store the catalog ID of the catalog they are in.
  • Problems:
    • What happens to the catalog ID when renaming? We can’t automatically update it, since it’s likely stored in assets of external files.
    • There is no namespace for catalog IDs, conflicts happen easily.

Changes to the Design

To address these problems, we agreed on the following design changes:

  • The catalog ID gets replaced by a 16 byte UUID (entirely random), e.g.:
    • This way we don’t ever have to change the catalog (UU)ID after it’s been created. Neither do we have to touch external Blend files.
  • To still keep this human readable, the UUID is listed together with the current catalog path.
    • If a catalog path changes, Blender needs to update it in the catalog definition file(s).
    • Proposed format uuid:catalog-path, e.g.:
  • For debugging, or potentially even for the UI (e.g. searching), it can be helpful to have an extended catalog name, e.g. "Elly Poses".
    • Can optionally be attached to a catalog definition:
      cd66bf52-58f4-45cb-a4e2-dc0e0ee8f3fe:/character/Elly/poselib:Elly Poses
  • If Blender sees a path where there isn’t a catalog definition for each segment, Blender generates it (i.e. by generating the UUID and extending the catalog definition file).
  • Add a version number to the beginning of the file, for forward compatibility (and later on backward compatibility).


Example of a valid catalog definition file, following the new format:



  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
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


After reading it, Blender would re-format and store it 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"


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