Third Party Plug-ins - Shaders

Technical Preview

This feature is in active development so subject to change.

Introduction

Write custom Shaders for use as Layers in Cavalry.

Installation

To install a third party Shader, drag a folder containing the Shader files into:

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

The Shader will then appear as a Layer inside 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 Shader

Third party Shaders consist of several files.

📁 Shader
  ┠ shader.sksl
  ┠ shaderIcon.png
  ┠ shaderIcon@2x.png
  ┠ definitions.json
  ┠ setup.js

Shader SkSL file

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

Definitions JSON file

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

JavaScript setup script

This optional script can be used to perform additional setup when creating a Shader. 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 Shader being created.

Icon

Adding an icon is optional but highly recommended.

Icons should be 18x18px and include a 36x36px version for high definition screens. e.g. include shader.png and shader@2x.png.

Definition Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "description": "The specific type of layer, e.g., 'brickShader'."
      },
      "superType": {
        "type": "string",
        "description": "The parent type of this layer, i.e., 'thirdPartyShader'."
      },
      "javaScriptSetupFile": {
        "type": "string",
        "description": "Path to the (optional) JavaScript setup file."
      },
      "skslFile": {
        "type": "string",
        "description": "Path to the SKSL file defining the shader."
      },
      "version": {
        "type": "number",
        "description": "Version of the layer definition."
      },
      "attributes": {
        "type": "object",
        "description": "Defines the attributes for the layer.",
        "additionalProperties": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": ["double", "double2", "color", "bool", "int", "int2"],
              "description": "Type of the attribute. Integers, booleans and doubles will be converted to floats for the Shader."
            },
            "default": {
              "type": "object",
              "description": "Default value of the attribute. Type depends on the attribute type."
            },
            "min": {
              "type": "number",
              "description": "Minimum allowable value, if applicable."
            },
            "max": {
              "type": "number",
              "description": "Maximum allowable value, if applicable."
            },
            "step": {
              "type": "number",
              "description": "The scrubbing multiplier for the UI, e.g 0.01"
            },
            "children": {
              "type": "object",
              "description": "Child attributes for composite types like double2.",
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "min": {
                    "type": "number",
                    "description": "Minimum allowable value for this child."
                  },
                  "max": {
                    "type": "number",
                    "description": "Maximum allowable value for this child."
                  }
                }
              }
            }
          },
          "required": ["type"]
        }
      },
      "triggers": {
        "type": "object",
        "description": "Defines triggers for the layer.",
        "properties": {
          "out": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of attributes that act as output triggers, i.e when said Attribute updates, the Shader recalculates."
          }
        }
      },
      "UI": {
        "type": "object",
        "description": "Defines UI settings for the layer.",
        "properties": {
          "attributeOrder": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Defines the order of attributes in the UI."
          },
          "icon": {
            "type": "string",
            "description": "The name of the icon to use for this layer. e.g myShader.png"
          }
        }
      }
    },
    "required": ["nodeType", "attributes", "superType", "triggers", "UI", "skslFile"]
  }
}

Unsupported features

Note that translation, tooltips and description strings are not yet supported.

Writing Shaders

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

Note that not all Attribute types are supported.

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).

Example Shader

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

Download an example Bricks Shader.↓ Download