Shotgun Engine for Houdini Shotgun Pipeline Toolkit integration in Houdini Latest Version: v1.6.0 (prod) For our version numbers, we follow the Semantic Versioning standard. System Name: tk-houdini

Documentation

The Shotgun Engine for Houdini contains a standard platform for integrating Shotgun Apps into Houdini.

Information for App Developers

Supported platforms

The Shotgun Engine for Houdini is currently supported on Windows, Linux, and OSX.

On OSX, only more recent verisons of Houdini are supported (14 and 15). Due to the way that older verisons of Houdini were compiled for OSX (with operating system level garbage collection) there was no supported Qt build that was binary compatible with the application. As of Houdini 14, Houdini comes bundled with PySide so there is no need for an external build.

PySide

For older versions of Houdini (13 and older) an external build of PySide is required. On Windows, we have bundled a compatible PySide build that will work with the python that Houdini runs. On Linux, Houdini uses the system python (per http://www.sidefx.com/docs/houdini12.0/hom/) which needs to have PySide or PyQt support.

Menu loading

A dynamic menu system was introduced by Side Effects as of Houdini 15, so the engine now supports rebuilding of the Shotgun menu on context switches.

In Houdini 14 and older, the Shotgun menu in Houdini is generated before Houdini starts and is static throughout the session. Due to this, the toolkit commands registered in the menu will not update on context changes.

Shotgun shelf

Release v0.2.4 introduced a dynamic Shotgun shelf to the engine. The shelf displays any registered app commands as tool buttons. The buttons will be displayed in roughly the same order as the menu commands.

Use the enable_sg_shelf setting to turn on the shelf within an environment. If using a version of Houdini (14 or older) that does not support dynamic menus, you may also want to turn off the Shotgun menu when using the shelf. This can be done by setting the enable_sg_menu setting to false.

To enable context switching via the shelf, you'll also need to add entity types to the sg_entity_types setting of the tk-multi-workfiles app in your engine configuration.

Here's a look at the settings related to the Shotgun shelf:

tk-houdini:
  apps:
    # ... other app definitions
    tk-multi-workfiles:
       # ... other app settings
       sg_entity_types: [Shot, Asset] # allow context switching to Shots or Assets
       # ... other app settings
  enable_sg_shelf: true
  enable_sg_menu: false
  # ... other engine settings

Once you've enabled the Shotgun shelf, you need to manually add it to a shelf set inside houdini.

Once added to a shelf set the Shotgun shelf will remain there between houdini sessions and will update dynamically as your shotgun context changes.

Panels

As of v0.2.8 the engine adds support for embedded toolkit panels.

The panel support currently requires Houdini version 15.0.272 or later for proper embedded panels. Registered panels will show up as panes in the pane menu for supported versions of Houdini.

Older versions of Houdini will display the registered panels as dialogs. SESI may backport some bug fixes to newer builds of Houdini 14. If and when that happens, we will make embedded panels work for those versions as well.

Apps with OTLs

The Shotgun Engine for Houdini makes it easy to load application supplied OTLs. If you are writing an app which uses OTLs, you can just drop them into a folder called otls and the engine will automatically load them into your session:

You can then easily access your nodes via the usual Houdini methods.

Warning!! Please note that while the use of OTLs may be convenient, it is typically NOT the right solution if you want to create nodes that persist in a scene. The reason for this is because as soon as you have put an OTL in the scene, you have introduced a dependency between that scene and the OTL code. Not only will you need to load the Shotgun Toolkit every time you load the scene, but you also need to carefully manage your code so that any updates to the code does not break old OTLs being used in scenes.

Startup Debugging via Terminal on OSX

Turning on debug_logging for the tk-houdini engine on OS X will not send all debug messages to the Terminal. This is because, by default, the tk-multi-launchapp app uses the open command to launch executables. This does not spawn a new subprocess from the Terminal, but rather uses OS X's Launch Services to create a new process elsewhere. As a result, the log statements are not shown. Even having a python shell saved in the user's default desktop in houdini does not seem to show debugging statements during startup. After startup, and embedded python shell will show debug logging statements, but there is a gap in available output during startup. If you need access to debug logging statements during engine startup, you can make 2 changes.

First, change your houdini_mac path (temporarily) in your test configuration to point to the executable inside the Houdini app bundle. For example:

#houdini_mac: /Applications/Houdini 15.0.272/Houdini Apprentice.app
houdini_mac: /Applications/Houdini\ 15.0.272/Houdini\ Apprentice.app/Contents/MacOS/happrentice

Next, you can make a copy of the tk-multi-launchapp app's app_launch hook in your test configuration's config/hooks directory and point to it in your config/env/includes/app_launchers.yml file:

launch_houdini:
  defer_keyword: ''
  engine: tk-houdini
  extra: {}
  hook_app_launch: app_launch    # <----- use a custom app_launch hook
  hook_before_app_launch: default
  icon: '{target_engine}/icon_256.png'
  linux_args: ''
  linux_path: '@houdini_linux'
  location: {name: tk-multi-launchapp, type: app_store, version: v0.6.6}
  mac_args: ''
  mac_path: '@houdini_mac'
  menu_name: Launch Houdini
  versions: []
  windows_args: ''
  windows_path: '@houdini_windows'

Then all you have to do is modify the launch logic to launch the executable directly. As an example, you could keep the old behavior for directories (application bundles) and otherwise execute the command directly. Here's an example:

        elif system == "darwin":
            # on the mac, the executable paths are normally pointing
            # to the application bundle and not to the binary file
            # embedded in the bundle, meaning that we should use the
            # built-in mac open command to execute it
            if os.path.isdir(app_path):
                cmd = "open -n \"%s\"" % (app_path)
                if app_args:
                    cmd += " --args \"%s\"" % app_args.replace("\"", "\\\"")

            # not a directory, execute directly
            else:
                cmd = "%s %s" % (app_path, app_args.replace("\"", "\\\""))

The next time you run launch_houdini via tank in the Terminal, you should get all the debug output. Once you're done testing, don't forget to revert your path and undo your app launch changes. Happy debugging!

Installation and Updates

Adding this Engine to the Shotgun Pipeline Toolkit

If you want to add this engine to Project XYZ, and an environment named asset, execute the following command:

Updating to the latest version

If you already have this item installed in a project and you want to get the latest version, you can run the update command. You can either navigate to the tank command that comes with that specific project, and run it there:

> cd /my_tank_configs/project_xyz
> ./tank updates

Alternatively, you can run your studio tank command and specify the project name to tell it which project to run the update check for:

> tank Project XYZ updates

Collaboration and Evolution

If you have access to the Shotgun Pipeline Toolkit, you also have access to the source code for all apps, engines and frameworks in Github where we store and manage them. Feel free to evolve these items; use them as a base for further independent development, make changes (and submit pull requests back to us!) or simply tinker with them to see how they have been built and how the toolkit works. You can access this code repository at https://github.com/shotgunsoftware/tk-houdini.

Special Requirements

• You need Shotgun Pipeline Toolkit Core API version v0.18.45 or higher to use this.

Configuration

Below is a summary of all the configuration settings used. These settings need to be defined in the environment file where you want to enable this App or Engine.

run_at_startup

Type: list

Description: Controls what apps will run on startup. This is a list where each element is a dictionary with two keys: 'app_instance' and 'name'. The app_instance value connects this entry to a particular app instance defined in the environment configuration file. The name is the menu name of the command to run when the Houdini engine starts up. If name is '' then all commands from the given app instance are started.

enable_sg_shelf

Type: bool

Default Value: True

Description: Controls whether a shelf will be built with commands registered by the installed apps. The shelf will be rebuilt dynamically as the Shotgun context changes.

menu_favourites

Type: list

Description: Controls the favourites section on the main menu. This is a list and each menu item is a dictionary with keys app_instance and name. The app_instance parameter connects this entry to a particular app instance defined in the environment configuration file. The name is a menu name to make a favourite.

launch_builtin_plugins

Type: list

Description: Comma-separated list of tk-houdini plugins to load when launching Houdini. Use of this feature disables the classic mechanism for bootstrapping Toolkit when Houdini is launched.

debug_logging

Type: bool

Description: Controls whether debug messages should be emitted to the logger

automatic_context_switch

Type: bool

Default Value: True

Description: Controls whether toolkit should attempt to automatically adjust its context every time the currently loaded file changes. Defaults to True.

enable_sg_menu

Type: bool

Default Value: True

Description: Controls whether a menu will be built with commands registered by the installed apps. It is not currently possible to rebuild the menu on a Shotgun context switch, so this option allows for the menu to be disabled in favor of the Shotgun shelf which can be rebuilt dynamically.

Release Notes

Welcome to the release notes for this Engine. Below you will find an overview of all the changes we did for each release. We try to be as detailed as possible and include all bugs we have fixed, features we have added and things that may have changed. If you have questions about a particular release, don't hesitate to contact our support team!

v1.6.0

2019-Jan-16

Compatibility fixes for Houdini 17.

v1.5.6

2018-Jun-27

Fixes a Qt dialog raising fatal error on Windows in Houdini 16.5.481+

v1.5.5

2018-May-19

Toolkit panel apps no longer causes built-in Houdini pypanels to be removed from the python pane menus.

Details:

Previously, we installed Toolkit panel apps to python pane menus in a destructive manner. This caused a few out-of-the-box Houdini pypanel apps to be removed from menus. This release also fixes a QCheckbox styling problem that resulted in missing check icons in panel apps.

v1.5.4

2018-May-11

Additional fix for slow Houdini startup when launched from a Task entity on Windows.

Details:

This fix is tied to when we load otls from disk for Toolkit apps. What was being done was correct, but when it was being done during startup of Houdini caused a pause in the launch that could take quite some time.

v1.5.3

2018-May-08

Fix for slow Houdini launching on Windows.

Details:

This is tied to our shelf population logic, but it doesn't appear to be anything we're doing wrong. Rather, as best as we can tell, it's WHEN our logic is being called during launch that causes Houdini to pause for some time. The fix is to defer the shelf population by an event loop cycle, which seems to resolve the issue without any ill effects.

v1.5.2

2018-Apr-19

Changes how we path to a checkbox image in qss. No visible change in functionality or styling.

Details:

Some issues around workfiles2 were reported by a few clients related to the os.chdir call we added as part of the v1.5.1 release of the engine. To address these issues, we've changed approaches to allow us to remove the os.chdir call.

v1.5.1

2018-Mar-09

Fixes a styling problem for checkboxes in Houdini 16.x on Linux.

v1.5.0

2018-Mar-02

Resolves a bug that caused panel apps to not load when launched from Houdini's native pane tab menu.

Details:

A mechanism was in place that renamed new PaneTabs in such a way that the engine could later identify it. This allowed us to activate an existing Shotgun Panel instance if one had been launched, rather than showing a duplicate. This breaks Houdini 16.x, however, so we've had to implement an alternative approach to get the same result.

v1.4.3

2018-Mar-01

Minor tweak to styling to help with text readability in some views.

v1.4.2

2018-Feb-22

Minor tweaks to scrollbar styling to make them prettier and easier to use.

v1.4.1

2018-Feb-21

Minor color fix for QMenu to make the menu item text more visible.

v1.4.0

2018-Feb-16

Styling fixes for Houdini 16.x.

Details:

Our old approach to styling from H15 and under causes problems with H16.x, where some of our style changes bleed into Houdini's dialogs. As such, we've had to take a different approach to styling for H16+.

v1.3.0

2017-Nov-08

Now houses publish2 plugin hooks and supports template-based worklfows

v1.2.7

2017-Aug-19

Stops Toolkit dialogs from falling behind Houdini on OS X.

v1.2.6

2017-Aug-16

Styling fixes for the Shotgun Panel app in H16 on OS X.

Details:

This change goes along with the temporary disabling of panel support for H16 on OS X in v1.2.5. When panel support is re-enabled, this styling change will also be removed.

v1.2.5

2017-Aug-16

Disables panel support for H16 on OS X.

Details:

This is a temporary measure while possible fixes for panel painting issues are discussed with SESI engineers. Our panel apps function properly on OS X in dialog mode, so that is the route we'll have to go for the time being. Panel support remains unchanged on Windows and Linux operating systems.

v1.2.4

2017-Aug-16

Bundles in a missing urllib2.py and fixes QLabel styling in H16.

v1.2.3

2017-Aug-15

Fixes to improve compatibility with Houdini 16.

Details:

Compatibility with Houdini 16 is improved. Engine-level qss has been added to address styling problems with Qt apps, and fixes for ssl compatibility with Python modules bundled with Houdini are included. There continues to be a Python pane problem on OS X, resulting in the Shotgun Panel app having some visual problems on that operating system.

v1.2.2

2017-Jun-29

Minor adjustments to logging output

v1.2.1

2017-May-12

bumps required core version to v0.18.45

v1.2.0

2017-May-10

Adds support for launching Houdini using the new Software entity setup in Shotgun. It also includes a houdini plugin that can run standalone or directly from within the engine.

v1.1.0

2017-Apr-25

Removes bundled PySide and updates to new logging style

v1.0.11

2017-Feb-10

Guard automatic context switching with a check of the engine config setting

v1.0.10

2016-Aug-19

Use existing path separator, fallback to os.pathsep

v1.0.9

2016-Aug-17

Use existing path separator, fallback to os.pathsep

v1.0.8

2016-Aug-06

hot fix for houdini bug when mouse over shotgun menu buttons.

v1.0.7

2016-Jun-24

Safer logic for modifying HOUDINI_PATH during bootstrap

v1.0.6

2016-Jun-24

Safer logic for modifying HOUDINI_PATH during bootstrap

v1.0.5

2016-May-24

Adds support for context switching when using the Recent Files menu in Houdini

v1.0.4

2016-May-23

Adds support for context switching when using the Recent Files menu in Houdini

v1.0.3

2016-May-20

Adds support for context switching when using the Recent Files menu in Houdini

v1.0.2

2016-Mar-31

Fix for embedded panel regression

v1.0.1

2016-Feb-18

Adds a call to log a user metric for the DCC version

v1.0.0

2015-Nov-25

Houdini engine 1.0 release. Supports H14, H15, OSX, reloadable menus, tk panels and more.

v0.2.11

2015-Nov-25

QA polish and fixes for houdini engine update

v0.2.10

2015-Nov-06

Added dynamic Shotgun menu for Houdini 15+. Menu now updates with context switching.

v0.2.9

2015-Nov-04

Make toolkit apps look nice and consistent inside Houdini

v0.2.8

2015-Oct-29

Panel support in houdini

v0.2.7

2015-Oct-29

Limits engine support on OS X to Houdini 14+

v0.2.6

2015-Oct-25

Updates tk houdini engine for Houdini 14

v0.2.5

2015-Oct-06

Fix for UNC paths for shelf icons

v0.2.4

2015-Sep-28

fix to allow Shotgun shelf to work in houdini 13

v0.2.3

2015-Sep-25

Updated Houdini to support dynamic shelf for registered commands

v0.2.2

Fixed issue where an exception was raised whenever a dialog was shown using engine.show_dialog or engine.show_modal

v0.2.1

Fixed issue with UNC paths on Windows when creating menus

v0.2.0

Updated engine to use new dark theme. Misc tweaks and fixes.

Details: - The engine now uses the new dark theme introduced in 0.14.56. Toolkit UIs running in Houdini now look more similar to Maya's UI look and feel. - Error logging no longer pops up error messages in dialogs, instead it just logs a message. This is consistent with they way other engines work. - Since houdini runs its python console in a separate thread, running toolkit command from the console which results in UI generation would previously crash the system. Added protection for this so that if a UI is launched outside of the main UI thread, an error message is raised.

v0.1.11

Updated PySide version handling to support very old versions!

v0.1.10

Support for Houdini 13 and Python 2.7

Details: Support for Houdini 13 and Python 2.7

v0.1.9

Fix for PyQt on linux.

Details: Fix for PyQt on linux.

v0.1.8

Fix to let the engine run from houdini batch and hython.

Details: Fix to let the engine run from houdini batch and hython.

v0.1.7

Updated PyQt compatibility

v0.1.6

Updated to support PyQt

Details: Updated to support either PyQt or PySide. PySide will be preferred if it is available.

v0.1.5

PySide bundled for Windows. Houdini version check. Unicode support. Fix for debug output.

Details: PySide for Windows is now bundled. As linux uses the system python, docs updated to reflect that dependency. Version check added for Houdini version 12+ Unicode support in PySide Fix for being able to turn off debug output.

v0.1.4

sgtk windows now first appear above houdini.

Details: Added os specific support to make sure that sgtk dialogs do not appear behind Houdini

v0.1.3

Experimental Release of the new engine version to the app store.

v0.1.2

Updated manifest to be 0.12.5 compatible

v0.1.1

Minor changes to work nicely with core v0.12.5

v0.1.0

Initial release to the App Store.