• If you need to check whether some code ran, the easiest way is to call hou.ui.displayMessage:

  import hou
  hou.ui.displayMessage("I ran! I ran so far away!")
  

  You can also use this to display the values of variables. For example, to see what’s in the kwargs global variable in an event handler:

  import hou
  hou.ui.displayMessage(repr(kwargs))
  

• You can share code between handlers by putting it in a module on disk and calling it from the handler script. For example, the handler script might just pass the kwargs to a common function:

  import companyutils
  
  companyutils.on_created(kwargs)
  

• Houdini has a very large, powerful (but verbose) set of APIs. Browsing through what’s available in the API reference will help you discover what’s possible with scripting.

• In general, Houdini looks for “scripts” (usually callback scripts) on disk under HOUDINI_PATH/scripts/, while modules you would import are under HOUDINI_PATH/scripts/python/ or HOUDINI_PATH/pythonX.Ylibs.

Houdini will look for these directories/files in the directories specified on the Houdini path.

Houdini lets you run scripts before and/or after a save. This can be useful to update asset management and source control tools whenever a save occurs.

• Before Houdini saves the scene file, it will run HOUDINI_PATH/scripts/beforescenesave.py if it exists.

• After Houdini attempts to save the scene file, it will run HOUDINI_PATH/scripts/afterscenesave.py if it exists.

The scripts run in a context containing a global dictionary named kwargs. This dictionary contains the following items:

The following example automatically “stages” the file for commit in git when it’s saved:

# afterscenesave.py
import subprocess

# Only run the command if the save succeeded and it's
# not an autosave
if kwargs["success"] and not kwargs["autosave"]:
    # Pass the scene file path to the git command
    subprocess.call("git", "add", kwargs["file"])

You can register a callback function that Houdini will call whenever a the scene file changes. Houdini calls the function with one argument. The argument is a hou.hipFileEventType object representing the type of event that occurred.

Instead of subscribing to a specific event, the script will be called for every event, and you need to check the event type to see if it’s an event you're interested in. This is usually more convenient for scene events, since you will often share code between reactions to several events.

In the script, you can use the functions in the hou.hipFile module to get information about the current scene file. Each file operation (New file, Open file, Import file, Save) has corresponding “Before” and “After” event types, so you can read the scene file’s values before and/or after the change.

For example, to run some code every time a new scene file is loaded:

def scene_was_loaded(event_type):
    if event_type == hou.hipFileEventType.AfterLoad:
        print("The user loaded", hou.hipFile.path())

See Python parameter expressions.

Houdini keeps a Python module associated with the scene file. You can edit it using Window ▸ Python source editor. This gives you a convenient place to store functions, classes, and objects specific to the scene file, and automatically have them saved and loaded with the scene file.

When the scene file is loaded (or when you edit the source code), the module source code is evaluated and the module is available to other Python code as hou.session.

For example, you write a log_deletion() function in the Python source editor, then call it from an asset deletion callback like this:

hou.session.log_deletion()

You can programmatically modify the hou.session source code using the hou.appendSessionModuleSource() function. The source code is saved with the scene file.

Each digital asset type has a Python module, similar to the scene file’s hou.session module. You can use this module to store functions, classes, and objects specific to the asset type.

The module source code is stored in a section of the asset named PythonModule (on the Extra files tab of the type properties window). You can create this section manually, or Houdini will create it automatically if you create a “Python Module” event handler on the Scripts tab.

In the HDA module’s code, you can get a reference to the HDA’s node type using:

nodetype = kwargs["type"]

You can access the module using the hou.NodeType.hdaModule method (if you have a NodeType object) or the hou.OpNode.hdaModule method (if you nave a Node object). For example, to call a myfunc function on the myasset object type:

hou.nodeType(hou.objNodeTypeCategory(), "myasset").hdaModule().my_function()

Python expressions on nodes inside the asset definition can access the PythonModule through relative references. For example, a Python parameter expression on a node in the asset’s definition subnetwork could use hou.node("..").hdaModule().foo().

If you have so much Python code inside an asset that you want to organize it into multiple modules, you can create other HDA sections to store those modules. For example, you could create a FooModule section containing Python code. Then in the main PythonModule section, use the following code to import the contents of FooModule as foo:

import toolutils
foo = toolutils.createModuleFromSection('bar', kwargs['type'], 'FooModule')

Houdini automatically adds any $HOUDINI_PATH/pythonX.Xlibs directories to the Python path, meaning packages and modules inside those directories can be imported in Python code.

To make packages and modules in other locations available to python, use the $PYTHONPATH environment variable, or modify the sys.path list in Python.

For example, to import the module in $HOUDINI_USER_PREF_DIR/pythonX.Ylibs/mystuff.py:

import mystuff

mystuff.my_function()

If you are trying to keep your script to a single line (for example, in a parameter expression or callback), you can use Python’s built-in __import__ function to return the module and immediately access its attributes:

__import__("mystuff").my_function()

You can write Digital asset event handlers in Python. After you create an event handler on the Scripts page of the type properties window (for example “On Created”), make sure Edit as is set to “Python”.

The event script can access the event parameters in a global dictionary variable called kwargs. For example, to get the hou.OpNode object involved in the event, use kwargs["node"].

See how to reference embedded files for information on how to refer to the embedded scripts wherever Houdini expects a filename.

on_created_body = """
from my_studio import register_stats
register_stats.createdSpecialNode()
"""

# Get a reference to the asset definition
hdadef = hou.nodeType("mystudio::Sop/flamingo::2.0").definition()
# Create the event handler section on the asset
hdadef.addSection('OnCreated', on_created_body)
# Set the "IsPython" option on the section
hdadef.setExtraFileOption("OnCreated/IsPython", True)

You can set up event handlers on individual node instances. Unlike asset events, which trigger when the event happens for any instance of the asset, these handlers only run when an event happens to the specific node you set them up on.

See hou.OpNode.addEventCallback for how to set up an event handler on a node. See hou.nodeEventType for the types of events you can react to.

You can set up handlers for changes to asset libraries. For example, when an asset is created or deleted, or an asset library is installed or uninstalled.

See hou.hda.addEventCallback for how to set up an asset library event handler. See hou.hdaEventType for the types of events you can react to.

You write the script that runs when the user clicks a shelf tool in Python. See how to write a tool script for more information.

You can write Python scripts that are called whenever the value of a parameter on a node changes.

If the default callback language is HScript, remember to change it to Python.

The event script can access the event parameters in a global dictionary variable called kwargs. For example, to get the hou.OpNode object containing the parameter, use kwargs["node"], and to get the hou.Parm object of the parameter, use kwargs["parm"].

hou.pwd().hm().my_callback(kwargs, hou.pwd())

The following table lists the contents of the kwargs dictionary for parameter callbacks:

You can use Python to generate dynamic parameter menus.

If a Python menu script contains only one line, Houdini evaluates it as a Python expression. If it contains multiple lines, Houdini evaluates it as a function body and you must use return to return the list. This behavior is the same as for Python parameter expressions.

The script must return a flat list of strings, where the even items are tokens and the odd items are labels. For example:

["1", "Light", "50", "Medium", "100", "Heavy"]

pairs = [("1", "Light"), ("50", "Medium"), ("100", "Heavy")]

return [item for sublist in pairs for item in sublist]
# -> ["1", "Light", "50", "Medium", "100", "Heavy"]

For example, to generate a menu of Object-level digital assets using Python:

result = []
for tool in hou.shelves.tools().values():
    node_type_name = tool.toolMenuOpType(hou.paneTabType.NetworkEditor)
    if (node_type_name.startswith("Object/") and
            'Digital Assets' in tool.toolMenuLocations()):
        result.append(tool.name())
        result.append(tool.label())
return result

In an asset, you can put the code that generates the menu into a function in the asset’s PythonModule section (for example, a generate_menu function) and call that function in the menu script hou.pwd().hdaModule().generate_menu().

The menu script can access the calling parameter in a global dictionary variable called kwargs. For example, to get the hou.OpNode object containing the parameter, use kwargs["node"], and to get the hou.Parm object of the parameter, use kwargs["parm"].

The following table lists the contents of the kwargs dictionary for parameter callbacks:

You can create “button strip” and “icon strip” parameters (either on an asset or as spare parameters). You can use these to provide a strip of clickable action buttons, or a strip of mutually exclusive options you can select from, or a strip of independent options you can individually turn on or off.

• When you create a strip parameter, you set whether it is “Normal” (mutually exclusive: only one item can be selected at a time) or “Toggle” (each item can be turned on or off individually).

• Reading the value of a “Normal” strip is straightforward. hou.Parm.eval will return the index of the selected item (starting from 0).

  To translate the index into the corresponding token you set up for each item in the menu, you can get the list of tokens from the parameter template and then index into that list:

  def get_selected_token(parm):
      # Read which item is currently selected
      selected = parm.eval()
  
      # Get the list of menu tokens from the parameter template
      tokens = parm.parmTemplate().menuItems()
  
      # Return the token corresponding to the selected item
      return tokens[selected]
  
  # In a parameter callback script...
  token = get_selected_token(kwargs["parm"])
  

• Reading the value of a “Toggle” strip returns a bit field . This is a number where each “bit” in the number’s binary representation encodes the on/off state of a button in the strip.

  If you're not a hardcore programmer that probably sounds very technical, but all you need are some utility functions like the ones below to translate a bit field into a more usable form.

  # The general form to test if the "bit" at position n is "on"
  # in a number is:
  # number & (1 << n)
  
  def strip_to_tokens(parm):
      # Takes a reference to a button/icon strip parameter
      # instance and returns a list of tokens corresponding
      # to the buttons that are on
  
      bitfield = parm.eval()
      tokens = parm.parmTemplate().menuItems()
      return [token for n, token in enumerate(tokens) if bitfield & (1 << n)]
  
  def is_n_selected(bitfield, n):
      # Returns True if the nth position (starting at zero)
      # is "on" in the bitfield
  
      return bitfield & (1 << n)
  
  def bitfield_to_list(bitfield, size=32):
      # Takes a bitfield and returns a list of booleans
      # (True or False) indicating whether each position
      # is "on" or "off" in the bitfield.
      # ("size" is the number of buttons in the strip.)
  
      return [bitfield & (1 << n) for n in range(size)]
  

• Working with the value of a “toggle” strip in an expression would be extremely difficult. If for some reason you need the settings of a toggle strip to drive an expression, a workaround would be give the strip a callback script that sets a simple value on a hidden parameter based on the strip settings. Then reference the hidden parameter in the expression instead of the strip.

• To make a button/icon strip that acts more like a toolbar of action items, make a “Toggle” strip, then give it a callback script that reads which item was turned on, performs some action based on that, and then immediately turns the option off again.

  For example:

  import math
  
  # A button strip callback strip that makes the buttons act like
  # action buttons. This script assumes the menu type is set to "Toggle". 
  
  # Read which button was turned on
  parm = kwargs["parm"]
  bitfield = parm.eval()
  # Only one item in the bitfield should be selected, so the base-2
  # log of the bitfield should give us the index of the selected button
  selected_index = int(math.log(bitfield, 2))
  
  # Do something here based on which button was clicked
  
  # Clear the selected button. Setting the parameter's bitfield value
  # to zero turns off every button.
  parm.set(0)
  

You can use Python to generate a new key-value pair for a key-value parameter when the user clicks a button. This script can present an interface for the user to choose a preset (for example, using hou.ui.selectFromList or hou.ui.selectFromTree). It must return a (key, value) tuple.

If the value in the field 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 and must use a return statement at the end to return a value. This is consistent with other parameter callbacks.

• The script can return return non-string values in the tuple. Houdini will convert them to strings.

• The script runs in an environment containing a kwargs global dictionary variable. kwargs["node"] contains a hou.OpNode for the node. kwargs["parm"] contains a hou.Parm reference for the key-value parameter.

• If the user cancels choosing, the script should return empty strings in the tuple ("", "").

• We recommend you define a function to handle the callback in the asset’s Python module.

  For example, you can put this function in the asset’s Python module:

  def choose_env_variable():
      """
      Lets the user choose an environment variable name and returns
      the name and value to the key-value parameter.
      """
  
      # Grab the environment variable dictionary from the OS
      import os
      names = os.environ.keys()
      # Use a Houdini UI function to ask the user to choose from the list
      results = hou.ui.selectFromList(names)
      if not results:
          # The user didn't choose anything
          return ("", "")
      # We only support choosing one item; if the user picked more than
      # one item, just use the first
      chosen_index = results[0]
      # hou.ui.selectFromList() returns the number of the chosen item;
      # translate that back into a name
      chosen_name = names[chosen_index]
      # Return a tuple of the variable name and the value of that variable
      return (chosen_name, os.environ[chosen_name])
  

  Then you could call it using this in the Chooser callback field:

  kwargs["node"].hdaModule().choose_env_variable()
  

  If the callback function needs the node and/or parameter reference, you can pass them to the function:

  kwargs["node"].hm().choose_env_variable(kwargs["node"], kwargs["parm"])
  

• Note that the callback does not need to interactively ask the user to choose something. You could have a button that adds a key-value pair based on current conditions.

  For example, you could put this in the Chooser callback field:

  (hou.frame(), hou.time())
  

  When a user clicked the button, this Python expression would evaluate to a tuple containing the current frame number and current time.

You can set up Python code to execute “in the background” while the user is working.

• You can use hou.ui.addEventLoopCallback to set up a function that Houdini calls whenever the UI is not busy.

  The callback function will be called very often (around 20 times a second). The function should be very fast to run so it doesn’t slow down the UI.

• You can use a Qt QTimer object to schedule code to run in the future. That code can itself set up another QTimer if you want some code to execute at a certain interval.

• You can use hou.findFile() to search for filenames in the Houdini path.

• To read content from an embedded file inside an asset, use hou.HDADefinition.sections to get a dictionary of section names to HDASection objects, then use hou.HDASection.contents to get the section contents.

  For example, to read the contents of an embedded file named example in the my_asset object:

  objects = hou.nodeTypeCategories()["Object"]
  my_asset = objects.nodeTypes()["my_asset"]
  my_asset_def = my_asset.definition()
  section = my_asset_def.sections()["example"]
  contents = section.contents()
  

  As a shortcut, you can use Houdini’s support for reading asset sections as if they were files using an opdef: path:

  content = hou.readFile("opdef:Object/my_asset?example")
  

• To access Python variables in the global scope from hou.session, import __main__. For example, if x is a variable in the global scope, you can access it as __main__.x.

  You can use this approach to access Python global variables from parameter expressions, HDA Python modules, Python button callbacks, shelf scripts, and so on.