Third Party Plug-ins

Technical Preview

This feature is in active development so subject to change.

Introduction

Write custom Shaders and Filters which can be loaded as native Layers in Cavalry.

Creating a product

Cavalry recursively searches the 'Third-Party' directory so plugins can be packaged in arbitrary directories but it's recommended that each 'product' is published within a single folder containing one strings/definition.json file.

A product could be a single Shader or it might be a bundle of 10. Package and distribute each product accordingly.

Installation

To install a third party Layer, add the folder containing the Shader's/Filter's files to:

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

The Layer will then appear within Cavalry following a restart.

info

AppData and ~/Library are hidden folders. To find them:

• Windows - check 'Hidden Items' in the View options for Explorer.
• macOS - in Finder, Library will appear when holding Option/Alt when opening the Go menu.

Anatomy of a plugin

Third party Layers consist of several files.

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

Layer SkSL file

This contains the SkSL code defining the Layer. These files can be encrypted using encryptFile from Cavalry's API Module. Encrypted Layers should use the extension .skslc.

Definitions JSON file

This contains the information used to create the Attributes for the Layer, along with the UI order, icon name, and other useful information. Definitions for multiple Layers can be present in the same file. See the example below.

Author

Both the definitions.json and strings.json files must include an "author" key as an identifier for the creator of the Layer (e.g. company name) which is used internally in the registration of plugins. This identifier must not contain any space or period (full stop) characters and is preferably written in camelCase.

"author": "sceneGroup",

Download the example definitions schema.↓ Download

superTypes

The third-party Layer superTypes are:

• Filter - "thirdPartyFilter"
• Shader - "thirdPartyShader"

JavaScript setup script

This optional script can be used to perform additional setup when creating a Layer. For example, additional Layers and connections can be made if required. When this script is run, a module called ‘setup’ is available with a variable ‘layerId’. This can be used to access the id of the Layer being created.

Node Strings

The strings.json file can be used to include:

• Nice names - A niceName can be specified to override the attribute's name in definitions.json. An attribute with the name camelCase will be automatically converted to Camel Case in the UI.
• Tooltips - Add information that appears when hovering an attribute.

This file must include the author key.

Unsupported features

Note that translation is not yet supported.

Download the example strings schema.↓ Download

Icon

Adding an icon is optional but highly recommended. The default icon's name should be set via the Definition Schema.

Icon Type	Dimensions	Suffix	Example Name
Layer	18x18px		layerIcon.png
Layer (high definition screens)	36x36px	@2x	layerIcon@2x.png
Attribute Editor	16x16px	_ae	layerIcon_ae.png
Attribute Editor (high definition screens)	32x32px	_ae@2x	layerIcon_ae@2x.png

The Attribute Editor icon is not often used but may be required in situations like the Input Shader drop down list for the Distortion Filter.

All native Shaders and Filters in Cavalry use the colors #F5B4B8 and #CACACA.

Writing Layers

When adding Attributes to the Definition, these values will become available as uniforms in the Layer automatically.

Note that not all Attribute types are supported.

Shaders

Adding the line...

uniform float2 resolution;

...to the top of a Shader will cause Cavalry to set this uniform to the size of the Shape being rendered.

Child Shaders are supported and can be created via the setup script and then sampled in the code much like they can be for SkSL Shaders.

Child Shaders should be connected to a Shader’s childShaders Attribute (this Attribute is added automatically).

Filters

Multi-pass Filters are not yet supported.

Example Layers

Download and unzip the files below and then follow the installation instructions.

Download example Filters.↓ Download Download example Shaders.↓ Download