Launch Application Launch Applications and initialize the Shotgun Pipeline Toolkit. Latest Version: v0.10.0 (prod) For our version numbers, we follow the Semantic Versioning standard. System Name: tk-multi-launchapp

Documentation

This app provides a shortcut to make it easy to jump from Shotgun to any supported application. It registers a Shotgun Action entry called for various entities in Shotgun according to your configuration choices.

How It Works

Depending on your configuration options a menu entry will appear in Shotgun when right-clicking entities or using the Shotgun actions menu or gear menu.

For example, this screenshot comes from a site who's configuration uses this app three times to implement menus for Maya, Nuke and Photoshop.

Currently supported applications and engines are:

• 3DSMax
• Hiero
• Maya
• MotionBuilder
• Nuke
• Photoshop
• Mari
• Houdini
• Softimage
• Flame

Use Command Line Arguments at Launch

Many applications have command line options that can be called to choose a different edition of the application (ex. Nuke vs. NukeX) or to specify other various usage aspects. The launcher app has an 'args' setting for each OS that can be configured for this purpose. For example if you put '--nukex' there, it will add that to the command line launch and NukeX will run instead of regular Nuke:

launch_nuke:
  engine: tk-nuke
  extra: {}
  hook_app_launch: default
  hook_before_app_launch: default
  linux_args: '--nukex'
  linux_path: '@nuke_linux'
  location: {name: tk-multi-launchapp, type: app_store, version: v0.2.15}
  mac_args: '--nukex'
  mac_path: '@nuke_mac'
  menu_name: Launch Nuke
  windows_args: '--nukex'
  windows_path: '@nuke_windows'

Set Environment Variables and Automate Behavior at Launch

Applications often require certain certain environment variables, plugin paths, etc. to be set in order to properly function in a studio pipeline. The launch app helps cover this case via the 'before_app_launch' hook, which allows you to define a snippet of code to run each time an application starts up. By default, the 'before_app_launch' hook is a simple pass-through that does nothing, but it can be overridden by following the instructions in this doc.

For example, if you use Zync Render, the Zync Maya plugin directory needs to be part of both $PYTHONPATH and $XBMLANGPATH. To have the launch app set these environment variables, update the 'before_app_launch' hook with a few lines of code, as follows:

def execute(self, **kwargs):
    """
    The execute functon of the hook will be called to start the required application        
    """

    # Example to show how to set env vars on Maya launch

    # Append the desired path to the existing $PYTHONPATH to ensure
    # everything upstream still works
    os.environ["PYTHONPATH"] = os.environ["PYTHONPATH"] + os.pathsep + "~/Library/zync/zync-maya"

    # Set $XBMLANGPATH to the desired path, may need to append it as
    # with $PYTHONPATH if already defined in your pipeline
    os.environ["XBMLANGPATH"] = "~/Library/zync/zync-maya"

You can also use the 'before_app_launch' to automate other behavior, including Shotgun updates. For example, you can configure the launch app to update the Task status (in this case, to "in progress") each time it's run (as long as the launch is from a Task, of course), as follows:

def execute(self, **kwargs):
    """
    The execute functon of the hook will be called to start the required application        
    """

    # If there is a Task in the context, set its status to 'ip'

    if self.parent.context.task:
        task_id = self.parent.context.task['id']
        data = {
            'sg_status_list':'ip'
        }
        self.parent.shotgun.update("Task", task_id, data)

As you can imagine, there are many possibilities here, and the launch app aims to provide the flexibility your pipeline needs.

Launching Applications that do not have an Engine Yet

You can also use the launch app to start up applications that do not have a Toolkit engine yet. In this case, folders will be created on disk for the shot, task or asset you are launching from and the application will be launched, but no code will run after application startup and no Shotgun menu will appear inside the application. This means that you can launch applications that are not yet supported by Toolkit from within Shotgun.

In order to do this, configure the app with paths to the application you wish to launch, but leave the engine option as an empty string.

Technical Details

3DSMax

This app automatically adds a MaxScript, init_tank.ms, to the 3DSMax command line that 3DSMax will run as part of its boot process.

When 3DSMax is booting, the following will happen:

1. 3DSMax will run init_tank.ms upon starting
2. init_tank.ms makes sure a Python interpreter is available and runs tank_startup.py
3. Using the Shotgun Toolkit Context API, the entity id passed from Shotgun is converted into a Toolkit Context.
4. Start the appropriate Engine (via tank.system.start_engine()) and pass in the Context. The engine will take care of the rest.

Extra configs

No extra configs are necessary for the 3DSMax engine

Hiero

Maya

This app registers a userSetup.py auto start script with Maya which Maya will call as part of its boot process.

When Maya is booting, the following will happen:

1. Maya starts execution of the userSetup.py startup script
2. Using the Shotgun Toolkit Context API, the entity id passed from Shotgun is converted into a Toolkit Context.
3. Start the appropriate Engine (via tank.system.start_engine()) and pass in the Context. The engine will take care of the rest.

Extra configs

No extra configs are necessary for the Maya engine

MotionBuilder

This app registers a init_tank.py auto start script with MotionBuilder which MotionBuilder will call as part of its boot process.

When MotionBuilder is booting, the following will happen:

1. MotionBuilder starts execution of the init_tank.py startup script
2. Using the Shotgun Toolkit Context API, the entity id passed from Shotgun is converted into a Toolkit Context.
3. Start the appropriate Engine (via tank.system.start_engine()) and pass in the Context. The engine will take care of the rest.

Extra configs

No extra configs are necessary for the MotionBuilder engine

Nuke

This app registers a menu.py auto start script with Nuke which Nuke will call as part of its boot process.

When Nuke is booting, the following will happen:

1. Nuke starts execution of the menu.py startup script
2. Using the Shotgun Toolkit Context API, the entity id passed from Shotgun is converted into a Toolkit Context.
3. Start the appropriate Engine (via tank.system.start_engine()) and pass in the Context. The engine will take care of the rest.

Extra configs

No extra configs are necessary for the Nuke engine

Photoshop

This app will use the Adobe Extension Manager to install or make sure the Tank plugin is installed.

When Photoshop is booting, the following will happen:

1. Photoshop will start the execution of the Tank Plugin
2. Using the Shotgun Toolkit Context API, the entity id passed from Shotgun is converted into a Toolkit Context.
3. Start the appropriate Engine (via tank.system.start_engine()) and pass in the Context. The engine will take care of the rest.

Extra configs

If you intend to use this app to launch Photoshop you will need to supply four config values in the extra section. Here are the configs and sane default values which you would need to adjust for your system and installation locations:

mac_python_path: "/usr/bin/python"
windows_python_path: "C:\\Python27\\python.exe"
mac_extension_manager_path: "/Applications/Adobe Extension Manager CS6/Adobe Extension Manager CS6.app"
windows_extension_manager_path: "C:\\Program Files (x86)\\Adobe\\Adobe Extension Manager CS6\\XManCommand.exe"

Related Apps and Documents

Launch Published File This app works in conjunction with the launcher app and lets you right click on a published file in order to launch it in its host application. Shotgun will start up the relevant application and initialise the Shotgun Pipeline Toolkit via a launcher app and then finally load the file in.

Admin Guide This is the Admin Guide for Shotgun Integrations.

User Guide This is the User Guide for Shotgun Integrations.

Installation and Updates

Adding this App to the Shotgun Pipeline Toolkit

If you want to add this app to Project XYZ, in 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-multi-launchapp.

Special Requirements

• You need Shotgun Pipeline Toolkit Core API version v0.18.74 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.

linux_args

Type: str

Description: The arguments to be passed to application on Linux, as a string.

engine

Type: str

Description: The name of the Shotgun engine to start. This is typically the application name prefixed with tk, e.g. tk-maya, tk-nuke, tk-photoshop etc. If you set this to an empty string, no toolkit engine will be started, meaning that you can launch applications that do not have toolkit engines set up.

mac_args

Type: str

Description: The arguments to be passed to application on Mac OS X, as a string.

windows_path

Type: str

Description: The path to the application executable on Windows.

group

Type: str

Description: The name for a group this command should be considered a member of.

hook_before_app_launch

Type: hook

Default Value: before_app_launch

Description: This hook is called just before the hook_app_launch is used and can be useful if you don't want to modify the way applications are being launched (which is advanced usage and can be done by overriding the app_launch hook), but merely want to modify the environment before app launch. You may want to add additional pipeline paths, APIs or other things to the setup, or specify additional scripts etc to run.

linux_path

Type: str

Description: The path to the application executable on Linux.

mac_path

Type: str

Description: The path to the application executable on Mac OS X.

skip_engine_instances

Type: list

Description: A list of string names of engine instances to skip registering Software launcher commands for. For example, a value of ['tk-nukestudio'] for this setting would stop any Software entity launcher commands being registered with the engine that reference the 'tk-nukestudio' engine instance in that environment. This can be used to allow for an engine instance to be configured for a given environment without a launcher existing for it. This is useful in the case of Nuke Studio, where we want to allow for context changes into certain environments, but we only want the application to be launchable from a project environment. This setting only has an impact on Software entity launchers.

extra

Type: dict

Description: Shotgun engine specific extra values. These are defined per Shotgun engine. Please look in the app documentation for more details.

defer_keyword

Type: str

Description: Advanced parameter. This allows for advanced customization around deferred folder creation. Deferred folder creation allows for the creation of partial subfolder structures depending on a specific keyword (see main documentation for details). Before an app is launched, folders are automatically created and by default (e.g. if you leave this setting as null), the launch app will pass the name of the engine as the deferred folder creation keyword. This makes it easy to set up deferred rules in your folder creation config for tk-maya, tk-nuke etc. However, if you for example wanted to set up specific deferred folder structures for Nuke and Nuke X (both running the nuke engine), you need a finer granularity. This setting can then be used to override the default behaviour of just passing the engine name. Instead, you can pass any string into the deferred folder creation (for example 'nuke' and 'nuke_x' in the case above). This parameter is also useful if you want to use deferred folder creation in conjunction with launching of apps which do not have a toolkit engine defined - for these app launch instances, the engine setting is left blank, and therefore no engine name is passed into the deferred folder creation. In such cases you can utilize this parameter to control the deferred folder creation. You can specify multiple keywords using a comma as a delimiter (eg. 'nuke, nuke_x'). This will trigger folder creation for folders in your schema that have any of these values in their deferred folder creation setting.

menu_name

Type: str

Description: Name to appear on the Shotgun menu.

hook_app_launch

Type: hook

Default Value: app_launch

Description: Called to launch the application. This hook contains the code that does the actual execution of the launch command and parameters. If you have a custom launcher system in your studio, it can be handy to override Tank's default launch behaviour.

versions

Type: list

Description: A list of strings that will be used to substitute for the {version} token in the values for the other settings for the instance of this app. For example, a value of ['2012', '2013', '2014'] for this setting and a value of 'Launch Maya {version}' for menu_name would result in the following command menu names being registered: Launch Maya 2012, Launch Maya 2013, Launch Maya 2014. The first version in the list will be considered the 'default' version if the engine running the app supports the concept. You can use pieces of the version if you wrap the parts in parenthesis like ['(7.0)v3', '(8.0)v1']. These pieces of the version string are available in the other settings via the {v0}, {v1}, {v2}, ... replacement tokens.

scan_all_projects

Type: bool

Description: When true, and when use_software_entity is true, launchers will be registered for all projects instead of only the current environment's project.

hook_before_register_command

Type: hook

Default Value: before_register_command

Description: This hook is called just before launcher command registration occurs. it can be used to alter the engine instance name associated with the launcher should that be required. This hook's methods are only called when Software entity launchers are being used.

windows_args

Type: str

Description: The arguments to be passed to application on Windows, as a string.

use_software_entity

Type: bool

Description: Whether to use Shotgun Software Entities to register launch commands for available DCCs.

group_default

Type: bool

Description: Boolean value indicating whether this command should represent the group as a whole. Setting this value to True indicates that this is the command to run and display in applications that show a single button for each named group.

icon

Type: str

Default Value: {target_engine}/icon_256.png

Description: The path to the icon to appear for the application. If the value starts with '{target_engine}' then the remainder of the path will be relative to the root of the engine's install. If the value starts with '{config_path}' then the remainder of the path will be relative to the root of the configuration. The path should use forward slashes which will be replaced with the correct operating system separator when used.

Release Notes

Welcome to the release notes for the Multi Launch App. 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!

v0.10.0

2018-Mar-06

On OS X, we now allow for both .app and unix-style executable launches.

Details:

Removes Flame-specific logic in favor of a generic solution. We now look at what kind of path we're being asked to launch on OS X: if it's a .app application bundle, we use the "open" command, and if it's not we treat it like any other Unix-style executable.

v0.9.15

2017-Dec-04

QA fix to account for flame launch with and without tk integration

v0.9.14

2017-Nov-30

Supplies the engine name to the app launch hooks

v0.9.13

2017-Nov-13

Switch from path detection to env variable check for flame launch

v0.9.12

2017-Nov-10

Updated metrics logging

v0.9.11

2017-Oct-24

Adds additional logic to detect that Flame is being launched via a Software launcher.

v0.9.10

2017-Sep-22

Adds a skip_engine_instances app setting.

Details:

This can be used to allow an engine instance to be configured for a given environment without a launcher existing for it. This is useful in the case of Nuke Studio, where we want to allow for context changes into certain environments, but we only want the application to be launchable from a project environment.

v0.9.9

2017-Sep-19

Ensures that the requested engine instance is configured.

Details:

When the before_register_command hook changes the engine instance name to be used by a launcher, we now ensure that the new engine instance is configured in the current environment before going ahead with the command registration with the engine.

v0.9.8

2017-Sep-18

Bug fix for argument ordering in the single-config-launcher API.

Details:

The single-config-launcher API did not order its arguments properly when launching from a context and/or path. This broke the tk-shotgun-launchpublish app.

v0.9.7

2017-Sep-01

Minor changes needed to allow the tk-shotgun-launchpublish app to support Software entity launchers.

v0.9.6

2017-Aug-22

Adds a new before_register_command hook.

Details:

The default implementation is for the hook method to be a no-op. It is intended to be overridden at the config level when redirecting to an engine instance other than what is set in the associated Software entity. A realistic example would be for Nuke and Nuke Studio. They share a single Software entity in SG, but in classic SGTK project setups Nuke Studio is configured differently than Nuke. In that situation, we need to redirect to a tk-nukestudio engine instance prior to the launcher command being registered with the engine.

v0.9.5

2017-Jul-27

Clears and restores Qt library paths when launching.

Details:

This replaces logic that has now been removed from tk-shell and tk-shotgun. In those implementations, the library paths were always cleared, regardless of OS, and were never restored. That was a bad idea, and caused problems with browser integration and shell launching in some cases.

v0.9.4

2017-Jun-29

Tweaks to debug logging.

v0.9.3

2017-May-17

Minor adjustments to logging output

v0.9.2

2017-May-16

Fixed issue in shotgun version detection check.

v0.9.1

2017-May-16

Incremented minimum required core version

v0.9.0

2017-May-04

Support for software entity based launching.

Details:

• When connected to shotgun 7.2 and above, adds support for the software entity. This is disabled by default and can be turned on via a use_software_entity setting.
• Adds parameters needed for the upcoming websockets integration
• Adds support for better grouping and group defaults. If used, these will propagate to the register command call and will be utilized by engines that implement command grouping.
• Support for automatic software scanning interfaces. Used in conjunction with the software entity, allowing a setup where the launch app reaches out to an engine and requests that the engine reports which software installations are detected on the current machine.

v0.8.2

2017-Mar-15

Removes problematic profiles from png files used as icons.

Details:

This will silence libpng warnings from Qt when the png files are loaded as pixmaps. This is a second attempt as this profile stripping, and uses ImageMagick's "mogrify" command to achieve the desired result, which maintains color consistency.

v0.8.0

2016-Oct-06

Removes Maya 2012/2013 specific SSL patching.

Details:

Support for Maya versions older than 2014 has been deprecated.

v0.7.7

2016-Sep-19

PATH environment variable fixes for 3ds Max 2017 compatibility.

v0.7.6

2016-Apr-12

adds support for version token replacement in args setting

Details:

• This enables clients who use a wrapper to launch their DCC, take advantage of the version tokens in the *_args setting for launching multiple versions of their DCC.

• Removed error when launching from a Task in the Shotgun web application without an associated Pipeline Step. It is completely valid to have a schema that uses Tasks that do not have an associated Pipeline Step. Previously, we would raise an exception when launching from a Task in the Shotgun web UI that had no associated Pipeline Step.

v0.7.5

2016-Apr-11

(NOT RELEASED) Removed error when launching from a Task in the Shotgun web application without an associated Pipeline Step

v0.7.4

2016-Apr-08

(NOT RELEASED) adds support for version token replacement in args setting

v0.7.3

2016-Feb-29

Remove warning about missing version tokens in menu

Details:

• Previously when you specified versions in your launcher instance settings, but didn't use any version tokens in the instance menu name, a warning would be emitted: . This warning was misleading and unnecessary. So we've now removed it altogether.
• Updated docs regarding using multiple defer_keywords

v0.7.2

Cleans up the bootstrap module after launch.

Details:

After a "generic" bootstrap operation is performed, the bootstrap module that was imported is removed from sys.modules. This allows subsequent launches that make use of a bootstrap module to function properly.

v0.7.1

Rearranges bootstrapping logic to fix bootstrapping for some engines.

Details:

Some engines have a bootstrap.py file included in their structure, but aren't setup for those to be fully standalone. In those cases, we need to let the launchapp bootstrapping code specific to that engine to run rather than relying on the generic bootstrapping behavior to handle everything.

v0.7.0

Favors bootstrap routines provided by the engine over those contained in the app.

Details:

If the engine contains bootstrapping logic it will be used. If it does not then launchapp will fall back on its internal logic.

v0.6.7

2015-Nov-04

Improved error message when flame is not found.

v0.6.6

app_path, app_args, and version parameters passed to both hooks

Details:

The before_app_launch hook now gets the same parameters as the app_launch hook which means you have access to the path of the application being launched and any arguments passed in. Also added a version parameter which will contain the version being launched if it was defined in the 'versions' setting in the Launcher instance (otherwise this will be None).

v0.6.5

add additional tokens to specify parts of the version string

Details:

Allows defining groups in the version string using ()s. You can then reference them in order as tokens in the icon, *_path, and menu_name settings. For example, if the version setting is ["(9.0)v4(beta1)"], the resulting available tokens would be:

{version}: "9.0v4beta1"
{v0}: "9.0"
{v1}: "beta1"

v0.6.4

Updated signature for the generic engine boostrap call.

v0.6.3

Pass multi-launchapp instance to the generic bootstrap.

v0.6.2

improved error when trying to run 3dsmax 2015 with the old tk-3dsmax engine

Details:

3dsmax 2015 requires the newer tk-3dsmaxplus engine to run. However, users may upgrade from older versions of 3dsmax and not realize this. Previously when doing so, they would get an unhelpful error message when the bootstrap script attempted to run on startup. This change catches the error at that point and displays a dialog explaining the need to use the newer tk-3dsmaxplus engine instead.

v0.6.1

App now backups the environment variables before launching an app and restores them afterwards.

Details:

sys.path and os.environ are now backed up before any app launch and restored after so that one app's launch environment can't leak into another's.

v0.6.0

Added generic engine launch logic so new engines do not need to modify this app.

v0.5.4

Documentation Update

v0.5.3

Update the project python bootstrap to reset PATH

Details:

Make sure applications are launched with the proper DllDirectory set.

v0.5.2

Minor adjustments to the Flame bootstrap sequence.

Details:

This changes the way the Flame family is being launched so that it gains greater control over the boostrap and launch process. The actual executable argument is being sent in to Flame so that this can be re-written by the engine at runtime, effectively allowing the Flame engine to run the DCC launch through its own wrapper script. This is to ensure that a particular environment is being set up where all library dependencies are working etc.

v0.5.0

Added support for the Flame Engine.

v0.4.1

Added support for the new 3DS Max Engine supporting MaxPlus and Max version 2015.

v0.4.0

Added support for launching Mari

v0.3.1

Improved error messaging when an application cannot be launched.

v0.3.0

Added a 'defer_keyword' parameter to support some advanced use cases.

Details:

This adds a new manifest parameter called 'defer_keyword'. Here is the manifest description: Advanced parameter. This allows for advanced customization around deferred folder creation. Deferred folder creation allows for the creation of partial subfolder structures depending on a specific keyword (see main documentation for details). Before an app is launched, folders are automatically created and by default (e.g. if you leave this setting as null), the launch app will pass the name of the engine as the deferred folder creation keyword. This makes it easy to set up deferred rules in your folder creation config for tk-maya, tk-nuke etc. However, if you for example wanted to set up specific deferred folder structures for Nuke and Nuke X (both running the nuke engine), you need a finer granularity. This setting can then be used to override the default behaviour of just passing the engine name. Instead, you can pass any string into the deferred folder creation (for example 'nuke' and 'nuke_x' in the case above). This parameter is also useful if you want to use deferred folder creation in conjunction with launching of apps which do not have a toolkit engine defined - for these app launch instances, the engine setting is left blank, and therefore no engine name is passed into the deferred folder creation. In such cases you can utilize this parameter to control the deferred folder creation.

v0.3.0

Added a 'defer_keyword' parameter to support some advanced use cases.

Details:

This adds a new manifest parameter called 'defer_keyword'. Here is the manifest description:

v0.2.19

Relaxed the error catching for the icon setting.

Details: Relaxed throwing an error if the icon is set to a '{target_engine}' replacement string even if the engine setting is empty.

v0.2.18

Support for the icon and versions settings.

Details: Added two new settings, "icon" and "versions". The icon can be used to define an icon that should be registered for the command if the engine has support for icons. The versions setting is shorthand for defining multiple applications where the only difference between the configurations is the version of the application being launched.

v0.2.17

Event log statistics now also tracks the core API version.

v0.2.16

Support for renamed env vars for photoshop engine.

Details: Added support for latest photoshop engine. Added readme for building linux Softimage dependencies. 3dsMax bootstrap handles _blurLibrary not being defined.

v0.2.15

Improved Softimage launching on Linux

v0.2.14

Fixed a bug that would cause launching to fail for 3dsMax and Motionbuilder

v0.2.13

Added ability to launch applications not yet integrated with Toolkit.

v0.2.12

Updated minimum required core version to v0.14.0

v0.2.11

Better support for review versions.

v0.2.10

Added logic for handling launching from review versions.

v0.2.9

Updated Softimage support

v0.2.8

Added exceptions for softimage.

v0.2.7

Houdini is not supported on osx due to Qt compatibility issues.

Details: Houdini is not supported on osx due to Qt compatibility issues.

v0.2.6

Added Houdini and ability to open hiero projects at application startup.

v0.2.5

Renames and support for the new name Sgtk.

v0.2.4

Added experimental support for launching softimage.

v0.2.3

Added a check so that Tasks that are missing steps cannot be launched from when launching from inside Shotgun.

v0.2.2

Adjustments to context handling and folder creation.

Details:

• The context is now serialized and passed from the app into the booting application
• Now correctly handles setups which are not task or file based
• Added new interfaces for better preserving context state when launching from a publish

v0.2.1

Adjustments to context handling and folder creation.

Details: - The context is now serialized and passed from the app into the booting application. This means that any context can be transferred into a launching app. Previously there were some built in restrictions as to what was possible to pass. - Added a pre launch hook for easy addition of environment variables to the launch.

v0.2.0

Bug fixes and preparation for v0.13

Details: - adjusted launch code for hiero to work with latest version of hiero - fixed a bug where opening nuke via a nuke file wasn't working - general prep for v0.13 - improved command metadata - polish on certain error messages

v0.1.0

Added documentation.

v0.0.2

Fixed issues with launching 3dsmax, removed the platforms parameter from the configs.

v0.0.1

Initial Release to the Tank Store.