Getting started

A plugin is a single file that says what it adds. Write one, install it, and it is part of the program.

Your first plugin

In TypeScript a plugin is a module whose default export is an object. In Python it is a file that leaves a Plugin in a variable named plugin. Only an id and a name are required.

import type { Plugin } from './rassam';

const plugin: Plugin = {
  id: 'hello',                 // its own short name: letters, digits, - . _
  name: 'Hello',
  version: '1.0',
  author: 'You',
  about: 'Adds one command that counts the layers.',

  commands: [{
    label: 'Count the layers',
    run(api) {
      api.notify(`${api.project.layers.length} layers`, 'success');
    },
  }],
};

export default plugin;
from rassam import Plugin

plugin = Plugin('hello', 'Hello', version='1.0', author='You',       # its id: letters, digits, - . _
                about='Adds one command that counts the layers.')


@plugin.command('Count the layers')
def count(app):
    app.notify(f'{len(app.layers)} layers', 'success')

Installing it

  1. Open File › Settings…, choose Plugins, then Browse plugins….
  2. Choose Custom plugins, then Choose a file…, and pick the plugin's file: .ts, .mts or .py.
  3. The plugin is read, shown for you to confirm, installed and turned on. Its switch turns it off and on again; Remove takes it out.
A plugin can read and change your projects. Install only plugins you trust.

Choosing a language

LanguageGood to know
TypeScriptRuns directly. Only types may be imported; the program hands the plugin everything it works with. Keep rassam.d.ts beside the file and your editor knows every name.
PythonOrdinary Python, with the standard library (math, random, colorsys, json…). Python is fetched the first time a Python plugin is used. See Python.

A plugin's mistakes do not stop the program: an error is reported in the status bar and the rest goes on.

Where next

Anatomy lists everything a plugin can declare. The API is what its code is given. The pages under What a plugin adds take each kind of thing in turn.