An import block is a type of folder that displays its contents “inline” (that is, the enclosing “folder” is not visible).

When you are developing a set of complex assets, with high-level assets that build on low-level assets, you sometimes want to promote an entire block of parameters from a lower-level asset onto the higher-level asset you're authoring. However, you want to be able to continue to edit the lower-level parameters and not have to re-promote them every time.

Import blocks let you promote a block of parameters and have them remember where they were promoted from so you can automatically update them with changes to the originals.

“Tags” let you attach arbitrary key/value data to the parameter template. You can access this data using hou.ParmTemplate.tags. Some tags are recognized and used by different parameter types. You can also use them to store your own per-parameter hidden data.

Tags are used by the 3D viewer to signal when a parameter should be treated as an OpenGL value. For example, attaching the “OpenGL → Diffuse” tag to a parameter on a material node makes the 3D viewer treat that parameter’s value as the diffuse color when displaying the surface.

• The tags are listed in a table in the “Parameter description” sub-pane on the right, when you select a parameter from “Existing Parameters” list in the middle.

• Click Built in tags below the tag table to choose from a tree of different tags recognized by Houdini, including the OpenGL tags.

• Some parameters may have internal tags attached to them which store options for the parameter’s look and behavior. These internal tags are not editable in the tag list.

• Tag names must be unique within each parameter.

• You can use the Key-Value Dictionary parameter type to add a tag-like editing interface to your own digital assets.

The “Collapsible” folder type (shown as a collapsing header in the parameter editor) has several options the lat you design a more compact and clear parameter interface.

This sub-tab shows the animatable channels associated with this parameter.

By default, Houdini creates an animated channel for each component of the parameter value (so for example, a Translate vector parameter would get three channels, one for each component of the vector). However, you can have the parameter generate more (computed) channels or fewer channels.

• You can turn on the Auto-add icon for a channel to make it key-able and automatically added to the channel list when the node containing this parameter is selected.

  You should turn this on for all commonly animated values.

• If this parameter is promoted, the “Linked Channels” column shows which channels this parameter was promoted from on the contained node. When the Link button in the middle is on, the channel gets its value from the linked channel.

The controls on this tab let you set up a menu of values the user can choose from for this parameter. You can also use the Callback script (on the Parameter sub-tab) to script actions based on the user’s menu choices.

Each menu item has a token and a label. The label is the human-readable label corresponding to the value that appears in the pop-up menu in the parameter editor.

• In a String parameter, when the user selects an item, the parameter is set to the corresponding string token.

• In an Integer parameter, by default when the user chooses an item, the parameter is set to the index of the item (for example, 0 for the first item, 1 for the second item, and so on). If you turn on Use Token as Value, the parameter will be set to the corresponding integer token instead.

• Any menu item with the token _separator_ will be replaced with a menu separator.

If you know the items you want to appear in the menu ahead of time, you can define them using the Menu items table. If you want to dynamically compute the menu contents using a script, click Menu script instead.

Houdini stores information here about where a parameter was promoted from, for use when updating import blocks. You should not edit this information unless you know what you're doing.

Some parameters can have a small button appear to the right of the field in the parameter editor that runs an arbitrary script.

Unlike other parts of Houdini, this is no checkbox to control whether the action button appears. Instead, if the script editor on this tab is empty, the parameter has no action button, and if the script editor has any content, the action button appears.

If the script is one line, it is treated as a Python expression and evaluated. If it has more than one line, it is treated as if it was the body of a function.

The script runs in an environment with a global kwargs dictionary variable containing the following keys:

The following action button script for a node path parameter opens a chooser, waits for the user to pick an Object node, and then fills in the parameter with the path to that node. If the user shift-clicks the button, the chooser is limited to selecting cameras, and if they ctrl-click the button, it’s limited to selecting lights.

# Get the reference to the current parameter
parm = kwargs["parmtuple"]

# Get the current value of the parameter, to use as the default in the chooser.
# Note that the method returns a tuple, so we grab the first (and only) item in
# the tuple.
path = parm.evalAsStrings()[0]
node = hou.node(path)

# Check the modifier keys to set the filter
if kwargs["shift"]:
    nodetype = hou.nodeTypeFilter.ObjCamera
elif kwargs["ctrl"]:
    nodetype = hou.nodeTypeFilter.ObjLight
else:
    nodetype = hou.nodeTypeFilter.Obj

# Ask the user to choose a node
newpath = hou.ui.selectNode(initial_node=node, node_type_filter=nodetype)

# Set the parameter value (again, it's a ParmTuple, so we need to set it as
# as tuple with a single item)
parm.set( (newpath, ) )

Often you want to dynamically show or enable parameters based on the values of other parameters. For example, you might have a checkbox that enables some feature, and only want to enable editing parameters related to that feature when the checkbox is on.

The Disable when and Hide when settings of a parameter let you set up when the parameter should be disabled or hidden. The value is a code using the syntax shown below to calculate whether to disable/hide based on other parameter values.

The general syntax is:

{ parm_name [operator] value ...} ...

• One or more comparisons inside curly braces.

• Inside the curly braces are one or more comparisons with a parameter name, a comparison operator, and a value.

• The following comparison operators are available: ==, !=, <, >, >=, <=, =~ (matches pattern), !~ (doesn’t match pattern).

  { type == 1 count > 10 } { tolerance < 0.1 }
  

  Note

  You must put spaces around the comparison operator, otherwise Houdini will not accept the rule.

• You can omit the comparison operator, in which case it will be assumed to be ==. For readability however we recommend you always explicitly type an operator.

  { geotype 1 } { geotype 2 }
  

• If there are multiple comparisons inside a set of curly braces, all the comparisons must be true for that condition to be true.

  For example, with the condition below, if the enablefeature checkbox parameter is on and the count parameter is more than 10, this parameter would be disabled/hidden:

  { enablefeature == 1 count > 10 }
  

• If there are multiple conditions (sets of curly braces), any of the conditions may be true to activate disabling/hiding.

  For example, with the condition below, if the enablefeature checkbox parameter is on or the count parameter is more than 10, this parameter would be disabled/hidden:

  { type == 1 } { count > 10 }
  

• You can’t use expression functions in the rule string. However, a workaround is to create an invisible parameter containing an expression that calculates what you need, and then reference it in a comparison.

• There are a few special functions you can use in place of the parameter name on the left side of a comparison. (You can not use these as a value on the right side of a comparison.)

  ninputs()

  The highest wired input number. This may be more than the number of wires if inputs in the middle are not connected. It also counts subnet inputs that may not be wired in the parent node.

  hasinput(‹n›)

  Returns 1 if the given input number is connected, or 0 if not. This does not count an input wired into a subnet input if that input is not also wired in the parent node.

  isparm(‹parmname›)

  Returns 1 if this parameter’s name is ‹parmname›. This is meant for use with multiparm items.

  For example, this rule would apply to the first item in a multiparm named blend, but not the second (blend1), third (blend2), and so on:

  { isparm(blend0) == 1 }
  

• The tab has two table editors, one for inputs and one for outputs.

• Click Create/update inputs from parameters to automatically create inputs based on the node’s parameters. This lets the user override parameter values by connecting inputs.

  The button creates inputs with the same name and label, and guesses the input type from the parameter type. If an input already exists with the same name as a parameter, the button only updates the label, so that changes to the input type aren’t overwritten.

  Inputs based on parameters cannot be edited in the table. They are marked with an info icon.

  If you manually create an input that has the same name as a parameter, they will automatically be linked.

• To add an input or output, choose the type from the New input or New output menus above the tables.

• Click the name, or label of an existing input/output in the table to edit it.

• Select the first cell in a row and then drag it up or down to rearrange the row in the table.

  You can select multiple rows by Shift-clicking or Ctrl-clicking the first cell of each row, and then drag multiple rows at once.

  You can drag column headings to rearrange signature order.

• To delete an input/output, click the Delete icon in the row.

• Some cells cannot be edited or deleted. For example, inputs corresponding to parameters, and outputs corresponding to exported parameters or VOP network outputs.

• A VOP can have multiple signatures: a set of input types and output type. For example, the Sine VOP has different signatures (float → float, vector → vector) corresponding to the different usages of the VEX sin function.

• Each signature is represented by a column in the inputs table, and three columns in the output table. You can match them up by the Signature name (the first cell in a signature column). Initially, a VOP node has one signature named default.

• You can use the New signature button to add a new signature (that is, a new way of calling the underlying VEX code with a different set of typed arguments and a different output). This adds one new column to the top inputs table, and three columns to the bottom outputs table.

• The first cell in a signature column is the signature name. The second cell is a human-readable label for the signature. The third cell is a shader function name for that signature, but can be left empty if there is no specialized function for it. These are shown in both the signature column in the input table and the corresponding first column of the signature in the output table. Editing the name or label in one table automatically updates the other.

• The signature shader row can optionally specify a specialized shader function name to use when VOP has that signature. Some shader languages allow overloading shader function name (i.e., allow functions of the same name have different parameter types), in which case this row is usually left empty. But for languages that don’t allow two function of the same name, this row allows specifying separate shader function name for each of the VOP’s signatures.

• In the inputs table, the rows of a signature column (after the name, label, and shader rows) contain the types of each input when that signature is active. (The user chooses the active signature from a pop-up menu at the top of the node’s parameter interface.) click a cell to choose the type from a pop-up menu.

  In the outputs table, the rows of the first signature column (after the name and label rows) contain the type of the output.

• To provide a default parameter to use for a particular signature, create a parameter with the same name as the input, followed by an underscore, then the name of the signature.

  For example, suppose you have two inputs, color and multiplier, which have the data types vector4 and float. You would create two parameters, also called color and multiplier. The first would be a Color parameter, and the second a single float parameter. Now you want to allow multiplier to also be a vector4. Create a new signature, and name it v4. Change the data type of multiplier for that signature to vector4. The create a new parameter named multiplier_v4, which is 4 floats. Now when one of these operator is created, and the signature is set to v4, the VEX Builder will use the color and multiplier_v4 parameters to provide the default values.

Use this tab to create, edit and store a python viewer state script associated to this asset. When the asset is loaded, Houdini registers the viewer state to make it available for use. Likewise, when the asset is unloaded, the viewer state is unregistered from Houdini and no longer available for use.

def createViewerStateTemplate():
    state_typename = kwargs["type"].definition().sections()['DefaultState'].contents()

This tab lets you create shelf tools associated with this asset. When the asset is loaded, the tools you define on this tab will be available for the user to add to the shelf, and will show up in the viewer tab menu.

When you create an asset, Houdini automatically adds a tool to this tab, that invokes a generic script to create an instance of the asset. You can edit the script of this tool, or add additional shelf tools to provide alternate ways of instantiating the asset. Click Create New and choose Tool to start a new tool.

See how to create shelf tools.

The controls on this tab let you create handles (3D user interface elements that appear in the 3D view) and bind the editable parts of the handles to parameters on your asset. This lets the users of your asset control it interactively in the view. The handles appear in the Handles tool when an instance of this asset is current.

The controls in this pane are the same as for the Persistent handle editor.

This tab lets you set up a (possibly multi-step) selection process to allow the user to select what (objects/geometry) the node applies to when you create it. For example, you have the node prompt the user to select an object your object-level asset will attach to.

The Type field is not editable and reflects the basic type of the selector. The Name field is the English name which should uniquely define this selector with respect to the operator type. The Prompt field displays the string during the selection process. The Multi-selection checkbox indicates whether or not multiple object selections are allowed for the current selector. The editable text field allows for a user-defined script to be executed when object selections are finished. The input objects are accessed by the variables $argc, and $arg0, $arg1,..., $arg($argc-1), where $argc is the number of inputs and the remaining variables represent each of the input objects.

There is no variable which holds a path to your current node; however, you can retrieve the current node using the pwd HScript command.

For example, you can wire in the first selected input into your current node by doing the following:

set curNode = `run("pwd")`
opwire -n $arg0 -1 $curNode

Use this tab to create, edit and store a python viewer handle script associated to this asset. When the asset is loaded, Houdini registers the viewer handle to make it available for use by Python viewer states. Likewise, when the asset is unloaded, the viewer handle is unregistered from Houdini and no longer available for use.

def createViewerHandleTemplate():
    handle_type = kwargs["type"].definition().sections()["ViewerHandleName"].contents()
    handle_label = "My Handle Label"
    handle_cat = [hou.sopNodeTypeCategory()]

    template = hou.ViewerHandleTemplate(handle_type, handle_label, handle_cat)