Houdini 20.0 Reference Windows

Viewer State Browser window

The Viewer State Browser window lets you list and manage python viewer states loaded in Houdini.

On this page


The browser offers the following functionalities:

  • List all registered viewer states.

  • Inspect the content of viewer states.

  • Identify viewer states with errors.

  • Access the viewer state python code from a file, embedded in the scene or stored in an HDA.

  • Display messages in a console area.

  • Add message markers to the console.

  • Trace the execution of an active state.

  • Display the content of the active state object in the console.

  • Edit, load, reload and, unload viewer state.

  • Code generator to help with the implementation and learning curve of viewer states.

The main components of the browser are the toolbar to access all the functionalities, a tree view to display the viewer states currently registered in Houdini and a console for logging information messages.

The browser is available as a Python panel. You can access the browser by clicking the new tab icon in the network editor and selecting New Pane Tab Type ▸ Viewer State Browser.

Tree View

The browser lists all registered python states in a tree view located on the left side. Each tree node represents a python state.

Tree Node

Tree nodes can be expanded to inspect the state properties and its bound elements. A tree node will typically (but not always) contain the following information:

  • Category: The state category such as Sop and Object.

  • Label: The state UI label (used for the tree node name).

  • Icon: The name of the state icon.

  • Node Type: The type of the node operator referencing the state. This node is available when the state is implemented in an HDA.

  • Source: The path to the state implementation. Scene embedded states are listed as Embedded.

  • Type: The state type name.

  • Contexts: A list of contexts compatible with the state.

  • Errors: Runtime and registration error messages.

  • Handles: List of handles bound to the state.

  • Menu: The state popup menu structure.

  • Parameters: The list of state parameters bound to the state.

  • Selectors: The list of selectors and their properties bound to the state.

  • Warnings: Runtime and registration warning messages.

Tree Node Menu

A popup menu is available for each tree node and contains action items specific to the type of state.

State implemented from a python module file

  • Edit: Opens a python editor and load the underlying state module file.

  • Enter: Enters the state. A node must be created and selected in the network view prior to run this action.

  • Exit: Exits the underlying state if active.

  • Expand All: Expands the tree node along with all its sub-nodes.

  • Reload: Reload the state.

  • Unload: Unload the state.

HDA and Embedded states

  • Uses the same menu as in the above but without the Reload and Unload items.


The console window is used for logging messages such as runtime errors, warnings, debugging and user messages.

The following buttons are available:

Clears the content of the console.

Prefix messages logged in the console with the actual time.

Adds a line marker in the console. Can be used as a message separator.

Dumps the content of the active state to the console for inspection.

Toggle button for enabling or disabling the message logging of the active state.

Toggle button for enabling or disabling a call trace of the active state event handler methods.


You use the toolbar to access the browser functionality through menus, select filters for displaying states in the tree view or to open the help page for python viewer states.

Toolbar menus

  • File

    • New State…

      Opens the Viewer State Code Generator dialog to create a new viewer state. The tree view should list the new state if the creation is successful.

    • Open State…

      Opens a python state file in the Python file editor. Unlike the Load State menu, the state is not loaded (registered) upon closing the dialog, therefore it will not be listed in the tree view.

    • Load State…:

      Loads (registers) a python state file from disk. The tree view should list the state if the load is successful.

    • Unload Selected State:

      Unloads (unregisters) the selected state in the tree view.

    • Reload Selected State:

      Reloads (unregisters/registers) the selected state in the tree view.

    • Reload All State:

      Reloads all states currently listed in the tree view.

    • Load Examples:

      Loads the Python State examples into Houdini. This installs all resources required to run the example scenes. See the Demo Viewer State shelf tools for the example scenes you can load.

  • Edit

    • Edit Selected State…

      Opens the selected state in a Python editor for editing.

  • Debug

    • Enter State

      Enters the selected state. A node must be created and selected in the network view prior to run this action.

    • Exit State

      Exits the active state.

    • Inspect State

      Inspects the content of the active state.

    • Trace Options

      Opens a dialog for configuring the tracing functionality of viewer states. For instance, you can select the event handlers you want to enable for tracing, or unselect event handlers to keep them off tracing.

Display Filters

Display filters are used for listing specific states in the tree view.

  • All

    Show all states.

  • Dop

    Show all DOP states only.

  • Lop

    Show all LOP states only.

  • Object

    Show all OBJ states only.

  • Sop

    Show all SOP states only.


When Houdini starts, all states in error can be displayed with the Invalid filter.


The following buttons are available in the toolbar.

Reloads all states currently listed in the tree view.

Opens the python viewer states documentation page.