第三方外掛

簡介

撰寫自訂 Shaders、Filters 和 JavaScript Layers，它們可以作為原生圖層在 Cavalry 中載入。

Cavalry 會遞迴搜尋 ‘Third Party’ 目錄，因此外掛程式可以打包在任意目錄中，但建議每個「產品」發佈在一個單獨的資料夾中，包含一個 strings/definition.json 檔案。

一個產品可以是單個 Shader，也可以是 10 個 Shader 的捆綁包。相應地打包和分發每個產品。

下載外掛 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 檔案

此檔案包含用於建立圖層屬性的資訊，以及 UI 順序、圖示名稱和其他有用資訊。多個圖層的定義可以存在於同一檔案中。請參見下面的範例。

作者

definitions.json 和 strings.json 檔案都必須包含一個 “author” 鍵，作為圖層建立者的識別碼（例如公司名稱），該識別碼在外掛註冊時內部使用。此識別碼不得包含任何空格或句點字元，最好使用駝峰命名法（camelCase）撰寫。

"author": "sceneGroup",

第三方圖層的 superTypes 包括：

圖層類型	SuperType	用途
Filter	thirdPartyFilter	建立自訂 Filters
Shader	thirdPartyShader	建立自訂 Shaders
JavaScript Utility	thirdPartyJavaScript	產生值（數字、顏色、字串）
JavaScript Shape	thirdPartyJavaScriptShape	建立自訂 Shapes
JavaScript Deformer	thirdPartyJavaScriptDeformer	修改現有 Shapes

JavaScript 設定指令碼

此可選指令碼可用於在建立圖層時執行額外的設定。例如，如果需要，可以建立額外的圖層和連線。當此指令碼執行時，一個名為 ‘setup’ 的模組可用，其中包含變數 ‘layerId’。這可用於存取正在建立的圖層的 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 透過外掛模組存取兩個成員變數：

• layerId 例如 plugin.layerId
• saveData 例如 plugin.saveData - saveData 是 .cv 檔案中此圖層的資料副本，可用於存取屬性資料。

撰寫圖層

在定義中新增屬性時，這些值將自動作為圖層中的 uniform 可用。請注意，並非所有屬性類型都受支援。

在 Shader 頂部新增以下行…

uniform float2 resolution;

…將使 Cavalry 將此 uniform 設定為正在渲染的形狀的大小。

支援子 Shaders，可以透過設定指令碼建立，然後像 SkSL Shaders 一樣在程式碼中取樣。

子 Shaders 應連接到 Shader 的 childShaders 屬性（此屬性會自動新增）。

支援多通道 Filters。

範例圖層

下載並解壓下面的 SDK，然後按照安裝說明操作。

下載外掛 SDK。↓ 下載

遺失的外掛程式

開啟包含遺失外掛程式的場景將觸發 Cavalry 建立場景的副本。此副本會從場景中移除遺失的外掛程式，因為目前使用者無法透過 UI 修復此問題。

還會出現警告對話框。要解決問題，使用者應安裝遺失的外掛程式，然後重新開啟原始場景檔案。