Note

Did you use this template? We'd love to get a shout out on the product page or in the documentation!

You can use our badges with a link to https://scenery.io

• Cavalry Scripting
• Development
• Release
• Entrypoints
• Import Images
• Import Node Modules
• Import Files as Text
• Static Files
• Debugging
• Autocompletion
• Environment Variables
• TypeScript
• Minification

Some notes on the scripting environment in Cavalry:

• Every script has its own scope
• No native support for EcmaScript modules
• Javascript engine is V8 9.0
• EcmaScript version is ~2020 (11.0)
• No browser APIs other than console
• Scripts can be encrypted to .jsc through the JavaScript editor and the API
• There's no debugger. Use console logging instead.

[!INFO] The build folder is automatically symlinked to the Cavalry scripts folder, making it available in the scripts menu. You can find the scripts folder by going to Help > Show Scripts Folder in Cavalry.

On the command line run the following command in your script's folder.

npm run dev

This will start watching your source files and automatically builds into the build folder on every file change. Press Ctrl-C to stop the watch process.

On the command line run the following command in your script's folder.

npm run release

This will bundle, minify and encrypt your script into the build folder. A zip file is created in dist together with the files from static/release.

All .js and .ts files in the root of the src folder are considered an entrypoint. Multiple entrypoints will result in multiple scripts being bundled separately.

Importing a .jpg or .png will copy the image to the Script_assets folder and import its path. The path includes ui.scriptLocation so you can use it directly without needing to create the relative path.

import iconPath from './icons/scenery.png'
// `iconPath` becomes `${ui.scriptLocation}/Script_assets/scenery.png`
const image = new ui.Image(iconPath)

Install Node modules with

npm install [module-name] -D

After installing, import the module by using

import Name from 'module-name'
// or
import { thing } from 'module-name'

Check the module's documentation to see what can be imported.

Adding a ?text suffix to the path of an import statement will import that file as a string. Note that the contents will be imported as-is.

import expression from './modules/expression.js?text'
api.set('javaScriptShape#1', {
	'generator.expression': expression,
})

The contents of the static/_assets folder will be copied to the build folder. Note that any changes in this folder will not be watched, so you need to run the bundler again or save a change in the code.

All files in the static/release folder will be added the release zip after running npm run release.

The _assets folder is ignored by Cavalry and is used for any assets that the script uses. Read the further details.

There is no debugger, so console logging is used instead. The following methods, except for debug, are printed to Cavalry's Message Bar.

Typically used in testing. Printed in green.

console.log(msg: string)

Confirm when something expected has happened. Printed in green.

console.info(msg: string)

Warn a user when they've done something unexpected. Printed in yellow.

console.warn(msg: string)

Flag when something has gone wrong. Printed in red.

console.error(msg: string)

Print a message to the console when Cavalry is launched from the command line.

console.debug(msg: string)

On Windows the console is opened on start and remains open.

To open the console on Mac, run this command from the Terminal

/Applications/Cavalry.app/Contents/MacOS/Cavalry

Autocompletion for the Cavalry API is enabled for all JavaScript and TypeScript files inside the src folder. This is made possible by the cavalry-types. See its readme for further details.

All variables are replaced by their values at build time.

By default the bundler exposes:

• DEVMODE is true when NODE_ENV is development
• PRODUCT_NAME which is the name in package.json
• PRODUCT_DISPLAY_NAME which is the displayName in package.json
• PRODUCT_VERSION which is the version in package.json

All variables in a .env file will be exposed to all JavaScript or TypeScript files in the src folder.

This template is set up for JavaScript with type checking enabled. But you can just start using .ts files and you're good to go. Remove allowJs and checkJs from tsconfig.json to strictly support TypeScript only.

The esbuild bundler doesn't do any type checking. You still have to use tsc for that. Using TypeScript with esbuild comes with some caveats.

Only whitespaces are removed and variable names are shortened.