ShotGrid Engine for VRED

ShotGrid Integration for VRED
Latest Version: v2.1.0 (prod)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-vred

Please Note: This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations User Guide for more details.
Overview Summary
      Information for App Developers
            VRED Project Management
      Working with tk-vred
                  File Open and Save
                  Scene Breakdown
Installation, Updates and Development
Configuration Options
Release Notes History

The Shotgun engine for the VRED product family establishes a bridge between the Shotgun Pipeline Toolkit apps and VRED. This engine communicates to VRED through the VRED python API. Once installed, it allows you to run the same apps that you have in Maya, Nuke, Photoshop and other applications.

Supported Application Versions

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


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

Information for App Developers


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

VRED Project Management

Whenever the Shotgun engine for VRED starts, it will set the VRED 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 VRED project is set based on a file can be configured in the configuration file, using the template system.

Working with tk-vred

This Shotgun integration supports the VRED product family (Pro & Design).

When VRED opens, a Shotgun menu (the VRED engine) is added to the menu bar.

File Open and Save

Use the My Tasks and Assets tabs to see all your assigned tasks and browse for assets. To the right, use these tabs to view all files, working or published files associated with what is selected to the left.


Snapshot: Opens the Snapshot dialog to create a quick backup of the current scene.


Publish: Opens the Publish dialog for publishing the file to Shotgun, which can then be used by artists downstream. For more information on VRED Publishing, see here


Load: Opens the Content Loader app, along with instructional slides explaining how it works. To see more info about VRED loading see here

Scene Breakdown

Scene Breakdown: Opens the Breakdown dialog, which displays a list of "referenced" files (and their links), along with what in the scene is out-of-date. Select one or more items and click Update Selected to switch and use the latest version of the content.

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

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

Special Requirements

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

Description: Template to use to determine where to set the VRED render images. This should be a string specifying the template to use but can also be empty if you do not wish the VRED render path to be automatically set.


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


Type: int

Default Value: 2022

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 recommended that you set this value to the current major version + 1.


Type: list

Default Value: ['VRED Scene', 'Alias File', 'Catpart File', 'Jt File', 'Igs File']

Description: A list of PublishedFileTypes that are allowed for review with VRED.

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!


  • Renames Shotgun to ShotGrid.


Fixed Bugs

  • [SHOT-3754] - Opening the shotgun panel for the second time crashes VRED.
  • [SHOT-3758] - SG Panel actions are missing.


Fixed Bugs

  • [SHOT-3618] - VRED Shotgun menu still remains even if the engine failed to reload.
  • [SHOT-3673] - "Couldn't get reference node" error after first update with Scene Breakdown2 in VRED.


  • [SHOT-3742] - VRED 2022 support for tk-vred engine.
  • [SHOT-3485] - Added action to "Create Smart Ref" from vpb file in VRED Load.
  • [SHOT-3608] - VRED presenter review workflow: have SG panel focused on version selected.
  • [SHOT-3662] - Added support for Smart Reference in VRED Scene Breakdown.
  • [SHOT-3663] - Aligned VRED Scene Breakdown with VRED Reference Editor behavior.
  • [SHOT-3665] - Added the "Create Smart Reference" option to SG Panel.
  • [SHOT-3666] - Added the "Import sceneplate" action to SG Panel.
  • [SHOT-3700] - Removed File Format in Version Name to reduce confusion.
  • [SHOT-3559] - Disabled the Close Button on Shotgun Panel.


Fixed Bugs

  • [SHOT-3580] - VRED processes not dying after exiting when launched via Shotgun
  • [SHOT-3591] - VRED launchers not found by Shotgun Desktop on certain versions of Windows
  • [SHOT-3610] - VRED v2020.x versions not properly loading Shotgun engine


Refactor of tk-vred engine structure, support for Qt & PySide2 v5.15 and addition of "Review with VRED" high quality review workflow.

Fixed Bugs

  • [SHOT-3423] - VRED Shotgun Panel & Python Console now has the "Shotgun" name in the tab title
  • [SHOT-3502] - Shotgun will now prompt the user to save when there are unsaved changes when opening or creating a new VRED file. Dependent on tk-multi-workfiles2 v0.12.4


  • [SHOT-3345] - Show a warning that this version of VRED isn't fully tested with Shotgun
  • [SHOT-3543] - Shotgun now has a Toolkit Action for "Review in VRED" to review VRED scenes with VRED Presenter. Read the official documentation here
  • [SHOT-3542] - Support Launching VRED Presenter in tk-vred in startup.py
  • [SHOT-3445] - The VRED Plugin now shows information about the Shotgun integration
  • [SHOT-3508] - Support for PySide2 v5.15



  • [SHOT-3349] The Scene Breakdown will no longer remove VRED clones when updating published files


Fixed Bugs

  • [SHOT-3340] Fixed having two Load items in the Shotgun menu for VRED
  • [SHOT-3351] Fixed the "reload engine and apps" function in VRED


  • [SHOT-3297] Launch Shotgun Panel on Startup of Alias and VRED in Basic Config
  • [SHOT-2423] Dock the Shotgun Panel in VRED
  • [SHOT-3314] Small improvements to prevent VRED from crashing on closing


Official Support for VRED 2021 and Python 3. Requires at least tk-multi-publish2 v2.5.0

Fixed Bugs

  • Added support for the existing VRED_SCRIPT_PLUGINS environment variable if it is set.
  • Fixed a bug when VRED is launched into a Task context via bootstrapping.


  • Added launch_at_startup for tk-multi-workfiles2 in VRED.


Improve Scene Breakdown behavior to respect the existing scene

Important Notes:

  • Adding LMV will require a new framework tk-framework-lmv.
  • Creating a 3D Version from VRED will now use the sg_uploaded_movie field. If you are using the legacy 3D - viewer you will need to modify the field name to continue using it.
  • Upgrading to this engine version will require tk-core version of at least 19.3.


  • Add VRED Publish hook that creates a Version that can be 3D or 2D with a boolean flag.

Fixed Bugs

  • Respect VRED Grouping during Scene Breakdown update.
  • Remove recursive transformation in scene_operations.py during Scene Breakdown Update.


Fixed Bugs

  • Be sure to create the render folder when setting up the render path and remove the render_path attribute.
  • "Import VRED scene" doesn't have the expected behavior.
  • Publish Menu in VRED is displayed as submenu.
  • Remove tk-framework-locking from engine dependencies.


  • Clean hook to remove unused "Load" action.
  • Improve the way to set render path in VRED.
  • Improve publish workflow for VRED renders.
  • Clean the OSB publish plugin in VRED.
  • Add start_version_control publish plugin to VRED engine.
  • Examine all publish_plugins for VRED.
  • Remove LMV translation in vred publish process.
  • Move the collector logic from tk-config to tk-vred engine.
  • Remove old plugin which is not used anymore (replaced by vred_publish_file_osb.py).
  • Get the render path in a more cleaner way and move the template logic to the method which set the render path.
  • Clean hook to remove unused actions in tk-multi-loader2 app.
  • Add new hook to deal with VRED actions in Shotgun Panel.


Fixed bugs

  • Fixed a bug with the plugin in 2020.2. VRED was crashing in the launch step because the engine was starting before the bootstrap process had completed.

  • Fixed a bug with Shotgun menu. It was not loading when VRED language was switched to Japanese/Chinese.


Whats New:

Overall cleanup of the engine code to maintain toolkit standards and make public.


  • Make tk-framework-locking an optional dependency
  • Removed the about app and created software_credits files in each app/engine/framework repo
  • Change hooks from tk-multi-breakdown, tk-multi-loader2, tk-multi-snapshot, tk-multi-workfiles2 and tk-multi-shotgunpanel to match existing Shotgun tk-default-config2 hook structure
  • Remove unnecessary code in hooks
  • Add custom exception for errors
  • Move common operations from engine to tk_vred/operations.py
  • Implemented dynamic Shotgun menu loading
  • Improved popup notification when loading in multiple files from the Loader
  • Removed vred_bootstrap.py and migrated all requirements (ex. SHOTGUN_ENABLE, VRED_SCRIPT_PLUGINS) to startup.py script
  • Remove the unnecessary pyside folder from resources
  • Replace tank command with the newer sgtk command
  • Move icons to an official icons folder
  • Replace product token with code_name token
  • Add sg_uploaded_movie for each Version from Publisher via VRED
  • Remove hard coded path for VRED to access LMV translator

Fixed Bugs:

Fixed a bug where if you created a scene from a CustomEntity, the Shotgun components would not load correctly.


First release of VRED engine.