サードパーティプラグイン

概要

カスタム Shaders、Filters、JavaScript Layers を作成し、Cavalry でネイティブレイヤーとして読み込むことができます。

Cavalry は ‘Third Party’ ディレクトリを再帰的に検索するため、プラグインは任意のディレクトリにパッケージ化できますが、各「製品」は 1 つの strings/definition.json ファイルを含む単一のフォルダ内で公開することをお勧めします。

製品は 1 つの Shader でも、10 個のバンドルでも構いません。各製品を適切にパッケージ化して配布してください。

プラグイン SDK をダウンロード。↓ ダウンロード

インストール

サードパーティレイヤーをインストールするには、プラグインのフォルダまたはフォルダの .zip を Cavalry ウィンドウ内の任意の場所にドラッグします。

フォルダ内のファイルが有効な場合、確認ダイアログが表示されます。

これにより、Shader/Filter ファイルを含むフォルダが以下に追加されます：

• macOS - ~/Library/Application Support/Cavalry/Third-Party/Plugins
• Windows - C:\Users\<USER>\AppData\Roaming\Cavalry\Third-Party\Plugins

その後、レイヤーは Cavalry 内で利用可能になります。

AppData と ~/Library は隠しフォルダです。見つけるには：

• Windows - エクスプローラーの表示オプションで「隠しファイル」をチェックします。
• macOS - Finderで、移動メニューを開く際に Option/Alt キーを押すとライブラリが表示されます。

プラグインの構造

サードパーティレイヤーは複数のファイルで構成されます。

📁 Layer  ┠ definitions.json  ┠ layer.sksl  ┠ layerIcon.png  ┠ layerIcon@2x.png  ┠ setup.js  ┠ strings.json  ┠ welcome.js  ┠ versioning.js

Layer SkSL ファイル

レイヤーを定義する SkSL コードを含みます。これらのファイルは Cavalry の API モジュールの encryptFile を使用して暗号化できます。暗号化されたレイヤーは拡張子 .skslc を使用する必要があります。

Definitions JSON ファイル

レイヤーの Attribute を作成するための情報、UI の順序、アイコン名、その他の有用な情報を含みます。複数のレイヤーの定義を同じファイルに含めることができます。以下の例を参照してください。

作者

definitions.json と strings.json ファイルには、レイヤー作成者の識別子（例：会社名）として “author” キーを含める必要があります。これはプラグインの登録時に内部的に使用されます。この識別子にはスペースやピリオドを含めず、キャメルケースで記述することをお勧めします。

"author": "sceneGroup",

サードパーティレイヤーの superTypes は次のとおりです：

レイヤータイプ	SuperType	用途
Filter	thirdPartyFilter	カスタム Filters を作成
Shader	thirdPartyShader	カスタム Shaders を作成
JavaScript Utility	thirdPartyJavaScript	値（数値、色、文字列）を生成
JavaScript Shape	thirdPartyJavaScriptShape	カスタム Shapes を作成
JavaScript Deformer	thirdPartyJavaScriptDeformer	既存の Shapes を変更

JavaScript セットアップスクリプト

このオプションのスクリプトは、レイヤー作成時に追加のセットアップを実行するために使用できます。例えば、必要に応じて追加のレイヤーや接続を作成できます。このスクリプトの実行時には、変数 ‘layerId’ を含む ‘setup’ というモジュールが利用可能です。これを使用して作成中のレイヤーの ID にアクセスできます。

ノード文字列

strings.json ファイルを使用して以下を含めることができます：

• 表示名 - niceName を指定して definitions.json 内の属性名を上書きできます。niceName が指定されていない場合、camelCase という名前の属性は UI で自動的に Camel Case に変換されます。
• ツールチップ - 属性にホバーしたときに表示される情報を追加します。

このファイルには author キーを含める必要があります。

現在、翻訳はまだサポートされていません。

アイコン

アイコンの追加はオプションですが、強くお勧めします。デフォルトのアイコン名は定義スキーマで設定する必要があります。

アイコンタイプ	サイズ	サフィックス	例名
レイヤー	18x18px		layerIcon.png
レイヤー（高解像度画面）	36x36px	@2x	layerIcon@2x.png
Attribute Editor	16x16px	_ae	layerIcon_ae.png
Attribute Editor（高解像度画面）	32x32px	_ae@2x	layerIcon_ae@2x.png

Attribute Editor アイコンはあまり使用されませんが、Distortion Filter の Input Shader ドロップダウンリストのような状況で必要になる場合があります。

色

ネイティブアイコンの色は次のカテゴリに分類されます：

カテゴリ	色
Shape	#DDD273
Behaviour	#9DD998
Utility	#A8D3FA
Effect (Filters/Shaders)	#F5B4B8
All	#CACACA

ウェルカム

オプションの welcome.js ファイルを含めて、新規ユーザーのオンボーディング/歓迎の手段として使用できます。Script UI を使用して、インストール成功時に表示される「スプラッシュスクリーン」を作成します。

install.fromUpdate を使用して、プラグイン更新時の条件分岐を作成できます。

const process = install.fromUpdate ? `updated` : `installed`;const label = new ui.Label(`You have ${process} the plugin.`);

バージョニング

プラグインのフォルダに versioning.js が存在する場合、そのプラグインのレイヤーを含むシーンを開くたびに実行されます。これは、以前のバージョンのプラグインを含むシーンに対して後方互換性を追加するために使用できます。

versioning.js はプラグインモジュールを介して 2 つのメンバー変数にアクセスできます：

• layerId 例：plugin.layerId
• saveData 例：plugin.saveData - saveData は .cv ファイル内のこのレイヤーのデータのコピーで、属性データへのアクセスに使用できます。

レイヤーの作成

Definition に Attribute を追加すると、これらの値は自動的にレイヤー内の uniform として利用可能になります。すべての Attribute タイプがサポートされているわけではないことに注意してください。

Shader の先頭に次の行を追加すると…

uniform float2 resolution;

…Cavalry はこの uniform をレンダリングされるシェイプのサイズに設定します。

子 Shaders がサポートされており、セットアップスクリプトで作成し、SkSL Shaders と同様にコード内でサンプリングできます。

子 Shaders は Shader の childShaders Attribute に接続する必要があります（この Attribute は自動的に追加されます）。

マルチパス Filters がサポートされています。

サンプルレイヤー

以下の SDK をダウンロードして解凍し、インストール手順に従ってください。

プラグイン SDK をダウンロード。↓ ダウンロード

不足しているプラグイン

不足しているプラグインを含むシーンを開くと、Cavalry はシーンのコピーを作成します。このコピーはシーンから不足しているプラグインを削除します。現在、ユーザーが UI を通じてこれを修正する方法はありません。

警告ダイアログも表示されます。問題を解決するには、不足しているプラグインをインストールし、元のシーンファイルを再度開く必要があります。