Overview
The Toolkit classic configuration has been revamped and released as a new github repository called tk-config-default2. This configuration is now the default configuration when doing the Advanced Project Setup in Shotgun Desktop. The goal of this article is to help answer common questions raised by those familiar with the patterns established by the legacy Toolkit configuration. As always, if you have additional questions, please let us know at support@shotgunsoftware.com.
What are the main differences between the old default configuration and this new one?
The new default configuration has been reorganized based on client feedback and observation to help maximize efficiency when needing to manually curate your production environments. It is designed to eliminate the number of files that need to be modified when making common edits to your configuration. An overview of the structure of the new environment files can be found here.
There are a few structural components of the new configuration that should help administrators understand what has changed:
- Location descriptors for apps, engines, and frameworks now exist in only one place in the configuration. In the legacy configuration, to update the version of an app or engine, changes would need to be made in each of the top-level environment files. All app and engine definitions now include the location descriptors from a single place. These bundle descriptor files can be found in env/includes:
- app_locations.yml # All app location descriptors defined here
- engine_locations.yml # All engine location descriptors defined here
- frameworks.yml # All frameworks defined here
- All engine-specific and app-specific settings are defined in files dedicated to that app or engine. In the legacy configuration, each top-level environment file defined the settings for all the engines and apps. With the new structure, the environment files include engine configuration from engine-specific settings files. The engine settings files then include app-specific settings. This isolates all of the various engine and app settings making it much simpler to determine where to update an engine or app (i.e. go to the engine or app settings file!). For example, in order to change how Maya is configured across all environments, you would edit env/includes/settings/tk-maya.yml. To change how the Publisher is configured in multiple environments, you would modify env/includes/settings/tk-multi-publish2.yml.
- Within these app/engine settings files, multiple configurations exist for that app/engine. Each variation of the settings is included by a different environment and is named in a way to make it easy to know which collection of settings correspond to which environment. For example, the settings.tk-maya.asset_step settings in tk-maya.yml define the maya engine settings for the asset_step environment. Similarly, the settings.tk-multi-publish2.nuke.shot_step settings in tk-multi-publish2.yml define the publisher settings for nuke in the shot_step environment.
- Outside of the environment refactoring, the other major change to the configuration is the upgrade from the legacy tk-multi-publish app to the new tk-multi-publish2 app. The new Publisher supports standalone publishing workflows and has been updated in conjunction with the new configuration to add support for classic template-based workflows. For more information on the new publisher, see the Integrations User Guide or the Integrations Developer Guide.
It should be noted that, for the most part, the core schema and templates remain largely unchanged in this new configuration. The bulk of the changes made involve the structure and organization of the environment files and their included settings.
How do I modify settings for an Engine?
Engine settings are isolated in a settings file that defines configurations of that engine across all environments. For example, the file env/includes/settings/tk-maya.yml defines all Maya configurations used by all environments. Here's a snippet showing the Maya settings for the project environment:
settings.tk-maya.asset_step:
apps:
tk-multi-about:
location: "@apps.tk-multi-about.location"
tk-multi-breakdown:
location: "@apps.tk-multi-breakdown.location"
tk-multi-loader2: "@settings.tk-multi-loader2.maya"
tk-multi-publish2: "@settings.tk-multi-publish2.maya.asset_step"
tk-multi-screeningroom: "@settings.tk-multi-screeningroom.rv"
tk-multi-shotgunpanel: "@settings.tk-multi-shotgunpanel.maya"
tk-multi-snapshot: "@settings.tk-multi-snapshot.maya.asset_step"
tk-multi-workfiles2: "@settings.tk-multi-workfiles2.maya.asset_step"
menu_favourites:
- {app_instance: tk-multi-workfiles2, name: File Open...}
- {app_instance: tk-multi-snapshot, name: Snapshot...}
- {app_instance: tk-multi-workfiles2, name: File Save...}
- {app_instance: tk-multi-publish2, name: Publish...}
template_project: asset_work_area_maya
location: "@engines.tk-maya.location"
Here you can see where it is possible to make changes to engine level settings such as menu_favourites or template_project. You can also add app references here. By default, all apps are included from app-specific files. This structure allows administrators to see how an engine is configured for all environments from within a single file.
How do I modify settings for an App?
Like engine settings, app settings are isolated in a settings file that defines configurations of that app across all environments. For example, the file env/includes/settings/tk-multi-publish2.yml defines all Publish2 configurations used by all environments. Here's a snippet showing the Publish2 settings for Maya in the shot_step environment:
# shot step
settings.tk-multi-publish2.maya.shot_step:
collector: "{self}/collector.py:{engine}/tk-multi-publish2/basic/collector.py"
collector_settings:
Work Template: maya_shot_work
publish_plugins:
- name: Publish to Shotgun
hook: "{self}/publish_file.py"
settings: {}
- name: Upload for review
hook: "{self}/upload_version.py"
settings: {}
- name: Begin file versioning
hook: "{engine}/tk-multi-publish2/basic/start_version_control.py"
settings: {}
- name: Publish to Shotgun
hook: "{self}/publish_file.py:{engine}/tk-multi-publish2/basic/publish_session.py"
settings:
Publish Template: maya_shot_publish
help_url: *help_url
location: "@apps.tk-multi-publish2.location"
You can see here how to modify the app-specific settings for the target environment. This structure allows administrators to see how an app is configured for all environments from within a single file.
How do I change a software path?
The env/includes/paths.yml file found in the legacy configuration has been renamed to env/includes/software_paths.yml. The structure of these files is identical, however the new configuration defines far fewer software paths. This is because the preferred method for resolving software paths with Toolkit is to use the Software entity. For more information on the Software entity and customizing it to work for your studio, please see the documentation found here.
Where did the shotgun_*.yml environment files go?
The shotgun_*.yml environment files have previously been used to configure what Toolkit actions are available within the Toolkit action menu in the Shotgun web app. We've now moved away from these extra environment files in favor of configuring the tk-shotgun engine in the same way that all other engines are configured. Instead of having a shotgun_xxx.yml file for each type of entity that we want Toolkit actions for, you will now see the configuration for the Shotgun engine in the more typical environments, like project.yml, shot_step.yml, and others. The goal has been to remove the special behavior surrounding Toolkit's browser integration in favor of a more standardized configuration. These changes to browser integration configuration are backwards compatible, so existing configurations will continue to function as they always have.
Where did app_launchers.yml go?
The app launcher definitions have been moved to env/includes/settings/tk-multi-launchapp.yml file. This brings app launching setting across various environments in line with the new structure of the configuration (each app/engine has its own settings file). It should also be noted that many of the app launch configurations have been removed in favor of the auto-discoverable app launch made possible by the Software entity. For more information on that, please see the Software entity documentation.
Can I still use the legacy Default configuration?
Yes. The legacy default configuration will still be available for use via the Advanced Project Setup in Shotgun Desktop. The Github repository will also remain visible and available for download. The legacy default configuration has also been updated with the latest apps, engines, and frameworks to bring it inline, version-wise, with the new default configuration.
