Writing Custom Nodes in JavaScript

With Retrobatch Pro 1.2, you can now write your own nodes using JavaScript. This feature is considered a beta, and we're looking to collect feedback and ideas for it. If you run into problems or want to give feedback, make a post on our forum or send us an email: support@flyingmeat.com.

Warning

While 3rd party plug-ins can be extremely useful, they can also be dangerous to your computer and files. Plug-ins have the ability to read, write, and even delete files on your computer. Plug-ins available from our samples page have been reviewed and are considered reasonably safe to use. The same cannot be said for any plug-in downloaded from other locations on the Internet or linked to from our forums.

Sample Plug-Ins

You can download a number of sample plug-ins from our website. The source for these plug-ins are also available on GitHub.

Installing Plug-Ins

Installing a plug-in is easy. Simply download a plug-in, unzip it as necessary, and double click the File.retrobatchplugin. Retrobatch will then offer to install the plug-in for you.

Writing Plug-Ins

The quickest way to get started with writing a new plug-in is to download the "My Sample Plugin" template, and modify the files in it.

Since Retrobatch plug-ins are bundles, you'll want to select the SampleTemplate.retrobatchplugin in the Finder (after unzipping it), control-click on the file to bring up its contextual menu, and then choose "Show Package Contents". In here you'll see a number of folders and files. The first one of interest is the "manifest.json" file. This file is a JSON file which describes the plug-in. You can open up the file in your favorite editor (and if you don't have one yet, you can check out BBEdit, CodeRunner, or Xcode) and begin modifying things.

manifest.json

pluginName is the name your node will show up with in Retrobatch. This must be unique, so choose a nice name that you don't think other plug-ins will use.

pluginCategory is an optional string you can use to mark your plug-in for a particular category. If you don't have this key, Retrobatch will put it in a "Plug-In" category.

description is a string which shows up when your plug-in is selected in the node source list.

updateURL is a URL which Retrobatch can use to check for updates to your plug-in. It is currently unused.

mainScript is the name of the script Retrobatch will load up for the plug-in, and must be located in the Retrobatch subfolder.

version is the current version of the plug-in. It is currently unused.

The JavaScript Cocoa Bridge

While JavaScript is a powerful and expressive language, it doesn't have a whole lot of utility for integrating with MacOS or manipulating images. So we've included a "bridge" in Retrobatch, which allows JavaScript to load up and use classes and function from Apple's Cocoa and Core Graphics frameworks. This bridge is named "FMJS".

While JavaScript is a "safe" language, the bridge introduces a number of "unsafe" classes. What this means is, if you want to write a script that deletes all the files in your home folder, you have the power to do this. It also means that if you make a programming error and pass the wrong type of value to a Core Graphics function, Retrobatch is very likely going to crash. So care must be taken when dealing with low level MacOS functions.