Houdini 20.5 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/houdini‹major›.‹minor›/packages (for example, $HSITE/houdini18.0/packages)

    • $HOUDINI_PACKAGE_DIR

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

    • $HFS/packages

    Note

    $HSITE and $HOUDINI_PACKAGE_DIR must be set prior to start Houdini.

  • Houdini scans the package directories in the order specified above, it starts with $HOUDINI_USER_PREF_DIR/packages, then with $HSITE and so on. The package files are loaded alphabetically in the scope of a directory. The processing order can be changed with the process_order keyword.

  • You can have multiple package files in a packages directory.

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

hpath

Shortcut to set HOUDINI_PATH.

Note

path has been deprecated in favor of hpath.

recommends

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

requires

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

show

Set a package to be listed in the Package Browser window.

Manipulating the Houdini Path

To...Do this

Prepend a new directory to the Houdini Path

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

The hpath keyword 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

 
{
    "hpath" : [
        "/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:

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

To overwrite the previous Houdini Path with a new path:

{
    "hpath" : 
    [
        {        
            "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",
    "hpath" : "/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"],
    "hpath" : "/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.

{
    "hpath" : 
        [
            {"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,
    "hpath" : "/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 hpath 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, value and method:

{
    "requires" : ["package1","package2"],
    "env": [
        {
            "var": "BOB_TOOL",
            "value": "$HOME/bob_tool",
            "method": "append"
        },
        {
            "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"
                }
            ]
        },
        {
            "PATH" : {
                "value" : "$BOB/bin",
                "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

{
    "hpath" : [ "${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

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

$HOUDINI_USER_PREF_DIR/packages/package2.json

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

$HOUDINI_USER_PREF_DIR/packages/package3.json

{
    "hpath" : "$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

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

$HOUDINI_USER_PREF_DIR/packages/package2.json

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

$HOUDINI_USER_PREF_DIR/packages/package3.json

{
    "hpath" : "$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 

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

Add multiple paths 

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

With expression 

{
    "hpath": {"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 ('python3.7', 'python3.9')

    houdini_platform_build

    The houdini_platform_build keyword denotes the specific version of the compiler employed in compiling different Houdini builds. The format of this keyword follows the structure compiler.major.minor.

    The table below lists the compilers used on each platform supported by Houdini. For more information about the Houdini variant builds see the Houdini third-party libraries page.

    Platform

    Compiler

    Linux

    gcc

    Use gcc -v to find the compiler major and minor version numbers.

    Mac

    clang

    Use clang -v to find the major and minor version numbers.

    Windows

    cl

    Use cl.exe to find the compiler major and minor version numbers. The cl version number is different than the MSVC version or the Visual Studio version or the Toolset version, please refer to the Microsoft documentation for more details.

    Note

    The compiler version used for compiling Houdini can be found in the About Houdini dialog under Platform Build.

  • 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.9'"

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

"houdini_platform_build == 'gcc.11.2'"

"houdini_platform_build == 'clang.14.0'"

"houdini_platform_build >= 'cl.19.22'"

Package Browser

Houdini lets you manage packages with the Package Browser window.

Package Debugging

In order to debug packages or for just listing package information, set the HOUDINI_PACKAGE_VERBOSE environment variable before launching Houdini. When HOUDINI_PACKAGE_VERBOSE is enabled, Houdini writes package information to the standard output device once all packages have been loaded.

Note

HOUDINI_PACKAGE_VERBOSE must be set in your terminal or in a script used for launching Houdini, do not set it in your package file directly.

. export HOUDINI_PACKAGE_VERBOSE=1
. hconfig -xa

= = = Houdini Package log = = =
Loading: C:/Users/bob/houdini19.5/packages/mypackage.json
WARNING: Undefined variable $USE_PACKAGE used in expression houdini_version > '19.0.589' and $USE_PACKAGE == 'TRUE'
WARNING: mypackage is marked as disabled.

Loading: C:/Users/bob/houdini19.5/packages/opencolorio.json

Loading: C:/Users/bob/HOUDIN~3/HOUDIN~1.39/packages/apex.json

Loading: C:/Users/bob/HOUDIN~3/HOUDIN~1.39/packages/kinefx.json

Loading: C:/Users/bob/HOUDIN~3/HOUDIN~1.39/packages/package_dirs.json

Processing load once: C:/Users/bob/houdini19.5/packages/opencolorio.json

Processing: C:/Users/bob/houdini19.5/packages/opencolorio.json

Processing: C:/Users/bob/HOUDIN~3/HOUDIN~1.39/packages/apex.json

Processing: C:/Users/bob/HOUDIN~3/HOUDIN~1.39/packages/kinefx.json

Processing: C:/Users/bob/HOUDIN~3/HOUDIN~1.39/packages/package_dirs.json

Loading: C:/Program Files/Side Effects Software/sidefx_packages/SideFXLabs19.0.json
WARNING: SideFXLabs19.0 is marked as disabled.

Loading: C:/Program Files/Side Effects Software/sidefx_packages/SideFXLabs19.5.json

Processing load once: C:/Program Files/Side Effects Software/sidefx_packages/SideFXLabs19.5.json

Processing: C:/Program Files/Side Effects Software/sidefx_packages/SideFXLabs19.5.json

Resolved variables:
    OCIO : C:/Program Files/Side Effects Software/sidefx_packages/SideFXLabs19.5/misc/labs_ocio/aces_config.ocio
    HOUDINI_PATH :
        C:/Program Files/Side Effects Software/sidefx_packages/SideFXLabs19.5
        C:/Users/bob/HOUDIN~3/HOUDIN~1.39/packages/kinefx
        C:/Program Files/Side Effects Software/sidefx_packages/SideFXLabs19.5/misc/labs_ocio/aces_config.ocio
        &
    SIDEFXLABS : C:/Program Files/Side Effects Software/sidefx_packages/SideFXLabs19.5

Loading Info:
    Loaded Packages (5):
        C:/Program Files/Side Effects Software/sidefx_packages/SideFXLabs19.5.json
        C:/Users/bob/HOUDIN~3/HOUDIN~1.39/packages/apex.json
        C:/Users/bob/HOUDIN~3/HOUDIN~1.39/packages/kinefx.json
        C:/Users/bob/houdini19.5/packages/opencolorio.json
        C:/Users/bob/HOUDIN~3/HOUDIN~1.39/packages/package_dirs.json

    Disabled Packages (2):
        C:/Users/bob/houdini19.5/packages/mypackage.json
        C:/Program Files/Side Effects Software/sidefx_packages/SideFXLabs19.0.json

= = = = = = = = = = = = = = = =
HFS := 'C:/Users/bob/HOUDIN~3/HOUDIN~1.39/'
HOME := 'C:/Users/bob'
HOUDINI_DESKTOP_DIR := 'C:/Users/bob/Desktop'
HOUDINI_OS := 'Windows'
HOUDINI_PACKAGE_VERBOSE := 1
HOUDINI_PATH := 'C:/Program Files/Side Effects Software/sidefx_packages/SideFXLabs19.5;C:/Users/bob/HOUDIN~3/HOUDIN~1.39/packages/kinefx;
    C:/Program Files/Side Effects Software/sidefx_packages/SideFXLabs19.5/misc/labs_ocio/aces_config.ocio;&'
HOUDINI_TEMP_DIR := 'C:/Users/bob/AppData/Local/Temp/houdini_temp'
HOUDINI_USER_PREF_DIR := 'C:/Users/bob/houdini19.5'
SHELL := 'C:/PROGRA~1/Git/usr/bin/bash.exe'
USER := 'bob'

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 otls, python panels, viewer states or dso files, etc.

Your plugin folder should contain the standard Houdini folders like so:

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

set HOUDINI_PATH with a reference to your plugin folder in your package file: 

$HOUDINI_USER_PREF_DIR/packages/xyzplugin.json

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

Note

  • Unlike PATH on Windows, setting LD_LIBRARY_PATH on linux (same for DYLD_LIBRARY_PATH on Mac) in the package file wouldn’t do anything since packages are processed well after Houdini has started. LD_LIBRARY_PATH only takes effect if it is set prior to launching Houdini. dlopen() won’t respect changes to LD_LIBRARY_PATH that are made after Houdini has been launched. Using the above approach would solve this problem.

  • Integrating plugins like the above can be automated with a package archive.

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"
            }
        ]          
      }
    ],
    "hpath": "$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"
            }
        ]          
      }
    ],
    "hpath": "${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"
      }
    ],
    "hpath": "$XYZ",
    "enable": "houdini_version == '18.5'"
}
$HOUDINI_USER_PREF_DIR/packages/xyzplugin18.0.json

{
    "env": [
      {
        "XYZ": "$HOUDINI_USER_PREF_DIR/xyzplugin18.0"
      }
    ],
    "hpath": "$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).

  • Launching Houdini from a sub-process will copy the environment variables of the Houdini parent process into the sub-process environment. Set HOUDINI_PACKAGE_SKIP=1 before launching the subprocess to prevent the duplication of the package environment variables of the Houdini parent process.

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