cavalry-types

Typescript definitions for Cavalry

[!NOTE] Current supported API version is Cavalry 2.7.0

These definitions expose the whole Cavalry scripting API. Essentially it gives you all the documentation inside your editor. After installation and following the usage guidelines you can start writing your script to get suggestions about available methods and parameters.

If you're not sure how to start, follow the usage guidelines and press ctrl-space in VSCode, then type cav and you'll see the cavalry namespace suggested along with its description. Press enter and type . to see a list of all the available methods.

A few pointers:

• Hovering over a namespace, method or parameter will show its documentation along with examples (in most cases).
• Red squiggly lines will appear when methods or parameters don't exist or when they're of the wrong type. Hover over them to find out about the problem.
• Even though there might be errors and warnings in the code, it will still run (with or without errors). This is because the error checking happens only in your editor.
• If you're writing in Typescript, the code will not run in Cavalry. You will have to compile the code first or use Stallion which will strip out the types before sending them to Cavalry.

Stallion

It's recommended that you use the Stallion VSCode extension if you're new to the Node ecosystem. It can insert the Typescript definitions without the need to install them.

Installation

Make sure you first initialise a new npm project. In your terminal run:

npm init --yes

then install the Typescript definitions:

npm install @scenery/cavalry-types --save-dev

Usage

You can either use Triple-Slash Directives for one-off scripts. Or for more involved projects, you can use a Typescript Config.

Triple-Slash Directives

Add the following triple-slash directive at the top of your script file.

/// <reference types="@scenery/cavalry-types"/>

Optionally include a @ts-check comment to enable type checking.

/// <reference types="@scenery/cavalry-types"/>
// @ts-check

Typescript Config

Create a tsconfig.json in your project folder and add @scenery/cavalry-types.

{
	"compilerOptions": {
		"types": ["@scenery/cavalry-types"]
	}
}

Versioning

The latest types are always up-to-date with the latest Cavalry release. To install the types for a previous Cavalry version check the changelog for the version corresponding to the Cavalry version.

Contextual Types

Cavalry has various scripting namespaces that can be used in specific contexts eg. JavaScript Layers, Render Scripts, etc.

Every context exposes only those types that are available in that context. The available contexts are:

• script is the default context. It's used for Scripts (with or without UI)
• plugin for Scripts that are part of a Plugin
• render for Setup, Pre- and Post-Render Scripts
• shape for JavaScript Shapes
• utility for JavaScript Utilities
• deformer for JavaScript Deformers
• emitter for JavaScript Particle Emitters
• modifier for JavaScript Particle Modifiers

Usage

Append the context name to the path in the Triple-Slash Directive.

/// <reference types="@scenery/cavalry-types/render"/>

TypeScript

If you're using tsconfig.json, append the context name to the path in the types array.

{
	"compilerOptions": {
		"types": ["@scenery/cavalry-types/render"]
	}
}

Sponsors

Huge thanks to Cavalry for sponsoring this project! Interested in sponsoring? Send us a message.