Open Brush (or at least currently the experimental build that supports plugins) ships with a selection of plugins that are both useful in their own right, great examples of what is possible and hopefully good starting points for people that want to write their own plugins.

This page will list the included plugins along with a brief explanation of what each one does. It is aimed mainly at users. If you're interested in understanding how each plugin was written, then the source code is hopefully clearly written and contains enough comments to make it easy to follow.

General Tips

• Try different brushes. Plugins can have wildly different results for some brush types. Try the hull brushes in particular with some of the Tool Plugins. Also try various animated brushes such as Neon Pulse or Keijiro Brush

• You can have more than one plugin type active at once and the combinations can be wild. Try combining a Symmetry Plugin with a Pointer Plugin. Or use a Background Plugin that animates a layer whilst drawing on it with an animated Pointer Plugin. Or maybe all three at once!

• Try spinning the Symmetry Widget with a flick of your hand while drawing. A slow spin gives very different results to a fast spin.

• (the rabbit/tortoise switch on your brush) is especially effective with some plugins. The smooth strokes you can with tortoise mode can combine beautifly with animated Pointer or Symmetry plugins.

• Many of the Symmetry Plugins have additional parameters for color shift. These allow you to create anything from a wild rainbow of different colored strokes, down to subtle shifts of your base color that gives a more natural effect.

• Don't forget to try different parameter values. The same plugin can look massively different based on the settings you choose.

• Use the Copy button to copy the script to your Open Brush folder and then open it up in a text editor (ideally something like VS Code). Try changing some of the values or modifying a line of lua code here or there.

You can open the Scripts Panel from a button on the

We won't be using the buttons on the bottom row at the moment. These are related to the older which are are useful for controlling Open Brush remotely. However the new plugin scripts are much more powerful and can add new features and modify how Open Brush works interactively.

The other four rows of buttons each relates to a different type of plugin. From the top down they are , , and .

A great way to get comfortable with how plugin scripting works - especially if you've never coded before - is to look at existing scripts and modify how they work in small (or maybe not so small!) ways.

Any of the example plugins can be copied to your Open Brush plugins folder simply by clicking the copy button for that plugin type:

(If this button isn't visible then a script of that name already exists in your plugins folder - you've probably already clicked the button for that particular plugin).

Once a plugin script does exist in your plugins folder you can edit it. Any changes you make will take effect immediately - there's no need to restart either Open Brush or the plugin itself. Any syntax errors might stop the plugin working. If so these are displayed on the console on the back of your brush controller. They will tell you which script and which line number has the problem.

Tool Plugins can do many different things but they are often used for drawing a lot of brush strokes all in one go. For example you could draw an entire spiral shape whenever the user clicks the trigger. Or you could use the positions: where they first pressed the trigger in and where their brush controller was when they released the trigger - to get the size of a region and create a shape that filled that space.

To create a Tool Plugin name your script with the prefix "ToolScript". For example: ToolScript.Circle.lua

Tool Scripts should usually return a list of transforms. If they do then this defines an entire brush stroke that is then created for you.

We previously started by showing the simplest possible plugin script - one that does nothing. Because a tool plugin does nothing by default that would be an empty file! But let's put a bit of scaffolding in so you have a starting point for a plugin that actually does something.

function Main()
    if Brush.triggerPressedThisFrame then
        return {}
    end
end

It checks to see if the user pressed the trigger and if so it returns an empty list. So this plugin does nothing and it does it every time the user presses the trigger. Great, huh?

Let's make it do something:

This returns a path with 5 points forming a square. A square has 4 corners so why 5 points? The last point is the same as the first so that the square closes on itself.

If you try this, you'll notice the square isn't very square. This is because Open Brush tries to smooth brush strokes. It expects you to be hand-drawing smooth curvy lines in space - not carefully placing precise geometric paths.

We can fix this by adding extra points:

This time we create a Path object instead of just using a list of transforms. This allows us to use any of the handy methods that are provided by Path - in this case it's the method. This modifies the path by inserting as many new points as we ask for in each path segment. In this case we ask for 5 new points so the square that previously had 5 points (and thus 4 segments) will now have 4 x 5 = 20 points. (I'll let you work out how many segments!)

Next let's draw a circle:

There's a few new things here:

1. a loop that begins for...do, this is a standard lua construct and works similarly to loops in other languages.

2. we first calculate a 2d vector using Vector2:PointOnCircle(angle). A Vector2 is very similar to the Vector3 that we used previously for specifying a position. The difference is that it only has two coordinates: x and y.

3. We convert the Vector2

When you paint freehand in Open Brush, the application is constantly recording your hand's position and orientation. Therefore internally a stroke is defined as a list of transforms. Scale isn't used but the position and rotation are key in defining the shape of the resulting stroke.

There are several situations when you might need to define a stroke when writing a plugin:

1. The most common use-case is with Tool Plugins. The value you return from the Main() function in a Tool Plugin is drawn as a brush stroke

2. You can paths explicitly using Path:Draw(), PathList:Draw() or the draw methods provided by classes such as SVG

In both these cases you must define the path as a list of transforms. Both the position and rotation are used to define the shape of the stroke. It matches what happens when you draw a stroke by hand - at each point in time you control both the position of the brush and it's orientation. Orientation doesn't matter for all brushes (a tube brush looks much the same whatever the rotation of the brush controller at each point is) but other brushes such as flat stroke brushes do make use of the rotation values you provide.

In the simple case where you are returning a value from the Main function of a Tool Plugin, you can return a normal lua array (or "table" as they are also called) containing two or more Transform instances:

It's simple to use a lua list like this: {} but there is also a class specifically for definition a list of transforms and it's called . The advantage of using this class is that also has many useful methods for modifying paths.

(The various Draw() methods insist that you use a Path object - so you can't use a simple lua array when you use those.)

Open Brush usually assumes a brush stroke is drawn by hand. Some simplification is done depending on your settings but a stroke is still usually made up of a lot of points forming a smooth curve as the app samples your controller position and orientation many times a second.

When you draw paths via code in a plugin script, you often send only the exact points you want. For example if you were drawing a square then you'd simply define the four points that make up the corners of the square (although you usually repeat the first point at the end if you want a closed shape)

The problem is that by default Open Brush tries to smooth the path you give it so your nice precise square becomes a rounded squiggle. The end result actually varies depending on the brush you use - different brushes use different rules for how to smooth the input points.

But generally speaking - if you want to draw a precise geometric shape then you need to add extra points - and the Path object has some useful methods to do this.

Ballistic Missile

Launches a line from your brush which you can steer. Similar to except that you can steer the brush stroke as it moves.

Choosing an Editor

In theory you could use any text editor to write and edit your plugin scripts: Notepad on Windows or TextEdit on MacOS.

However an editor that is designed for writing code has many useful features to make your life easier. You might already have a favourite editor. However one thing to consider it whether it supports Lua properly - and also if allows you to use the autocomplete hints that we automatically provide.

These hints will allow your editor to suggest method names, offer tooltips for parameters and even spot errors in the types you're using in your code.

If you're not sure then the simplest thing to do is just use Visual Studio Code:

Autocomplete and Intellisense for Lua scripts

If you look in your Documents/Open Brush/Plugins folder there is a subfolder called LuaModules and in there are a few commonly used libraries, that will provide some useful features.

However one file is different. It contains empty definitions for all available API methods and properties along with special comments that can be used by the EmmyLua plugin to give you working autocomplete, intellisense and tooltips. This makes writing scripts and finding bugs much easier.

If you're using Visual Studio Code then follow these steps: 1. Launch the Plugins build of Open Brush at least once so that it creates the Open Brush/Plugins folder.

1. Launch Visual Studio Code.

2. Click on the button on the left that shows the Extensions sidebar:

3. Search for "Lua" and look for the sumneko extension:

1. Click to install it and wait for it to finish installing

2. Click the small cog icon and then open the Extension Settings:

3. Optionally you can hide a lot of spurious warnings by disabling "lowercase-global" warnings under Lua> Diagnostics: Disable: (In our plugins we're using upper and lower case initial letters to distinguish your stuff from the API supplied-things but standard lua style is to use it to differentiate local from global. Don't worry for now...)

As soon as you type the period you should see a list of suggestions that match the "App" part:

If not - check you've followed all the steps above.

Next Steps

Now you've got a code editor installed and a plugin to help make things easier, you can move on to tweaking the example plugins and maybe even writing your own plugins from scratch.

Plugins are written in the scripting language which is designed to be simple to learn and easy to understand. There's plenty of tutorials online and Lua is widely used in games and applications such as , , , and many others.

If you've written scripts in any other language then you'll find it easy to pick up.

If you've never programmed at all then Lua is a great place to start. Copy an example script to your Open Brush folder (there's a button next to each Plugin type that does this for you), open it up in a text editor and try changing things.

As soon as you save your changes, Open Brush will load the new version. If you've made a mistake then the console on the back of your brush hand will tell you what line the error is on.

AutoSpinSymmetry

Allows you to precisely control the spin speed of the symmetry widget

CrossfadeLayers

AutoLathe

Like spinning the mirror by hand but with precise control

Parameters

• Speed: How fast to spin

• Angle X: The axis tilt in the X direction

• Angle Y: The axis tilt in the Y direction

Boids

A flock of pointers follows your hand using simple rules to control how they fly

Parameters

• Number of copies: How many boids in the flock

• Separation Amount: How strongly each boid tries to stay away from others

• Alignment Amount: How closely the boids try and follow the flocks path

Ducklings

The pointers follow your brush position but each one moves towards a point where your hand was further back in time

Parameters

• Copies: The number of strokes to draw at once

• Delay per copy: How far back in time (in frames) for each copy

• Amount: How far between the current and past position to move towards. 0.5 is the midpoint between past and current

EllipseAround

Copies of your stroke forming an ellipse - with optional color shifts

Parameters

• Copies: The number of strokes to draw at once

• Eccentricity: How elliptical the shape is

• Axis Consistency: Controls how much the elliptical axis follows your brush position

Frame

A simple frame of points following your brush position

HoldFirstClick

Like except the widget always moves to where you start drawing

Parameters

• Copies: The number of strokes to draw at once

ManyAlong

Linear copies of your stroke with optional color shifts

Parameters

• Copies: The number of strokes to draw at once

• Distance: How far each copy is from the next

ManyAround

Radial copies of your stroke with optional color shifts

Parameters

• Copies: The number of strokes to draw at once

PointSymSpin

Works like activating Multimirror but the extra pointers spin around your brush position

Parameters

(todo)

Pole

Multiple copies of your brush spaced between your left and right hand positions

Parameters

• Copies: The number of strokes to draw at once

PolygonAround

Copies of your stroke forming an polygon

Parameters

• Copies: The number of strokes to draw at once

• Sides: The number of sides of the polygon

RectangleAround

Copies of your stroke forming an rectangle

Parameters

• Number of points along width: How many points along the sides

• Number of points along height: How many points along the top and bottom

• Spacing: The distance between each point

• Exterior Only: Whether to create copies just around the perimeter or also fill in the middle

Spin

Multiple copies of your brush spinning around your actual brush position

Parameters

• Copies: The number of strokes to draw at once

• Speed: How fast the extra pointers are rotating

• Radius: The radius of the circle they are rotating around

StrokePoints

The previous stroke you drew is used as a template and multiple copies of the pointer are spread along it as you draw

Parameters

• Point Spacing: The distance to space out the copies along the stroke

SuperEllipseAround

Copies of your stroke forming a

Parameters

• Copies: The number of strokes to draw at once

• n: The parameter that controls the overall shape of the superellipse

• Eccentricity: How elliptical to make the shape

Svg

An example of using an SVG file as a template for symmetry patterns

SvgAround

Similar to but centered around the Symmetry Widget

Parameters

• Point Spacing: The distance between each pointer around the shape

Symmetry Plugins are similar to Pointer plugins with a few differences:

1. They can return a list of transforms that represent multiple pointers.

2. They can modify the color, size and brush type for each of the strokes separately.

3. They have access to the Symmetry Widget which can be used as a point of origin for each pointer. If you've used the Mirror or MultiMirror features in Open Brush then the Symmetry Widget is like the Mirror Widget that controls the reflection plane and center for those mirrors.

Bear in mind - the number of pointers you generate cannot change once a brush stroke has begun, but can change between each brush stroke.

Make sure you name your symmetry plugin scripts with the prefix "SymmetryScript". For example SymmetryScript.MyMirror.lua

Let's start with the simplest possible Symmetry Plugin:

In lua you can define a list of items by enclosing them in curly braces. This example is almost identical to the simplest possible Pointer plugin except that we wrap the transform in curly braces.

You might expect that it behaves the same - i.e. nothing changes and you paint as normal. However if you try it, you'll find that's not the case. In fact - you can't paint at all - your pointer remains stubbornly stuck to the center of the Symmetry Widget.

Why is this? By default Pointer Plugins and Symmetry Plugins use a different . This is how we describe how where the origin is and how translations and rotations are interpreted. Pointer plugins default to using the current brush controller position as the origin so all coordinates are relative to that. Symmetry plugins on the other hand default to using the Symmetry Widget as the origin. So returning a transform that does nothing means that the pointer is stuck at the widget's center.

You can change the default coordinate space by adding a value to the script settings:

This plugin will now behave the same as the "do nothing" pointer plugin example. Using space="pointer" in a Symmetry Plugin is useful if you want to ignore the widget and have all the pointers move relative to the brush controller.

Let's do something more interesting in our Symmetry Plugin:

Here we are returning a list of 4 transforms so we will have four separate pointers all creating a stroke at the same time.

Transform.Lerp is a method that takes two transforms as input and blends them by an amount given by the third number. So Transform.Lerp(a, b, 0.5) will return a transform that is exactly half-way between a and b. It's position will be at the midpoint of a and b and will have a rotation and scale exactly halfway between those of a and b.

What are we passing into Transform.Lerp? origin is set to Transform.identity which is our do-nothing transform. As mentioned before - in this case it will be the center point of the symmetry widget.

brushOffset is a with it's position set to the value ofSymmetry.brushOffset. This is a which represents the position of the user's brush controller relative to the symmetry widget. It is a special value that only makes sense in the context of a Symmetry plugin and you won't use it in other types of plugin script.

Usually the value of the user's brush controller is given byBrush.position. This is because by default, symmetry scripts use coordinates centered on the symmetry widget and you'd have to do a some complicated calculations to get from there to the current brush position. If you use symmetry.brushOffset this is done for you.

So this script will create 4 pointers that are spaced evenly between the symmetry widget and the user's brush controller as they paint. Give it a try!

Finally - let's look at one last symmetry script.

Some things to note here:

1. Instead of creating a list of transforms using curly braces we are creating a Pathobject and then using Insert to add pointers to it one at a time. Path is just a class that stores a list of transforms. It has some useful methods for transforming and modifying itself so is often more useful than just a simple list.

2. We are using a loop: for i = 1, copies do You should have come across similar constructs in other scripting languages. Any lua tutorial will explain some small differences with lua loops but in general they should behave as you would expect.

Background Plugins run all the time when activated. They are useful for animating layers or continually generating new shapes. You can still check for user actions such as pressing the trigger and change the action accordingly. They are very versatile but because they run continuously in they background, they can affect performance (especially if you run several at the same time).

Always use one of the other script types in preference if it is more suitable.

Unlike other plugin types, Background Plugins don't expect you to return a value and they don't do anything with any values you do return.

In contrast other plugin types use return values as follows:

1. Pointer Plugins use the returned value to change the pointer position, rotation or scale.

2. Symmetry Plugins use the returned values to create multiple new pointers.

3. Tool Plugins can use the returned value as the path of a new brush stroke which is drawn immediately.

You can of course draw in a Background Plugin but it's left to you to do so explicitly:

There are some potentially new details to be aware of here:

1. We are defining our own function to generate a random position around the current brush position

2. We are using the Random class to generate a point that is never more than a certain distance away from the origin. We then add that to the current brush position

3. We are manually drawing the path with myPath:Draw()

Circle

Draws a circle centered on the position you first press the trigger with the radius and orientation controlled by where you release the trigger.

Pointer Plugins can modify the pointer position and/or rotation every frame. You can get the current position and rotation so you can simply add an offset to those - or you could create an entirely new position or rotation based on any of the other context variables that are available to the script.

Name a Pointer Script with the prefix "PointerScript". For example: PointerScript.MyPlugin.lua

Assuming your script is valid (i.e. it has no syntax errors) then giving it a valid prefix is all you need for it to appear in the Scripts Panel.

By default a Pointer Script returns a which represents how the pointer moves relative to it's normal position (which in this case is wherever the user moves their brush hand)

The simplest possible pointer plugin would be something like this:

This does nothing at all. It returns a transform called "identity" which means "no change at all". There are several other ways to express the same thing:

There's no difference between these - it's just sometimes more convenient or clearer to write things in different ways.