Houdini 19.0 Reference

Houdini packages

How to write and combine multiple environment variable definition files for different plug-ins, tools, and add-ons.

On this page

Plugin installation

Overview

Traditionally, the way to set the values of environment variables in Houdini was to edit the houdini.env file. The most important variable to set up is the $HOUDINI_PATH, which tells Houdini where to look for files such as assets. You can also create convenience variables (for example $TEXTURE_DIR) and edit system variables (such as the binary search path $PATH).

The problem is that not only the user wants to set environment variables, but also studios, plug-in authors, and so on. Multiple parties would end up rewriting or appending to the houdini.env file, sometimes causing errors or redundancy.

Also, you might want variables defined some times and not others (for example, switching between project-specific paths, or turning “experimental” assets on and off).

The new solution for this kind of set-up is packages. Packages are .json files in HOUDINI_PATH/packages. Each package file contains a specification for how to modify the environment (including the Houdini Path and other variables).

You can then have separate packages for:

  • Studio variables.

  • Project variables.

  • User variables.

  • Variables for each separate plug-in, tool, or add-on.

The file format supports a small expression language to allow some automation. With expressions you can, for example:

  • Enable/disable a tool installation or specify what package(s) are required by a tool.

  • Write generic package files.

  • Write a single package to manage a multi-platform setup.

  • Set variables conditionally with simple operators, Houdini keywords and environment variables.

This removes the need to edit houdini.env.

See also hou.ui.loadPackage()

Using package files

  • Package files must be valid JSON and must have the .json extension.

  • Houdini will scan the following directories on startup (if they exist) for package files:

    • $HOUDINI_USER_PREF_DIR/packages

    • $HSITE/houdinimajor.minor/packages (for example, $HSITE/houdini18.0/packages)

    • $HOUDINI_PACKAGE_DIR

      Houdini will process the package files directly in the folders specified in HOUDINI_PACKAGE_DIR, do not add a packages directory under these folders.

      $HSITE must be set to an existing directory before starting Houdini.

    • $HFS/packages

  • Houdini process files it finds first in the directory order above, then within each directory alphabetically by file name. The processing order can be changed with the process_order keyword.

  • You can have multiple package files in each packages directory on the above path.

  • Houdini does not scan subdirectories inside packages.

  • Extra package folders can be specified dynamically from a package file.

Writing the package file

The following keywords are used for writing a package:

env

Sets or modifies environment variables.

enable

Enables or disables a package.

load_package_once

Prevents a package from being loaded multiple times. Houdini will load the first package in the search path with "load_package_once": true, and ignore any other packages with the same file name in the search path. This keyword defaults to false.

process_order

Specifies an integer value that Houdini can use for arranging the order of the packages to process in a package directory.

package_path

Scans package paths dynamically.

path

Shortcut to set HOUDINI_PATH.

recommends

Checks specific package(s) availability without enforcing a dependency.

requires

Checks specific package(s) availability and enforces a dependency.

Manipulating the Houdini Path

To...Do this

Prepend a new directory to the Houdini Path

 
{
    "path" : "/user/bob/libs"
}

The path top-level key is a convenience for manipulating the $HOUDINI_PATH variable. See also how to set arbitrary environment variables below.

Prepend multiple directories to the Houdini Path

 
{
    "path" : [
        "/user/bob/libs",
        "/user/tom/libs",
        "/user/sam/libs"
    ]
}

Edit the value of a variable using the method and value keys

New path elements are prepended by default.

In places where you would use a string value to prepend to the path, you can replace it with a JSON object containing a value key with the value of the new path element, and a method key specifying how to modify the variable’s current value.

The value for method can be prepend (the default, add new element(s) at the start of the existing path), append (add new element(s) at the end of the existing path), or replace (clear the previous value and set the variable to the new value).

To append one element and prepend two others to the Houdini Path:

{
    "path" : 
    [
        {
            "value" : "/user/bob/libs",
            "method" : "append"
        },
        "/user/tom/libs",
        "/user/sam/libs"
    ]
}

To overwrite the previous Houdini Path with a new path:

{
    "path" : 
    [
        {        
            "value" : 
                [
                    "/user/bob/libs",
                    "/user/tom/libs",
                    "/user/sam/libs"
                ],
            "method" : "replace"
        }
    ]
}

Specify that the package file depends on another package file.

If you use a recommends key and the other package file is not found, Houdini displays a warning but still processes this package file.

{
    "recommends" : "package_name",
    "path" : "/user/bob/libs"
}

If you use requires and the other package file is not found, Houdini displays an error and does not process this package file.

{
    "requires" : ["package1","package2"],
    "path" : "/user/bob/libs"
}

The value of either key can be a package name string or an array of package name strings.

Add or don’t add a path element based on an expression

In places where you would use a string value, you can replace it with a JSON object where instead of value, the key is a simple expression, and the value is the path element value to use if the expression evaluates to true.

{
    "path" : 
        [
            {"houdini_os != 'windows'" : "/user/bob/libs"},
            {"houdini_os == 'windows'" : "$HOME/bob_win_libs"},
            {"$use_tom_libs == '1'" : "$HOME/tom_libs"}
        ]
}

See package expressions below.

Mark a package as “not enabled” so Houdini ignores it

The enable top-level key:

{
    "enable" : false,
    "path" : "/user/bob/libs"
}

Instead of a boolean, the value of the enable key can be a string containing an expression:

{
    "enable": "houdini_os == 'linux'"
}

If you want to reverse the meaning of the expression, you can make it generate the value false instead of the default true:

{
    "enable": { "houdini_os == 'linux'": false }
}

Prevent Houdini from loading the other packages with the same package file name found later in the search path

Use the load_package_once key with boolean value:

{
    "load_package_once" : false
}

Or the value of load_package_once key can be a string containing an expression:

{
    "load_package_once": "houdini_os == 'linux'"
}

Or JSON Map:

{
    "load_package_once": { "houdini_os == 'linux'": false }
}

Set arbitrary environment variables

To...Do this

Set/modify an environment variable

The top-level keyword env lets you set environment variable values. You can create custom variables, and set the system PATH and the Houdini path variables as well.

  • The value of the env key is a JSON array.

  • The JSON array can contain string literals or JSON objects where the keys are environment variable names (without the $ prefix), and the values are strings.

  • Where you would use a string value, you can replace it with a JSON object specifying a method, and a value or expression. See package expressions below for more information.

  • Values added to path variables (e.g. HOUDINI_PATH) with JSON objects (e.g. { “houdini_os == 'linux'”: “/bob/tool” }) are prepended by default. Use the method keyword to change the default behavior.

Note

The env keyword is not meant for setting the package keywords.

The following set $BOB with $HOME/bob_tool and $HOUDINI_PATH directly instead of using the path keyword.

{
    "requires" : ["package1","package2"],
    "env": [
        {
            "BOB": "$HOME/bob_tool"
        },
        {
            "HOUDINI_PATH" :
            [
                "$BOB/libs",
                {
                    "houdini_version>'17.5' and houdini_version<'17.5.250'": "$BOB/test",
                    "method": "append"
                }
            ]
        }
    ]
}

You can also use an alternate syntax for defining environment variables using the reserved keys var and value:

{
    "requires" : ["package1","package2"],
    "env": [
        {
            "var": "BOB",
            "value": "$HOME/bob_tool"
        },
        {
            "var": "HOUDINI_PATH",
            "value": [
                "$BOB/libs",
                {
                    "houdini_version>'17.5' and houdini_version<'17.5.250'": "$BOB/test2",
                    "method": "append"
                }
            ]
        }
    ]
}

You can define custom path variables.

{
    "env": [
        {
            "MYPATH": ["$HOME/bob_tool", "$HOME/bob/test"]
        }
    ]
}

Use curly braces ({}) to concatenate a variable value and a value literal. The curly brace syntax is the same as the HSCRIPT variables syntax.

{
    "env": [
        {"BOB": "/home/bob/bob_tool"},
        {"BOB1": "${BOB}1"},
        {"BOB2": "${BOB}2"}
    ]
}

From Hscript Textport:

/ -> echo $BOB
/home/bob/bob_tool
/ -> echo $BOB1
/home/bob/bob_tool1
/ -> echo $BOB2
/home/bob/bob_tool2

Default variable syntax

The default variable syntax ${VAR-DEFAULT} can be used for defining a variable with a default value. The default value can be a value literal, a variable or an expression. VAR will expand as expected if already set, otherwise it will expand to DEFAULT if unset.

Some examples defined in /home/bob/packages/package1.json

{
    "path" : [ "${EMPTY_VAR-/var/tmp}", "${BOB_TOOL-${HOUDINI_PACKAGE_PATH}/../BOB_TOOL}" ],
    "env": [
        {"BOB": "${BOB_TOOL-/home/bob/bob_tool}"},
        {"BOB1": "${BOB_TOOL_V1-${BOB}}"}
    ]
}

With HOUDINI_PACKAGE_PATH set to /home/bob/packages, the variables set in package1.json will expand to the following:

. echo $HOUDINI_PATH
/var/tmp:/home/bob/BOB_TOOL
. echo $BOB
/home/bob/bob_tool
. echo $BOB1
/home/bob/bob_tool

Relative path variables

To...Do this

Set environment variable relative to the package

The $HOUDINI_PACKAGE_PATH variable let you identify the current package path in your variable value.

For instance, given this package file /home/user/bob/packages/bob.json

{
    "env": [
        {
            "HOUDINI_PATH": "$HOUDINI_PACKAGE_PATH/../tools"
        }
    ]
}

Houdini will resolve HOUDINI_PATH as

HOUDINI_PATH := '/home/user/bob/tools;&'

Set package folders dynamically

In addition to the startup folders that you specify upfront for loading package files, Houdini lets you set extra package folders from a package file:

  • Use the package_path keyword for setting either a single folder or an array of folders.

  • Houdini will process the package files located directly in the specified folders, do not add a packages directory under these folders.

  • Houdini will queue the extra package folders and will process them recursively. The queue is processed when the current package folders have been processed. The loop ends until there are no more folders added to the queue.

Note

Environment variables set with the env keyword cannot be used for setting package_path. You can only use variables from the environment where Houdini was launched.

To...Do this

Set a single folder to scan

 
{
    "package_path" : "$HOME/bob_tool"
}

Conditionally specify a folder

 
{
    "package_path" : { "houdini_version == '18.0.302'": "/opt/bob/packages" }
}

Set an array of folders to scan

 
{
    "package_path" : [
        "$HOME/bob_tool",
        "/opt/tom_tool"
    ]
}

Set an array of folders

 
{
    "package_path": [ 
        "$HOME/bob_tool1", 
        "$HOUDINI_PACKAGE_PATH/../bob_tool2",
        {"houdini_version > '17'" : "$HOME/bob_tool3" } 
    ]
}

Changing the package processing order

At startup Houdini scans specific package directories and then loads the packages it finds in each directory alphabetically by filename. The ordering for processing the packages is the same. You can change the processing order within a package directory with the process_order keyword. Houdini uses this keyword for sorting the packages in an ascending order before processing them. The package with the lowest process_order will be processed first while the package with the highest process_order will be processed last.

Note

Changing the processing order is relative to a package directory, the process_order of a package is significant only within its directory.

To...Do this

Prepend paths to HOUDINI_PATH with the default processing order

$HOUDINI_USER_PREF_DIR/packages/package1.json

{
    "path" : "$HOME/bob1"
}

$HOUDINI_USER_PREF_DIR/packages/package2.json

{
    "path" : "$HOME/bob2"
}

$HOUDINI_USER_PREF_DIR/packages/package3.json

{
    "path" : "$HOME/bob3"
}

Result:

. hconfig -xa
. HOUDINI_PATH := '$HOME/bob3;$HOME/bob2;$HOME/bob1;&'

Prepend paths to HOUDINI_PATH with a custom processing order

$HOUDINI_USER_PREF_DIR/packages/package1.json

{
    "path" : "$HOME/bob1",
    "process_order" : 3
}

$HOUDINI_USER_PREF_DIR/packages/package2.json

{
    "path" : "$HOME/bob2",
    "process_order" : 2
}

$HOUDINI_USER_PREF_DIR/packages/package3.json

{
    "path" : "$HOME/bob3",
    "process_order" : 1
}

Result:

. hconfig -xa
. HOUDINI_PATH := '$HOME/bob1;$HOME/bob2;$HOME/bob3;&'

Append paths to HOUDINI_PATH with a custom processing order

$HOUDINI_USER_PREF_DIR/packages/package1.json

{
    "env": [
        {
            "HOUDINI_PATH": {
                "value": "$HOME/bob1",
                "method": "append"
            }
        }
    ],
    "process_order" : 3
}

$HOUDINI_USER_PREF_DIR/packages/package2.json

{
    "env": [
        {
            "HOUDINI_PATH": {
                "value": "$HOME/bob2",
                "method": "append"
            }
        }
    ],
    "process_order" : 2
}

$HOUDINI_USER_PREF_DIR/packages/package3.json

{
    "env": [
        {
            "HOUDINI_PATH": {
                "value": "$HOME/bob3",
                "method": "append"
            }
        }
    ],
    "process_order" : 1
}

Result:

. hconfig -xa
. HOUDINI_PATH := '$HOME/bob3;$HOME/bob2;$HOME/bob1;&'

Examples

Path

Prepend a path to HOUDINI_PATH 

{
    "path": "$HOME/bob_tool/libs"
}

Add multiple paths 

{
    "path": ["$HOME/bob_tool/libs", "$HOME/bob_tool/test"]
}

With expression 

{
    "path": {"houdini_os == 'windows'": "$HOME/bob_tool/libs"}
}

Env

Define multiple environment variables 

{
    "env" : 
    [
        {
            "BOB" : "$HOME/bob_tool"
        },
        {
            "TOM" : "$HOME/tom_tool"
        }
    ]
}

Use expressions 

{
    "env": [
        {
            "QUAD_LIBS": 
            { 
                "houdini_version > '17.0' and houdini_version < '17.5'" : "$HOME/quad_libs"
            }
        }
    ]
}

Use expressions with environment variables 

{
    "env": [
        { "SERVER1": { " $MY_SERVER_SETUP == 'ICARUS' ": "/servers/icarus" } },
        { "SERVER2": { " $MY_SERVER_SETUP == 'MERCURY' ": "/servers/mercury" } }
    ]
}

Create and reuse variables 

{
    "env" : 
    [
        {
            "BOB" : "$HOME/bob_tool"
        },
        {
            "BOB_TEST" : "$BOB/test"
        }
    ]
}

Prepend path to HOUDINI_PATH 

{
    "env" : 
    [
        {
            "HOUDINI_PATH" : "$HOME/bob_tool"
        }
    ]
}

Append path to HOUDINI_PATH 

{
    "env" : 
    [
        {
            "HOUDINI_PATH" : 
            {
                "value": "$HOME/bob_tool",
                "method": "append"
            }
        }
    ]
}

Replace HOUDINI_PATH 

{
    "env" : 
    [
        {
            "HOUDINI_PATH" :
            {
                "value": 
                [
                    "$HOME/bob_tool",
                    "$HOME/tom_tool"
                ],
                "method": "replace"
            }
        }
    ]
}

Multiple variables 

{
    "env": 
    [
        {
            "BOB" : "$HOME/bob_tool"
        },
        {
            "HOUDINI_PATH" :
            {
                "value": 
                [
                    "$BOB/libs",
                    {
                        "houdini_version>'17.5' and houdini_version<'17.5.250'": "$BOB/test",
                        "method": "append"
                    }
                ]
            }
        }
    ]
}

Modify system PATH 

{
    "env" : 
    [
        {
            "PATH" :
            { 
                "value": 
                [
                    "$HOME/bob_tool",
                    {
                        "value": "$HOME/tom_tool",
                        "method": "append"
                    }
                ]
            }
        }
    ]
}

Recommends/requires

Display warning if bob_tool package is missing 

{
    "recommends": "bob_tool"
}

Multiple dependencies 

{
    "recommends": [ "bob_tool", "tom_tool" ]
}

Conditional dependency 

{
    "recommends": { "houdini_version > '17.0'": "sam_tool" }
}

Display error if bob_tool package is missing 

{
    "requires": "bob_tool"
}

Multiple requirements 

{
    "requires": [ "bob_tool", "tom_tool" ]
}

Conditional requirement 

{
    "requires": { "houdini_version > '17.0'": "sam_tool" }
}

Package Expressions

Expressions can be used for setting package variables conditionally. The grammar supports boolean expressions defined with the following set of comparison and logical operators.

  • The expression can use the following operators: (, ), ==, !=, <, >, <=, >=, and, or.

  • You can establish precedence using brackets (). Otherwise and and or have higher precedence, and the comparison operators all have the same lower precedence.

  • You can compare with a literal string by enclosing the string in single quotes.

    'This is a valid string'

  • You can use environment variables in a comparison by prefixing the variable name with $.

    $MY_VAR == '/var/tmp'
$HOME == '/user/bob'

  • You can use the following “keywords” as part of a comparison:

    houdini_version

    The current Houdini version (full version path).

    houdini_os

    The OS platform ('windows', 'linux', 'macos')

    houdini_python

    The Houdini python version ('python2', 'python3')

  • The expression language supports string values only. Other types may be supported in the future for new identifiers.

Examples 

"houdini_version == '16.5'"

"houdini_python == 'python3'"

"houdini_version == '16.5' and houdini_os=='linux'"

"houdini_version => '16.5' and houdini_version < '17.5'"

"houdini_os != 'windows' or houdini_version == '17.5' or houdini_version == '17.5.56'"

"(houdini_os != 'macos') or (houdini_version >= '17.4' and houdini_version <= '17.5')"

"houdini_os == 'windows' and houdini_version >= '17.5' and $USE_XYZ == 'TRUE'"

Packaging techniques

Here are a few common techiques for packaging plugins in Houdini.

Easy way to integrate plugin files

Create a package file to set the $HOUDINI_PATH with the plugin folder to tell Houdini where to look for the plugin HDA, python panel and viewer state files.

Plugin folder:

$HOUDINI_USER_PREF_DIR/xyzplugin18.5/
    otls/
    python_panels/
    viewer_states/

Package file: 

$HOUDINI_USER_PREF_DIR/packages/xyzplugin.json

{
    "path": "$HOUDINI_USER_PREF_DIR/xyzplugin18.5"
}

Plugin versioning

You can write a package to set $HOUDINI_PATH with a plugin folder for a given Houdini version. This can be done with an array variable where each entry uses an expression to match a plugin folder with a specific Houdini version.

$HOUDINI_USER_PREF_DIR/packages/xyzplugin.json

{
    "env": [
      {
        "XYZ":
        [
            {
                "houdini_version == '18.0'": "$HOUDINI_USER_PREF_DIR/xyzplugin18.0"
            },

            {
                "houdini_version == '18.5'": "$HOUDINI_USER_PREF_DIR/xyzplugin18.5"
            }
        ]          
      }
    ],
    "path": "$XYZ"
}

The above example will set $HOUDINI_PATH with $HOUDINI_USER_PREF_DIR/xyzplugin18.0 if Houdini 18.0 is running or with $HOUDINI_USER_PREF_DIR/xyzplugin18.5 for Houdini 18.5. If no match is found, $HOUDINI_PATH will not be set. You could however use a default variable to set $HOUDINI_PATH with a plugin folder if any of these Houdini versions match. The example below will set $HOUDINI_PATH to $HOUDINI_USER_PREF_DIR/xyzplugin for any Houdini versions other than 18.0 and 18.5.

$HOUDINI_USER_PREF_DIR/packages/xyzplugin.json

{
    "env": [
      {
        "XYZ":
        [                
            {
                "houdini_version == '18.0'": "$HOUDINI_USER_PREF_DIR/xyzplugin18.0"
            },

            {
                "houdini_version == '18.5'": "$HOUDINI_USER_PREF_DIR/xyzplugin18.5"
            }
        ]          
      }
    ],
    "path": "${XYZ-$HOUDINI_USER_PREF_DIR/xyzplugin}"
}

Plugin versioning method 2

Another approach for plugin versioning is to use multiple package files. The package matching the current version of Houdini will be marked as enabled and processed:

$HOUDINI_USER_PREF_DIR/packages/xyzplugin18.5.json

{
    "env": [
      {
        "XYZ": "$HOUDINI_USER_PREF_DIR/xyzplugin18.5"
      }
    ],
    "path": "$XYZ",
    "enable": "houdini_version == '18.5'"
}
$HOUDINI_USER_PREF_DIR/packages/xyzplugin18.0.json

{
    "env": [
      {
        "XYZ": "$HOUDINI_USER_PREF_DIR/xyzplugin18.0"
      }
    ],
    "path": "$XYZ",
    "enable": "houdini_version == '18.0'"
}

Loading HDAs with OPlibraries

By default Houdini scans the folders in HOUDINI_OTLSCAN_PATH to load HDA files. This is done if the Operator Type Manager dialog is configured not to use OPlibraries files to find HDA files. However, plugins must use a OPlibraries file to ensure their HDA files are loaded if the user choose to set the OPlibraries option.

1) Put an OPlibraries file in the package folder. The file must list all HDA files to load with a path relative to the plugin folder. 

$HOUDINI_USER_PREF_DIR/xyzplugin18.5/OPlibraries

otls/OPlibXYZ.hda

2) Tell Houdini where to find the OPlibraries file. This is normally achieved by setting $HOUDINI_PATH or HOUDINI_OPLIBRARIES_PATH with the plugin folder.

Tips

  • You can quickly display the contents and order of the Houdini Path in Houdini’s Python shell by calling hou.houdiniPath().

  • You can define an environment variable earlier in the env array and then use that variable in a value later in the array. Make sure the variables are defined before they are used.

  • Environment variables set in one package can be referenced by other packages as well.

  • Environment variables set in packages only affect the Houdini process (for example, they do not affect the shell if you launch Houdini from a command line).

Plugin installation

Reference

User interface

  • Menus

    Explains each of the items in the main menus.

  • Viewers

    Viewer pane types.

  • Panes

    Documents the options in various panes.

  • Windows

    Documents the options in various user interface windows.

Programming

  • Expression functions

    Expression functions let you compute the value of parameters.

  • Expression cookbook

    Tips and tricks for writing expressions to accomplish various effects.

  • Python scripting

    How to script Houdini using Python and the Houdini Object Model.

  • VEX

    VEX is a high-performance expression language used in many places in Houdini, such as writing shaders.

  • HScript commands

    HScript is Houdini’s legacy scripting language.

  • hwebserver

    Functions and classes for running a web server inside a graphical or non-graphical Houdini session.

Command line

Guru level

Plugin installation

  • Houdini packages

    How to write and combine multiple environment variable definition files for different plug-ins, tools, and add-ons.

Houdini Engine