Houdini 20.5 Digital assets

Creating and versioning digital assets

On this page

Overview

You can create a digital asset of any type (Object, Geometry node, Dynamics node) by converting a subnetwork of that type into a digital asset.

In the New Digital Asset dialog, you can set the label for the asset (the human-readable name for the asset which will be used in the user interface, for example Explodo Mucho), the internal name (the unchanging internal ID for the asset, which can include a namespace and version, for example acme::explodo_mucho::1.0), and the library file to save the asset into.

See how to install and use assets for how users can access the new asset after it is created.

How to create a digital asset

To...Do this

Prepare a subnet to turn into a digital asset

  • If you start by implementing the subnetwork before turning it into an asset, make sure you use relative references in expressions so they will still be valid inside the asset. For example, use ch('../copy1') instead of ch('/obj/geo1/subnet1/copy1').

    (When you try to turn a subnet into an asset, Houdini will warn you if you have references inside the subnet to nodes outside it, since they won’t work in an asset.)

  • To quickly put a bunch of nodes inside a subnetwork, select them, right click and choose Actions ▸ Collapse into Subnet.

Create a new digital asset from a subnet

  1. Right click the subnet and choose Create digital asset.

    Or, select the subnet node and choose Asset ▸ Create digital asset from selected.

    Houdini opens a dialog that lets you name the asset and decide where to save it.

  2. The Label is the human-readable name that shows up in Houdini’s user interface, for example Three Light Rig.

  3. The Tab Menu Submenu is the submenu this node (actually, this node’s first tool) will be under when the user browses the ⇥ Tab menu.

  4. The Internal Name is a unique internal name to distinguish it from other nodes, for example sanjay::threelightrig::1.0.

    You can expand the internal name group to show a builder interface that lets you control and set the individual parts of the name interactively, or collapse the group to only show a text box for the name.

    You can change the label later, but you can’t change the internal name without recreating the asset.

    The default Internal Name includes a namespace to ensure your node names don’t collide with Houdini’s node names or node names from other vendors, and a version to allow different versions of a node with the same base name be installed at the same time. See below for more information.

  5. Set Save To to the file path of the library file to save the asset definition into.

    You can expand the Save To group to show an interface that lets you choose the save directory and filename construction interactively, or collapse the group to only show a text box for the file path.

  6. Click Create.

    Houdini opens the new asset’s Type properties window so you can work on the asset’s metadata and parameter UI.

Create a new version of an existing asset

  1. Right click an instance of the asset and choose Digital Asset ▸ Increase Major Version or Increase Minor Version.

    Houdini opens a dialog that shows the new internal name for the new asset version.

  2. In the dialog, you can edit what library file to save the new asset into, if you want to.

  3. Click Create.

Set up the asset

After you create an asset, Houdini opens the Type properties window for the new node type to let you edit its options. (To open the type properties window again later, you can right click an instance of the asset and choose Type properties.)

You can use this window to set up the new node type’s parameter interface.

You can write documentation on the asset’s Help tab to explain its purpose and controls to users, using a Wiki markup language.

Start a new asset by duplicating an existing asset

  1. In the network editor, right-click an instance of the asset you want to copy, and choose Digital Assets ▸ Save As….

    Houdini opens the Create Asset dialog.

  2. Use the options in the dialog to set the new asset’s internal name, label, as well as the parent directory and file name of the library to save the new asset into.

Set the defaults for the Create Asset dialog

In the Create Asset dialog, set up the options how you want, then click Save Defaults in the bottom left corner of the dialog.

See also how to customize presets below.

Label

  • By default, editing the Label automatically changes the Internal Name to a similar string (converted to lower case and with illegal characters replaced by underscores). If you edit the Internal Name directly, it will disable the synchronization, so from then on you can edit the label and name independently.

    The Sync button next to the label indicates whether editing the label modifies the internal name. You can use it to turn synchronization on or off manually.

  • If you do edit the label and name independently, we strongly recommend you make sure an asset’s label and internal name are similar (for example,Three Light Rig and threelightrig), to avoid confusion.

Internal name

The internal name of the asset is how Houdini keeps track of it internally. You can’t have two assets with the same internal name in a Houdini session. If you try to save an asset to an asset library on disk (on embed it in a HIP file) and an asset with the same name already exists there, the new asset will overwrite the existing one.

You can edit the Internal name directly, or click the triangle to open the section and enable/edit the Author, Branch, Base Name, and Version parts individually.

Namespace / Author

Because internal names must be unique, and simple names might collide (with existing or future factory node names, or names of assets from other users or other studios), you can add a namespace and/or a version to the name. We recommend you add at least a namespace to the assets you create.

For more information, see namespaces.

In the Create Asset dialog, the main part of the namespace is labeled Author, because you should generally specify the creator of the asset (either your name or the name of your studio) to distinguish it from assets created by other people/studios.

If $HOUDINI_DEFAULT_ASSET_NAMESPACE is set, Houdini uses it as the initial default. It that is not set, it uses the value returned by hou.userName() (this is the user name portion of $HOUDINI_AUTHOR if it is set, otherwise the current user name). See asset creation environment variables below for more information.

The drop down list for the Author field includes:

  • The values of $HOUDINI_DEFAULT_ASSET_NAMESPACE (if set).

  • The value returned by hou.userName().

  • Any presets you've configured.

  • Any namespaces/authors found in the names of existing installed nodes.

Namespace branch

If you have assets in various phases of development being used by different people in a studio (for example, artists are using a “finished” asset but Technical Directors are beta-testing the next version of the asset), you can add an extra bit of structure to the namespace indicating which development “branch” the asset is in.

This lets you have different “branches” of an asset with the same Author and Version installed at the same time. For example, a “dev” branch (acme.dev::myasset::1.0) and a “test” branch (acme.test::myasset::1.0).

Note

The branch part is not added by default. You can turn it on by opening the Internal name section and turning on Add branch to namespace.

If you always want the branch to be added, turn it on and click Save Defaults to save the current options in the dialog as the defaults.

In the dialog, Houdini considers anything after the last delimiter in a namespace to be the “branch”, where a delimiter is one or more . (period) or : (colon) characters. So, for example, an asset with the namespace foo.bar.baz will be considered to have an Author of foo.bar and a Branch of baz. We recommend that you use the default . (period) as the delimiter to make it easier to tell the namespace part from the rest of the full name. However, studios may have legacy policies to use : or :: as the branch delimiter. You can change the delimiter by editing the full name in the Internal name field.

Houdini starts with a few preset branch names for you to use. You can add to, edit, or remove them (see configuring presets).

Branch name

Suggested meaning

dev

An “in-development” state, not ready to be used by other people.

beta

Ready to be tested, but likely to have bugs.

test

Ready for final testing.

main

For use in production.

The drop down list for the Branch field includes:

  • The current default branch.

  • The configured presets.

  • Any branches found in the names of existing installed nodes.

Tip

If you use branches, you can have multiple branches of the same base node installed at the same time. This can be confusing in the Tab menu if they all have the same label. When Add branch to namepsace is on, you can also turn on Add branch to label to automatically add the branch name to the node’s label when it’s created. For example: Pairwise Delete (dev). This will let you tell the different branches apart in the Tab menu.

Base name

The base name should describe what the node does. We recommend that the core name be at least similar to the label, so it’s easier to tell which node type corresponds to the label that users see.

Version

Adding a version to the asset name lets you have separate version of an asset with the same Author and Core Name. This lets create a new version with added functionality to an asset, a different parameter interface, and so on, without affecting existing instances that use the previous definition version.

When multiple versions of an asset are installed, by default the Tab menu will put down the latest (highest numbered) version. However, instances of previous versions can still exist in HIP files and will still work.

Tip

You can manually set any version of the asset as the “current” version for a session (in the Asset Manager dialog, right-click the older asset definition and choose Use This Definition).

You can also set a preference in Edit ▸ Preferences ▸ Shelves and Tab Menu to Show all nodes, not just the latest versions.

Even if you don’t add a version number to an asset when you create it, you can create a new version of the asset later by adding a version number to the name. For example, you can go from acme::myasset to acme::myasset::2.0.

For more information, see asset name version and systems for versioning assets.

Saving the asset to a library

The Save to section of the Create Asset dialog lets you specify the asset library file to save the new asset into.

Note

It is possible to save multiple assets into a single library file. This may be useful to distribute a bunch of assets together, or to speed up loading of assets on startup.

Otherwise, in general it’s a good idea to keep each asset in a separate file, so you can add and remove individual assets easily by moving the library files into/out of the Houdini Path.

You can edit the Save to location directly, or click the triangle open the section and edit the preset location and filename pattern Houdini uses to generate the save location.

Choosing a save location

The Location menu contains the following commonly used locations, plus any other hda or otls directories found on the Houdini Path, and any additional save location presets you've configured.

Label

Directory Path

Description

User Preferences

$HOUDINI_USER_PREF_DIR/otls

Your personal user preferences. Assets you save here will only be available to the current user. (For historical reasons Houdini defaults to saving to an otls directory in the user preferences instead of hda. Houdini scans both sub-directory names when it loads assets at startup.)

HIP File Directory

$HIP

The same directory as the current HIP file. Assets you save here will be available to the current HIP file.

Job Directory

$JOB/hda

You can set the $JOB environment variable, or use File ▸ Set Project, to point to a directory of shared files for the current project or shot. You can create a project directory with various sub-directories set up automatically using File ▸ New Project. See project management for more information.

Site Directory

$HSITE/hda

Studios may set the $HSITE environment variable to point to a repository of studio-wide shared files.

Embed in HIP File

Embedded

See embedding assets in the HIP file below.

Custom File Path

Custom

Saves to the library file specified by the Save to text box. You can edit the path or click the file chooser button to open a file chooser dialog.

If the Location is not Custom File Path, you can choose the naming scheme Houdini uses to generate the library filename to save the asset into. See file naming schemes below for more information.

You can also choose to prefix the file name with the network category type (for example, sop, lop, object). We recommend you do this to avoid collisions between assets in different categories with the same name.

Saving onto the Houdini Path

Houdini automatically finds assets at startup by looking in hda and otls sub-directories on the Houdini Path (see about the Houdini Path).

(For historical reasons, Houdini looks for assets in both HOUDINIPATH/hda and HOUDINIPATH/otls.)

When you save an asset, you usually want to save it into an hda sub-directory on the Houdini Path. This ensures Houdini will find and install the asset automatically when it starts up.

  • When you save the asset, Houdini will automatically re-scan for assets, so Houdini will automatically install the asset if you saved to an hda or otls sub-directory on the Houdini Path.

  • If the save location is not on the Houdini Path, Houdini will install the asset for use in this session. However, the next time you start Houdini, it will not find the asset on the path and to use it you will need to manually install it using Assets ▸ Install Asset Library.

Embedding an asset in a HIP file

If the save location is Embedded, Houdini will save the asset as part of the current HIP file, instead of in a separate file.

This can be useful sometimes:

  • If you are just experimenting with an asset and don’t want to commit it to disk yet.

  • If you want to share a working HIP file with someone else who might not have their own copy of the asset installed.

However, for general use embedding has drawbacks:

  • The asset is only available in that HIP file. It can’t be shared between projects or users.

  • Saving the asset as part of the HIP file bloats the size of the HIP file.

Unless you are embedding an asset for a specific reason, you should usually save it to a file

File naming schemes

If the Location is not Custom File Path, you can choose how Houdini constructs the library file name to save in the chosen directory using the File Naming Scheme menu. Houdini provides the following naming scheme choices:

Label

Form

Description

Standard

$NS--$TYPENAME-$VERSION

This is the recommended form for library files containing a single asset. It includes the namespace, base name, and version (for example, acme--explodo-1.0.hda). This avoids possible filename collisions.

Type Name

$TYPENAME

This only uses the base name (for example explodo.hda). This may be useful if you use some other convention to keep assets in other namespaces (or with multiple versions) apart. For example, saving them into different directories.

Node Name

$NODENAME

This uses the name of the node the asset was created from (for example, subnet.hda).

Custom

Custom

This lets you specify a custom filename pattern string. Houdini will fill any the variables in this pattern. For example, you could set the pattern to $NS @ $TYPENAME ($VERSION) to build a filename like acme @ explodo (1.0).hda.

You can use the following variables in the custom pattern, either in $NS or ${NS} form:

Variable

Content

$NS

The namespace (including the branch, if any).

$AUTHOR

The “author” part of the namespace (not including the branch).

$BRANCH

The branch part of the namespace, if any.

$CATEGORY

The node type category of the asset, such as Object or Sop.

$BASENAME

The base name part of the full asset name. For example, if the full name is acme::explodo::1.0, the $TYPENAME would be explodo.

$VERSION

The version part of the full asset name.

$NODENAME

The name of the node the asset was created from.

A studio can disable this option and enforce a standard filename pattern by setting the $HOUDINI_ASSET_FILENAME_PATTERN environment variable. See asset creation environment variables for more information.

Tip

You can also use environment variables in the pattern, for example $USER. This can be useful to include studio-specific information in the filename.

Customizing the Create Asset dialog

To...Do this

Customize the options the Create Asset dialog starts with in a new Houdini session

In the Create Asset dialog, set up the dialog options how you want, then click Save Defaults in the bottom left corner of the dialog.

Customize the drop-down menus of preset Authors, Branches, or Save Locations

  1. In the Create Asset dialog, click the Gear menu (in the top-right corner of the dialog) and choose Edit Author Presets, Edit Branch Presets, or Edit Save Directory Presets.

  2. Use the list editor dialog to add, edit, reorder, or delete presets.

    • To add a preset, click the Add button below the list.

    • To edit a preset, select the preset in the list, then click it again to make it editable.

      or

      select the preset and press Enter to start editing.

    • To change the order, drag and drop items within the list.

    • To delete a preset, select it in the list, then click the Remove button below the list.

  3. Click Accept in the list editor to save the new list.

    When you edit a preset list, the new list is saved to disk immediately (you don’t have to click Save Defaults to make the content changes permanent).

    However, editing the lists does not change the default values. To set the current Author, Branch, and Save Location as the new defaults, click Save Defaults.

Tip

Save Location presets can include environment variables. Houdini expands the string with hou.text.expandString to get a file path.

Asset creation environment variables

Note

These environment variables only affect the asset creation dialog window. A user can still override these settings through HOM scripting.

$HOUDINI_DEFAULT_ASSET_NAMESPACE

If this is set, it is used as the default namespace instead of the value returned by hou.userName().

$HOUDINI_AUTHOR

If this is set, the hou.userName() function uses it instead of the system user name. The asset creation dialog uses the value returned by hou.userName() as the default namespace if $HOUDINI_DEFAULT_ASSET_NAMESPACE is not set.

Note that if $HOUDINI_AUTHOR includes a machine name, for example padma@london, hou.userName() only returns the user name part (padma in this example).

$HOUDINI_ASSET_FILENAME_PATTERN

If this is set, the asset creation dialog uses this filename pattern for the asset library path, and hides the option to choose a different filename pattern. This may be useful for studios to enforce a studio-wide file naming convention.

If this variable is set, the dialog hides and disables the option to automatically add the node type category to the filename. You can use the $CATEGORY variable in the pattern to get the same effect.

Tip

Since the pattern variables look like shell variables (for example, $NODENAME), you need to be careful to escape them properly if you set this variable in a shell, so the shell doesn’t try to expand them.

Configuration files on HOUDINI_PATH

You can use configuration files to provide site-wide or studio-wide presets.

The Create Asset dialog stores its configuration in $HOUDINI_USER_PREF_DIR/vhda.config. This is a simple JSON file. When it loads the configuration at start-up, it looks for vhda.config files in each directory on the $HOUDINI_PATH and merges them.

Note that, in Houdini, earlier directories on the path override later directories. The user prefs dir is usually near or at the start of the path, but packages are earlier.

Since “earlier” values override “later” values in configuration files on the path, plain values (such as the default Author string) in the user prefs will usually override any site-wide values you have later in the path (unless you hack the user’s configuration file to not have a certain key and then prevent it from being overwritten).

However, for list values, the dialog merges together all the lists it finds in the configuration files on the path. This lets you specify site/studio-wide Author, Branch, and Save Location presets that will be added to any presets each user has in their own configuration.

For example, a studio might have Houdini set up so the directory /mnt/server/houdini/sitewide/ is in the Houdini path, and is used for site-wide configuration.

You could create the following JSON file at /mnt/server/houdini/sitewide/vhda.config:

{
    "users": ["acmeSF", "acmeNY"]
}

This will add acmeSF and acmeNY to the drop-down list of preset authors (for historical reasons, the config key for the Author field is called users).

Tip

Because the Create Asset dialog automatically adds any hda directories it finds on the Houdini path to the Save Locations, in this scenario /mnt/server/houdini/sitewide/hda would automatically show up as a possible save location.

Digital assets

Getting started

Creating assets

Next steps