Shotgun Engine for Flame

Shotgun Integration in Flame

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


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 Flame creates a bridge between the various integration hooks that are available as of Flame 2015 Extension 2, and acts as a host for executing Toolkit Flame apps.

Supported Application Versions

This item has been tested and is known to be working on the following application versions: 2016+. 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.


In-depth Technical Walkthrough

The best starting point if you want to install and start using the Flame integration is probably our Technical Walkthrough Videos. Below, you find a playlist with several videos, showing step by step how to install the Shotgun Desktop, set up a project and then run the Flame integration.

The last section contains more technical in-depth information about configuration and hooks. If you watch all of the videos, you should hopefully have a good sense of what the Flame integration can do and how you can connect it to the rest of your pipeline.


The Shotgun engine for Flame relies on new integration hooks that were added in Flame 2015 Extension 2. This version of Flame must be used in order for the engine to function. For more info on Flame 2015 Extension 2 (including how to get it), reach out to Flame Support.

The simplest way to get started with the Shotgun engine for Flame is to set up a new test project with our example pipeline configuration. You can do this by launching the Shotgun Desktop, running the Project Setup for a new project and choosing the default Flame configuration (in the default configurations section).

Flame Project Setup

The Shotgun engine for Flame also helps associate the Shotgun project with a Flame project, and creates it if need be. This is key to the integration, as it ensures data from Flame gets associated with the right things in Shotgun. As an added feature, the engine provides functionality for managing the naming conventions of Flame projects as well as the other various settings for the project.

When Flame is launched via Shotgun for the first time, a Flame project creation UI will appear that lets the artist edit the usual settings from the standard Flame project creation screen:

But with the Shotgun integration, the settings can be pre-populated with pipeline-friendly values, helping artists quickly get the right thing without having to think about it. The defaults can be customized via the project_setup_hook, which supports the following options:

use_project_settings_ui If set to True, the project creation UI will appear. If False, the Flame project will automatically be created based on the rest of the defaults in the hook.

get_server_hostname By default this is set to 'localhost', but it can be overridden if desired.

get_project_name By default this is set to the same value as the Shotgun project, but it can be overridden if desired.

get_volume By default this is set to the first available storage, but it can be overridden if desired.

get_workspace By default Flame will create a default workspace according to its standard workspace creation logic, but it can be overridden if desired.

get_user This will try to associate the user logged into the Flame machine with a user in Shotgun.

get_project_settings This is where the main Flame settings are configured and the hook helps build the Flame project XML stream. The following parameters must be supplied:

  • FrameWidth (e.g. 1280)
  • FrameHeight (e.g. 1080)
  • FrameDepth (16-bit fp, 12-bit, 12-bit u, 10-bit, 8-bit)
  • FieldDominance (PROGRESSIVE, FIELD_1, FIELD_2)
  • AspectRatio (4:3, 16:9, or floating point value as string)

Proxy settings can also be supplied. For more info, see the Autodesk Wiretap SDK docs!

To view the entire codebase for the project_setup hook, please see our Github repo for the engine.

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-flame

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

Special Requirements

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


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.


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 flame starts up. If name is '' then all commands from the given app instance are started.


Type: list

Description: Controls the commands that show up in Flame's context menu. This is a list where each element is a dictionary with three keys: 'app_instance', 'name' and 'display_name'. The app_instance value connects this entry to a particular app instance defined in the environment configuration file. The name value is name of the registered command in the engine. The display_name value is the name that Flame should show in the menu. If name is '' then all commands from the given app instance are started. If display_name is not present, name will be used instead


Type: str

Description: Comma separated list of servers to use when submitting a backburner job. (Ignored if a group is used)


Type: tank_type

Default Value: Flame Batch File

Description: The publish type associated with Flame batch scripts. This parameter is used to help the Flare launch process auto-load a batch script from Shotgun at startup.


Type: str

Description: The group name of the servers to use when submitting a backburner job.


Type: str

Default Value: /tmp

Description: A folder where the Flame engine can put temporary files. This folder needs to be accessible from all backburner nodes, so if you are running a larger backburner setup, this path must be some sort of shared network location.


Type: hook

Default Value: {self}/project_startup.py

Description: Contains the logic for determining and creating the workspace and users to use when launching into a Flame project.


Type: bool

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


Type: bool

Description: Whether to prepare the launch of Flame to make use of its builtin Toolkit plugin or not. If false, the classic-style Toolkit integration will be initialized when Flame is launched.


Type: str

Description: The host where the backburner manager is located. All backburner jobs generated by the flame engine will be dispatched to this server. This setting is only supported on Flame 2016.1 and above. If this value is not specified, the system default will be used.


Type: bool

Description: Hint about the possibility to switch project

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!



Adds legacy/classic startup logic for Software launchers.



Add a possibility to specify the backburner servers/group used on job submission



Bug fix: Unregister tk-flame hooks on engine destruction



Add a possibility to specify the backburner servers/group used on job submission


New tk-flame configuration entry available: backburner_servers and backburner_server_group.



Fix Flame executable detection on Mac OS



Add launch context to the FlameLauncher



Better error handling on log file



Improve Version Checking



Adds software scan support for mac update releases. Fixes logging permissions issues.



Adds automatic software scanning logic and interfaces.



Fix Shot Export on Mac and RHEL6 for flame 2016 and 2017



Fix Shotgun Shot Export for flame 2016.1 to 2017.2



Added menu ordering in the shotgun main menu



Added setup directory and group selection in project creation UI.



Fix python hook crash when user implement their own version of the preCustomExport python hook.



Support remote Backburner Manager when submitting clip to review with toolkit as a plugin.



Ensures that Backburner reads Toolkit settings and writes logs in the home folder.



A series of tweaks and fixes to allow the flame engine to be packaged in a plugin.



Updated Flame icons and adding validation to see if Shotgun is disabled



Renamed some of the hook files for better compatibility when running shotgun alongside other integrations.



Registered commands now automatically appear on the menu.



Added support for 2016 export preset paths.



Added export_presets_root convenience property.



Added support for non-launchapp init of the engine.



Engine now reports upgraded export presets for Flame 2017.



Updated to support more flexible install paths



Compatibility adjustments to Flame 2017 preset logic.



Now supports profile presets for Flame 2017. Increased backburner timeout to 600 minutes.



moved version logging to engine post app init



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



Support for proxy settings introduced in Flame 2016 Extension 1. Ability to run flame batch from a shot.



Added support for exposing Toolkit commands via the Flame context menu.



Flame user names are now based on the full flame version number.



Updated to support Flame 2016 Extension 1


  • Updated flame export preset version to 6 for 2016.1 and above
  • Added support for a backburner manager parameter for 2016.1 and above. Adds a new parameter to the engine configuration which means the the Shotgun/Flame integration now supports remote render farms. This change required some internal bug fixes in Flame, so the new config option will be ignored on versions prior to 2016.1



Add ability to run configured apps on Flame launch


Fixed a Flame issue when having a space in the Pipeline Configuration and Primary paths


Minor polish and improvements.


Improved logging, documentation and general code structure.


Improved error logging.


Fixed an issue causing project creation to fail in Flame v2015.2


Improved default creation of user names.


The hook that generates user names has been improved to include the major version of Flame. This is to ensure that the Shotgun integration can gracefully handle switches between major versions in flame, since user accounts can be incompatible between releases.


Added support for visual depth in the project settings hook. Defaults to 16 bit.


FPS Support and compatibility changes.


  • Frame rate (FPS) is now supported by the project UI and project setup hook.
  • Removed a method which was returning misleading frame defaults.
  • Added a method to detect which xml preset version that the DCC expects.

Note! This release changes the behaviour around how in/out frame numbers are normalized prior to being pushed to shotgun. Previously, the integration tried to normalize frame values in Flame that had been offset by an internal flame setting (usually set to 10:00:00.00) but this is no longer the case. Instead, the values in Shotgun will appear exactly the way they appear in the conform view in Flame.


The Shotgun Flame integration updated for Flame compatibility.

  • Improved python detection for backburner jobs
  • Improved support for detection of flame version numbers


Improved support for partial flame version numbers.


Added additional checks to make sure the executable exists.


Updated Flame compatibility.


Fixed a bug which caused backburner jobs to fail for sequences with very long names.


Misc minor adjustments and fixes.

  • Fixed an issue causing Flame to fail to launch on linux if a system install of PySide was present.
  • Added logging to file and improved exception handling in UIs showing up outside Flame.
  • Added the ability to choose volume interactively at project setup.
  • Added better version checks at startup to ensure a minimum version (2015.2) of Flame is being used.


UI Polish and tweaks.


First official release of the Shotgun Flame integration.



  • 0

    This is great work - all very positive so far - and the possibilities are just unfolding before our eyes.

    We are slowly working our way through what is possible and you've already made a lot of stuff possible.

    Very very interesting work - thankyou - please keep it up.

    Phil & Ozgur in Istanbul...

  • 0

    i'm about to upgrade a flame from 2017.0.1 to 2017.1.

    the upgrade from 2017.0.1 to 2017.1 means that flame projects get converted to be compatible with the new software and also get renamed from "project-name" to "project-name_2017_1"

    if i do this, how will shotgun desktop integration know which project to open?


Please sign in to leave a comment.