Houdini Engine 5.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages


The Houdini Engine SessionSync feature allows the plugin to connect to a session of Houdini Engine running inside Houdini. In terms of functionality, it supports all the features of the regular (headless) Houdini Engine workflow, along with additional features specific to SessionSync. It allows to visualize the state of Houdini Engine session through the Houdini viewport and interface. Changes to assets and nodes in either application, whether in Houdini or the Houdini Engine client, will be synchronized so that both applications will be able to make changes and see the same results.

SessionSync enables the following workflows:

  • visualize the state and troubleshoot loaded assets and hip files
  • real-time feedback when building an asset in Houdini and seeing its generated output in the Houdini Engine client
  • use Houdini tools and interfaces that haven't been replicated or aren't available in Houdini Engine client (e.g. python states)
  • synchronize the Houdini viewport with Houdini Engine client viewport
  • better understanding of Houdini Engine client features and limitations

Note that Houdini Engine SessionSync replaces the Houdini Engine Debugger in Houdini 18.0 and earlier.


Support for SessionSync can be added to Houdini Engine plugins using the following guide.

Connecting to or Starting SessionSync

Plugins can launch Houdini with SessionSync enabled, or connect to an existing Houdini instance with SessionSync already running.

Launching Houdini with SessionSync enabled:

Launch a Houdini executable with the -hess argument. This argument signals to Houdini to start the SessionSync server, and open the SessionSync panel at launch. See Command line options for more information about this command argument. While Houdini is launching, the plugin can be programmed to attempt connecting to SessionSync over some period of time. For example, the Unity plugin attempts to connect every few seconds over a 2 minute period. See the next section on connecting to the server.

Connecting to SessionSync server:

In order to connect to SessionSync, it must already be running in Houdini. If Houdini has already been launched and SessionSync hasn't started, it can be done so using the Houdini Engine SessionSync pane.

Once SessionSync has started, to connect to it, use either HAPI_CreateThriftNamedPipeSession() or HAPI_CreateThriftSocketSession(). In fact, these are the same APIs used to connect to HARS (the out of process Houdini Engine server) in the regular plugin workflow.

Asset Cook Synchronization

Typically changes to loaded Houdini digital assets (HDAs) via their parameters or inputs are made on the Houdini Engine plugin side. In SessionSync, these same changes can also be made directly in Houdini via the parameter interface or network editor. These changes will cook the asset in Houdini. To synchronize the changes and the cooked results from Houdini to the plugin, SessionSync provides a method for enquiring whether the asset has cooked in Houdini since the last enquiry. The HAPI_GetTotalCookCount() will return the total accumulated cook count of a node and its children (based on node type filters) in Houdini. The plugin can cache the value of this call and compare it in future calls to determine if the asset has changed. If the cook count has changed, it should cook the asset again through HAPI using HAPI_CookNode(), and then acquire the updated parameters, state, and generated outputs of the asset through the regular HAPI methods. It is important to cook the asset using HAPI_CookNode() as it will update the internal state of the asset in Houdini Engine. This should not result in a full Houdini cook of the asset, so the cook process should be fairly fast and lightweight.

It is recommended to check the cook count of each instantiated asset periodically to provide a seamless user experience. For example, the Unity plugin checks whenever the Unity Editor window updates or repaints.

Non-Asset Nodes

While Houdini Engine is typically used with Houdini digital assets, HAPI does allow creating and using nodes and networks without having to create assets from them. With SessionSync, the Houdini interface provides a natural way to create and edit node networks. The limitation here is that the nodes must be created through HAPI in order for them to be registered with Houdini Engine. Therefore, use Create, Delete, Connect Nodes to always create new nodes or delete them. Cook updates to these nodes can be queried via HAPI_GetTotalCookCount() from the plugin.

Non-Asset Nodes Saving and Loading

Non-asset nodes and their internal network can be saved to a file, or loaded from a file. This mechanism allows plugins to use and store file references to regular nodes and networks. This is similar to an asset stored in a HDA file. Note that this is currently an experimental feature, and therefore is limited and subject to change. Feedback is appreciated via our forums or support email.

Cooking using Houdini Time

In regular workflow, when cooking an asset or node, Houdini Engine defaults to using time 0 or the time value that the plugin has specified via HAPI_SetTime(). In SessionSync, Houdini will use the current time (from the timeline) when it cooks nodes, which conflicts with the Houdini Engine time. To keep things consistent, in SessionSync, Houdini Engine is set to use the current time in Houdini when cooking using HAPI_CookNode(). This behaviour can be queried via HAPI_GetUseHoudiniTime() and enabled or disabled via HAPI_SetUseHoudiniTime(). It is not recommended to disable this in SessionSync.

Viewport Synchronization

The Houdini viewport can be synchronized with other application viewports through the use of HAPI_Viewport, HAPI_GetViewport(), and HAPI_SetViewport(). HAPI_Viewport stores the camera pivot, orientation, and offset from the pivot. This information can be used to recreate the viewport camera in other applications. In SessionSync, Houdini will update Houdini Engine's viewport when its own viewport has changed, and will synchronize its own viewport with Houdini Engine's viewport if the latter's viewport has changed. Similarly, plugins can implement the same logic using the provided viewport APIs. For example, the Unity plugin provides the viewport synchronization feature.


The HAPI_SessionSyncInfo struct is a container of SessionSync settings that can be used for synchronizing all of the setting values between Houdini and plugins. Houdini will update a cached copy of this struct in the Houdini Engine session, and synchronize with it when it changes. Plugins can use HAPI_GetSessionSyncInfo() and HAPI_SetSessionSyncInfo() to retrieve and update the copy periodically.

Reference Implementation

The Unity plugin fully implements all of the SessionSync features. It can be used as a reference for integration of these features. The plugin source can be found on Github.

Specifically, the following files implement the SessionSync functionality:

  • HEU_SessionSyncWindow.cs Implements logic and UI for starting and connecting SessionSync, settings, creating new nodes, and loading non-asset nodes.
  • HEU_SessionSyncData.cs Contains the local SessionSync data for the current Houdini Engine session.
  • HEU_NodeSync.cs The non-asset node construct in the Unity plugin.