Maya

Shotgun Engine for Maya

Shotgun Integration in Maya


By: Shotgun Software
Latest Version: v0.8.0 (prod)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-maya

Overview

This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations Admin Guide for details. The Shotgun engine for Maya establishes a bridge between the Shotgun Pipeline Toolkit apps and Maya. It also contains a PySide distribution, which is designed to connect to the QT inside of Maya, making it possible to write apps using Python and PySide that run right inside the engine.

Supported Application Versions

This item has been tested and is known to be working on the following application versions: 2014-2017. Please note that it is perfectly possible, even likely, that it will work with more recent releases, however it has not yet been formally tested with these versions.

Overview Video

The following video gives a quick overview of features and functionality.

Documentation

The Shotgun engine for Maya contains a standard platform for integrating Shotgun Apps into Maya. It is lightweight and straight forward and adds a Shotgun menu to the Maya menu.

Maya Menu

Information for App Developers

PySide

The Shotgun engine for Maya contains a PySide installation, and will activate this whenever this is necessary.

Maya Project Management

Whenever the Shotgun engine for Maya starts, it will set the Maya Project to point at a location defined in the settings for this engine. This means that the Project may also change when a new file is opened. The details relating to how the maya project is set based on a file can be configured in the configuration file, using the template system.

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:

> tank Project XYZ install_engine asset tk-maya

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-maya.

Special Requirements

  • You need Shotgun Pipeline Toolkit Core API version v0.18.8 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 Maya engine starts up. If name is '' then all commands from the given app instance are started.

template_project

Type: template

Description: Template to use to determine where to set the maya project location. This should be a string specifying the template to use but can also be empty if you do not wish the Maya project to be automatically set.

use_sgtk_as_menu_name

Type: bool

Description: Optionally choose to use 'Sgtk' as the primary menu name instead of 'Shotgun'

launch_builtin_plugins

Type: list

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

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.

compatibility_dialog_min_version

Type: int

Default Value: 2015

Description: Specify the minimum Application major version that will prompt a warning if it isn't yet fully supported and tested with Toolkit. To disable the warning dialog for the version you are testing, it is recomended that you set this value to the current major version + 1.

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.

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!

v0.8.0

2017-May-03

Adds plugin, software scanning and 0.18 logging implementation.

v0.7.16

2017-Feb-02

Fix an error when opening Shotgun panel twice in Maya 2017.

v0.7.14

2017-Jan-18

Fix Shotgun app panel restoring and sizing issues in Maya 2017.

Details:

  • When the engine is started, restore the persisted Shotgun app panels into their Maya workspace controls in the active Maya 2017 workspace.
  • When a Shotgun app panel is embedded into a Maya workspace control tab, give a minimum width to this workspace control.

v0.7.11

2016-Dec-16

Capture and recall Maya engine panel state in Maya 2017.

Details:

The opened Shotgun app panels docked in a Maya 2017 workspace are restored to their saved locations:

  • when the user switches back to this workspace after displaying another workspace,
  • after restarting Maya, when the tk-maya engine is rebooted and the Shotgun app panels are recreated.

When switching from one workspace to another, the opened Shotgun app panels retain their current UI states.

v0.7.9

2016-Dec-06

'Jump to File System' available only when there are some file system locations.

Details:

Add Shotgun context menu item 'Jump to File System' only when there are some file system locations.

v0.7.8

2016-Nov-30

Recreates Maya event handler and resets the Maya project when changing context.

v0.7.7

2016-Nov-24

Update Maya version compatibility to include 2017

v0.7.6

2016-Nov-16

Add a method to close windows opened by the engine.

v0.7.5

2016-Nov-14

Uses on-the-fly context changing for Maya-event-driven context changes.

v0.7.4

2016-Nov-02

Adds basic support for on-the-fly context changes.

v0.7.3

2016-Oct-20

Dock Shotgun app panels in the Channel Box area in Maya 2017.

v0.7.2

2016-Oct-19

Dock Shotgun app panels in the Channel Box area in Maya 2017.

v0.7.1

2016-Oct-05

Adds a sane error message when attempting to use the engine with Maya 2012 or 2013.

v0.7.0

2016-Oct-04

Removes support for Maya 2012 and Maya 2013.

v0.6.1

2016-Sep-15

An undocked toolkit panel is no more deleted when relaunching it.

v0.6.0

2016-Aug-11

Added option to turn off automatic context switching.

v0.5.10

2016-Jul-28

Add the ability to run a series of app instance commands at engine startup.

Details:

When the engine starts up, it will run the series of app instance commands listed in the new 'run_at_startup' setting of the environment configuration file.

For example, adding the following configuration setting will make the engine launch the Shotgun panel automatically:

run_at_startup:
  - {app_instance: tk-multi-shotgunpanel, name: ''}

File 'info.yml' provides more information about 'run_at_startup' setting.

v0.5.9

2016-Jul-27

Preliminary release for Maya 2017

Details:

This is the first release of the Maya engine for Maya 2017. It supports all our applications, but there are still some issues with the Publish tool and the Shotgun Panel.

v0.5.8

2016-Jul-20

Docked panels are now raised upon creation or activation.

Details:

When docking an app widget in a Maya panel, the docked panel window is raised to the top dock tab.

v0.5.7

2016-Jul-18

Adds support for Maya 2017.

Details:

This release adds support for Maya 2017. Note that it requires core v0.18.8 or above.

v0.5.6

2016-Jun-30

Engine now supports a site context.

v0.5.5

2016-Feb-18

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

v0.5.4

2015-Nov-27

Logging using engine.log_* is no longer blocking.

Details:

A deadlock would occur when a background thread was logging through the engine's log methods while the main thread was waiting for the background thread to complete.

Note that this fix requires Core API 0.16.35.

v0.5.3

2015-Nov-23

Tweaked panel implementation to be core compliant

v0.5.2

2015-Aug-13

Replaced evalDeferred with a single-shot QTimer to avoid issue where evalDeferred callback was being executed multiple times

Details:

  • In certain situations, a callback executed through evalDeferred was run a second time, possibly from the event loop of the modal dialog that the first execution created.
  • This change avoids this situation which was leading to instability

v0.5.1

Added panel support

Details:

This implements the standard toolkit panel interface and allows Toolkit apps to dock themselves into the Maya user interface.

v0.4.7

Updated logging to always run on the main thread

v0.4.6

Update Maya version compatibility to include 2016

v0.4.5

Add support for unicode characters in Shotgun menu labels

v0.4.4

Fixed issue when running Maya in batch mode

Details:

  • The engine no longer attempts to create/remove menus when Maya is running in batch mode

v0.4.3

Fixed issue causing Unicode characters to display incorrectly in app UIs

Details:

When unicode characters are used in fields that get displayed in the UI of apps in Maya, they are now correctly displayed as the intended characters rather than incoherent glyphs.

v0.4.2

Removed deprecated queue interface.

Details: This update removes the queue interface which was deprecated in Jaunary 2013. If any of the apps you use are still relying on these interfaces, please do not go ahead with this update but instead email us on toolkitsupport@shotgunsoftware.com.

v0.4.1

Added support for Maya 2015.

Details: - Maya 2015 is now officially supported by Toolkit. - Unsupported versions no longer cause Toolkit not to load but instead present a warning to the user. - Added a setting to allow Toolkit to be used with future unsupported versions if needed.

v0.4.0

Added a new version of PySide, targeting Maya 2013 on Windows x64.

Details: This resolves some instability issues which were observed with the previous version of PySide that was used. Before, the same version of PySide was used for both Maya 2012 and 2013 on Windows. This release adds a specific version of the PySide binaries which specifically targets Maya 2013.

v0.3.10

Now starts up properly with maya 2014 service packs.

v0.3.9

Minor adjustments to how the menu items are sorted.

v0.3.8

Tweak to Shotgun menu: Items in app sub menus are now sorted alphabetically.

v0.3.7

Improvements to the Toolkit dialog & widget management

Details:

  • Dialogs created with show_modal & show_dialog are now released correctly when closed.
  • Updated to require core v0.14.23

v0.3.6

Added timing information in debug log messages

v0.3.5

Updated Engine Icon.

v0.3.4

Renames and support for the new name Sgtk.

v0.3.3

Renames and support for the new name Sgtk.

v0.3.2

Fixed a crash bug when running a command from the Tank menu that results in the engine being restarted under Linux

v0.3.1

Added support for Maya 2014.

v0.3.0

Added support for Maya 2014.

v0.2.7

Better error messages if UIs are launched when Maya runs in batch mode.

v0.2.6

menu hierarchies for tank registered commands are now supported in the Maya engine

v0.2.5

Uses new API methods for file system access.

v0.2.4

QT windows are now correctly parented to maya.

Details:

  • Included pyside shiboken module in pyside distro
  • QT windows are now properly parented to the main window in maya when the tank engine dialog methods are used
  • Adjusted a command to open urls to use QT rather than mayas native url open command since this fails on some linux setups.

v0.2.3

Fixed a bug which caused the engine to be initialized over and over again

v0.2.2

Misc compatibility tweaks

Details:

  • Now uses the Tank QT foundation
  • Added deprecation messages for the engine queue
  • Updated manifest to require core v0.12.5
  • Work area parmaeter can now be left out, in that case, the maya project is not set.

v0.2.1

Added support for code reload.

v0.2.0

PySide, Windows Bug fixes and new menu handling.

This release contains several major changes and enables new functionality for Apps.

  • The engine now comes bundled with PySide, allowing Apps to use QT for UIs and integration.
  • We have included a Maya patch which resolves the issue with delays at startup when Tank was connecting to a hosted Shotgun.

  • The menu has been reorganized and improved.

v0.1.0

First Release with the new Tank API.

v0.0.1

Initial release to the App Store.

Follow

2 Comments

  • 1
    Avatar
    Adam Benson

    What I'm finding with most of Shotgun's documentation is lots of descriptions about WHAT can be done, but virtually no information on HOW it's supposed to be done.  Without the HOW all of the documentation is useless.
    In this particular case, the Maya Project Settings are said to be part of some Template, and yet no listing of WHERE that template might be, or examples of HOW that template should be setup exist.

  • 0
    Avatar
    Mawusime Blewuada

    Installing the Maya Engine v0.7.11 doesn't include a PySide installation.

Please sign in to leave a comment.