Third Party Plugins

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 drag the plugin's folder or a .zip of the folder anywhere into the Cavalry window.

If the files within the folder are valid a confirmation dialogue will appear.

This will add the folder containing the Shader's/Filter's files to:

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

The Layer will then be available within Cavalry.

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
  ┠ welcome.js
  ┠ versioning.js

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 where a niceName is not specified.
• 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.

Welcome

An optional welcome.js file can be included as a way to onboard/welcome new users. Use the Script UI to create a 'splash screen' that will appear on successful installation.

install.fromUpdate can be used to create conditionals when updating plugins.

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

Versioning

If versioning.js is present in a plugin's folder it will be run when opening any Scene that contains one of the plugins Layers. This can be used to add backwards compatibility for users with Scenes containing previous versions of a plugin.

versioning.js has access to two member variables via a plugin module:

• layerId e.g plugin.layerId
• saveData e.g plugin.saveData - saveData is a copy of the data found in the .cv file for this Layer which can be used to access attribute data.

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

Missing plugins

Opening a Scene containing missing plugins will trigger Cavalry to create a copy of the Scene. This copy removes the missing plugins from the Scene as there is currently no way for a user to this via the UI.

A warning dialogue will also appear. To resolve the issue a user should install the missing plugins and then reopen the original Scene file.