第三方插件

简介

编写自定义 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 - 在访达中，打开前往菜单时按住 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 修复此问题。

还会出现警告对话框。要解决问题，用户应安装丢失的插件，然后重新打开原始场景文件。