環境設定リファレンス

はじめに

Toolkit パイプラインの中心にあるのは環境設定です。Toolkit パイプライン設定内の環境構成ファイルでは、さまざまな DCC 内で使用可能な Toolkit アプリを定義し、それぞれの設定をカスタマイズできます。このドキュメントは環境設定ファイルの構造と機能についての完全なリファレンスです。ここでは、プロジェクト内のさまざまなワークフローを設定するための Toolkit の「環境」の概念、環境設定の構成、ファイル参照、そしてどのようなカスタマイズが行えるかを確認する方法について説明します。

環境について

ShotGrid Toolkit プラットフォームは、一般的に使用されるコンテンツ作成ソフトウェア用に、完全にカスタマイズ可能な統合セットを提供するため、これを使用してスタジオのパイプラインを構築できます。プロジェクトの構成において、統合されているソフトウェアパッケージはどれか、そのそれぞれで利用可能な Toolkit アプリはどれかを指定し、さらに各アプリのオプションを指定することにより、スタジオのニーズに合わせてアーティストのワークフローを構築できます。

しかし、スタジオのパイプラインでは、さまざまなタイプのアーティストが異なるワークフローを使用するのが一般的です。簡単な例として、アセットを扱うアーティストの場合は Mari などのテクスチャペイントソフトウェアを利用可能にし、ショットを扱うアーティストの場合は Nuke などの合成ソフトウェアを利用可能にします。

ソフトウェアパッケージの他にも、異なるアーティストに対して、同じ Toolkit アプリで異なる設定を使用することができます。たとえば、ショットのアーティストとアセットのアーティストの両方が Workfiles アプリを使用することがありますが、ショットのアーティストは Shot エンティティ、アセットのアーティストは Asset エンティティに関連付けられているファイルにのみナビゲートできるように制限することができます。

プロジェクト内でこれらの個別のワークフローをサポートするために、Toolkit はアプリとエンジンの構成を環境上で分離しています。環境には、一連のソフトウェアパッケージの統合とその設定が含まれています。それらのすべてには、特定の共通するコンテキストがあります。

上記の例では、アセットを扱うアーティストはアセットの手順の環境で作業し、ショットを扱うアーティストはショットの手順の環境で作業しています。環境はそれぞれ独立して構成されているため、プロジェクト内で異なるワークフローを使用できます。

Toolkit の既定の設定に関するメモ

Toolkit での環境設定の構築には多くの自由が与えられています。このドキュメントは利用可能なすべてのオプションのリファレンスで、実際のパイプラインのニーズに最も適した選択をするのに必要な知識を得ることができます。

またこのドキュメントでは、既定の設定と呼ばれる、パイプライン設定の出発点として選択された特別な設定についても説明します。パイプラインをカスタマイズする準備が整ったら、最初の手順はプロジェクト用の編集可能なパイプライン設定を作成することです。

これらの選択は単なる規則であり、Toolkit のワークフローにハードコードされているわけではありませんが、既定の設定を例として参照すると、パイプラインのカスタマイズを開始した後に使用できる機能や、独自の設定を構築するためのベストプラクティスについて学ぶことができます。また、新しい Toolkit ユーザが既定の設定を出発点として参照すれば、Toolkit の規則について知るのにも役立ちます。このドキュメントでは、Toolkit の環境設定の一般的な機能と、既定の設定における特定の選択とを常に区別します。既定の設定の環境構成の詳細については、README ファイルを参照してください。

ファイルの場所

パイプライン設定内の config/ ディレクトリには、カスタマイズ対象のすべてのファイルとフォルダが含まれています。config/ には、cache、core、および env の 3 つのサブディレクトリがあります。env ディレクトリには環境設定ファイルが保持されるため、このドキュメントでは config/env 内のファイルを参照します。

env フォルダの内容

既定の設定では、config/env/ に次のファイルが表示されます。

asset.yml
asset_step.yml
project.yml
sequence.yml
shot.yml
shot_step.yml

これらの各ファイルは環境に対応しています。異なるファイルを含めることで、各環境を別々に設定できます。

Toolkit が現在の環境を判断する仕組み

Toolkitは pick_environment というコアフックを使用し、現在のコンテキストに基づいて特定の時点で使用する環境ファイルを決定します。pick_environment フックの戻り値は環境設定ファイルに対応しています。たとえば、pick_environment が shot_step を返した場合、Toolkit は config/env/shot_step.yml を使用して Toolkit 環境を設定します。

カスタム環境

上記の環境設定ファイルは、既定の設定で提供されます。ただし、スタジオによっては、異なる環境や追加の環境を採用することがあります。たとえば、スタジオによっては、パイプラインのステージごとに異なる構成設定が必要な場合があります(asset_step_rig、asset_step_model、shot_step_anim、shot_step_light など)。その場合、利用可能な環境を完全にカスタマイズできます。

これを行うには、目的の環境設定ファイルを config/env ディレクトリに追加します。次に、pick_environment コアフックをオーバーライドして、新しい環境をいつ使用するかを定義するロジックを追加します。

基本構造

Toolkit の設定ファイルは YAML で記述されます。バンドル(アプリ、エンジン、またはフレームワーク)の一般的な設定の構成は次のとおりです。

bundle_name:
  setting1: value
  setting2: value
  complex_setting:
    sub_setting1: value  
    Sub_setting2: value
  location:
    type: descriptor_type
    descriptor_setting1: value
    descriptor_setting2: value

この構成を説明するために、非常に単純な例を示します。単一のエンジンがあり、その中に単一のアプリケーションが定義されている環境です。以下は、この設定の project.yml の内容です。

engines:
  tk-maya:
    apps:
      tk-multi-workfiles2:
        location:
          type: app_store
          name: tk-multi-workfiles2
          version: v0.11.8
    location:
        type: app_store
        name: tk-maya
        version: v0.9.4

エンジンブロック

すべての環境設定ファイルは engines ブロックで始まります。ここに、その環境用に定義されているすべてのエンジンがネストされています。

この例では、単一のエンジン tk-maya のみが定義されています。apps と location の 2 つの設定がリストされています。

location はすべてのバンドルに必要な特別な設定です。apps 設定はエンジンに定義されたすべてのアプリのリストで、それぞれ独自の設定があります。この場合、エンジンに対して定義されるアプリは 1 つのみです(tk-multi-workfiles2)。

ロケーションディスクリプタ

すべての Toolkit バンドルには location 設定があり、これをバンドルの「ディスクリプタ」と呼びます。ディスクリプタは、特定のバンドルの入手元、およびそのタイプに応じて直接アクセスするかローカルにキャッシュするかを Toolkit に指示します。Toolkit バンドルは、ShotGrid App Store、git リポジトリ、ディスク上のパス、ShotGrid サイトにアップロードされた zip ファイルなどから入手できます。これらには、それぞれ対応するディスクリプタタイプがあり、そのタイプに固有の設定があります。以下に、上記の例の tk-maya エンジンのディスクリプタをもう一度示します。

    location:
        type: app_store
        name: tk-maya
        version: v0.9.4

これは、タイプが app_store のディスクリプタです。指定したバンドルを ShotGrid App Store から入手するように Toolkit に指示します。タイプ app_store のディスクリプタの設定は name と version です。

対照的に、スタジオでカスタムバンドルをアクティブに開発している場合、たとえば特定のワークフロー用の Toolkit アプリを作成している場合は、ディスク上のパスから直接入手することができます。この場合、以下に示すようにタイプ dev のディスクリプタを使用します。

    location:
        type: dev
        path: /path/to/app

dev ディスクリプタは app_store ディスクリプタとは設定が異なります。他の設定を使用することもできますが、ディスク上のアプリの場所を参照する path 設定を使用して簡単にセットアップすることができます。

利用可能なすべてのディスクリプタタイプとその設定に関する詳細は、Toolkit Core API ドキュメントの「ディスクリプタ」セクションを参照してください。

アプリブロック

アプリは Toolkit のユーザツールであり、各アプリは他のアプリから独立して実行できます。パイプラインのニーズに基づいてどのアプリを使用するかを選択できます。エンジンブロック内の apps 設定は、特定のエンジンで使用できるアプリを定義します。

以下に、上記の例の apps 設定をもう一度示します。

engines:
  tk-maya:
    apps:
      tk-multi-workfiles2:
        location:
          type: app_store
          name: tk-multi-workfiles2
          version: v0.11.8

単一のアプリ、tk-multi-workfiles2 アプリが定義されていることがわかります。現在のところ、単一の設定、すなわちディスクリプタのみが定義されています。

project 環境の tk-maya エンジンで他のアプリを利用できるようにするには、ここで追加します。ここでは、エンジンに Panel、tk-multi-shotgunpanel、および About アプリ、tk-multi-about を追加します。例の project.yml ファイルは次のようになります。

engines:
  tk-maya:
    apps:
      tk-multi-about:
        location:
          type: app_store
          name: tk-multi-about
          version: v0.2.8
      tk-multi-shotgunpanel:
        location:
          type: app_store
          name: tk-multi-shotgunpanel
          version: v1.6.3
      tk-multi-workfiles2:
        location:
          type: app_store
          name: tk-multi-workfiles2
          version: v0.11.8
    location:
        type: app_store
        name: tk-maya
        version: v0.9.4

ここでは、いくつかの重要な注意事項があります。

既定の設定ではバンドルがアルファベット順にリストされ、この例ではその規則に従います。
ファイルが長くなり始めていますが、構成設定はまだ追加していません。
他のエンジンや他の環境でこれらと同じアプリを使用していることが想像できます。たとえば、Panel、About アプリ、Workfiles アプリの 3 つのすべてのアプリが、異なるエンジン(Houdini、Nuke、Photoshop など)および異なる環境(asset_step や shot_step)で実行されている可能性があります。設定内の異なる場所で共通のアプリ設定を定義することは、変更が必要なときに、それぞれの場所で変更が必要になることを意味します。

最後の 2 つの問題を軽減するために、Toolkit 設定はインクルードをサポートします。

インクルード

「インクルード」を使用すると、あるファイルのセクションを構成内の別のファイルで参照できます。インクルードを使用すると、構成設定を一箇所で設定し、複数の環境で使用できます。

インクルードは次の 2 つの部分で構成されます。

includes リスト: キーが includes で、インクルードするすべてのファイルのリストを値に持つ YAML 辞書。
構成設定内の参照。@ 記号で始まり、インクルードファイルから参照するセクションの名前をポイントする名前が付けられています。

上記の例を具体化するために、すべてのエンジンのロケーションディスクリプタを保持する単一のファイルを作成しているとします。そのファイルを includes サブフォルダに置き、engine_locations.yml という名前を付けます。

engine_locations.yml の内容は以下のようになります。

config/env/includes/engine_locations.yml:

engines.tk-maya.location:
  type: app_store
  name: tk-maya
  version: v0.9.4

engines.tk-nuke.location:
  type: app_store
  name: tk-nuke
  version: v0.11.5

...

このファイルはすべてのエンジンの場所に対する単一のソースとして機能し、すべての環境設定から参照することができます。このインクルードファイルを使用した場合、この例は次のようになります。

config/env/project.yml:

includes:
- includes/engine_locations.yml

engines:
  tk-maya:
    apps:
      tk-multi-about:
        location:
          type: app_store
          name: tk-multi-about
          version: v0.2.8
      tk-multi-shotgunpanel:
        location:
          type: app_store
          name: tk-multi-shotgunpanel
          version: v1.6.3
      tk-multi-workfiles2:
        location:
          type: app_store
          name: tk-multi-workfiles2
          version: v0.11.8
    location: @engines.tk-maya.location

engine_locations インクルードファイル

ここでは、tk-maya エンジンの location 設定の値が、インクルードされる YAML ファイルのキーを参照していることがわかります。

アプリの場所を示すために、2 番目のインクルードファイルを追加することができます。実際には、これは既定の設定によって行われます。例を拡張してみましょう。

config/env/includes/app_locations.yml:

apps.tk-multi-about.location:
  type: app_store
  name: tk-multi-about
  version: v0.2.8

apps.tk-multi-shotgunpanel.location:
  type: app_store
  name: tk-multi-shotgunpanel
  version: v1.6.3

apps.tk-multi-workfiles2.location:
  type: app_store
  name: tk-multi-workfiles2
  version: v0.11.8

config/env/project.yml:

includes:
- includes/app_locations.yml
- includes/engine_locations.yml

engines:
  tk-maya:
    apps:
      tk-multi-about:
        location: @apps.tk-multi-about.location
      tk-multi-shotgunpanel:
        location: @apps.tk-multi-about.shotgunpanel.location
      tk-multi-workfiles2:
        location: @apps.tk-multi-workfiles2.location
    location: @engines.tk-maya.location

インクルードされた engine_locations.yml ファイルから tk-maya エンジンのディスクリプタを取得し、インクルードされた app_locations.yml ファイルから tk-maya エンジン用に定義された各アプリのディスクリプタを取得します。

スパース構成

すべての Toolkit バンドルには、使用可能な構成設定のセットがあり、それぞれの設定に既定値があります。Toolkit は「スパース構成」を許可します: 構成設定が環境設定ファイル(またはそこに含まれるファイル)で明示的に指定されていない場合、バンドルの既定値が使用されます。

この例では、location 以外にアプリの設定を指定していません。したがって、設定の現在の状態では、3 つのアプリはすべての設定に既定値を使用します。それでは、どの構成設定が利用可能であるかを知るにはどうすれば良いでしょうか。

利用可能な構成設定を検出する

スパース構成では、単に設定ファイルを見ただけでは、どの構成設定がアプリに使用できるかをすぐに判断することはできません。アプリで利用可能な構成設定を確認する場合、2 つの選択肢があります。

アプリのドキュメント: 各アプリには独自のドキュメントページがあり、それぞれのページに「設定オプション」セクションがあります。このセクションでは、アプリで使用可能なすべての構成設定が、それぞれの説明と既定値と共に一覧表示されています。たとえば、Workfiles ドキュメントページを参照することができます。アプリとエンジンのページには、すべてのアプリとエンジンのドキュメントページが一覧表示されています。
マニフェスト: すべての Toolkit バンドルは、そのルートディレクトリに info.yml というファイルを含んでいます。このファイルをバンドルの「マニフェスト」と呼び、バンドルで利用可能なすべての設定を、それぞれの説明と既定値と共に定義します。マニフェストは、バンドルの独自のキャッシュ(パイプライン設定内の install/app_store/tk-multi-workfiles2/v0.11.8/info.yml など)、または Github (ここでは Workfiles の場合の例を示します)にあります。

構成設定を修正する

既定値の設定を変更するには、パイプライン設定の適切な環境で、適切なブロックに構成を追加し、その値を設定します。

例に戻って、プロジェクト環境で Maya が起動されると tk-multi-workfiles2 が自動的に起動するように設定してみましょう。アプリのマニフェストを見ると、アプリの起動時に Workfiles UI を起動するかどうかを制御する launch_at_startup 設定があり、その既定値が False であることがわかります。そこで、launch_at_startup オプションを追加して True に設定します。project.yml ファイルは次のようになります。

config/env/project.yml:

includes:
- includes/app_locations.yml
- includes/engine_locations.yml

engines:
  tk-maya:
    apps:
      tk-multi-about:
        location: @apps.tk-multi-about.location
      tk-multi-shotgunpanel:
        location: @apps.tk-multi-about.shotgunpanel.location
      tk-multi-workfiles2:
        launch_at_startup: True
        location: @apps.tk-multi-workfiles2.location
    location: @engines.tk-maya.location

tk-multi-workfiles2 の設定がインクルードファイルからのものである場合は、そのファイルでこの変更を行います。

環境設定リファレンス

はじめに

環境について

Toolkit の既定の設定に関するメモ

ファイルの場所

Toolkit が現在の環境を判断する仕組み

カスタム環境

基本構造

エンジン ブロック

ロケーション ディスクリプタ

アプリ ブロック

インクルード

スパース構成

利用可能な構成設定を検出する

構成設定を修正する

その他の参考情報

エンジンブロック

ロケーションディスクリプタ

アプリブロック