Open Brush Docs
  • Home
  • How to get Open Brush
  • Differences between Open Brush and Tilt Brush
  • User Guide
    • Get started with Open Brush
    • Painting with Open Brush
    • The Open Brush UI
      • Admin Panel
        • Settings Panel
        • Labs Panel
      • Tools Panel
        • Selection Options
        • Repaint Options
      • Brushes Panel
      • Extras Panel
        • Environment Panel
        • Lights Panel
        • Backdrop Panel
        • Guides Panel
        • Media Library
        • Camera Paths Panel
        • Snap Settings Panel
        • Transform Panel
        • Layers Panel
      • Experimental Panel
      • UI Differences Between Basic Mode and Advanced Mode
    • Grid and Angle Snapping
    • Repaint Tool and Jitter
    • Selection/Erase Filter
    • Lazy Input
    • Bimanual Input and Revolver
    • World Axis Unlock
    • Saving and sharing your Open Brush sketches
    • Troubleshooting issues with Open Brush
    • Check out Labs features
    • Importing Images, Videos and 3D Models
    • Experimental Mode
    • Make moving creations using audio reactive brushes
    • Using Reference Images on Oculus Quest
    • Remixing and Creative Commons
    • Accessing Autosave Files
    • The Open Brush config file
    • Exporting Open Brush sketches to other apps
      • Exporting to Unreal Engine 5
      • Exporting to Snapchat Lens Studio
      • Configuring Export
    • Plugins
      • Example Plugins
        • Example Pointer Plugins
        • Example Symmetry Plugins
        • Example Tool Plugins
        • Example Background Plugins
      • Writing Plugins
        • Getting Started
        • Tweaking existing plugins
        • Writing a Pointer Plugin
        • Writing a Symmetry Plugin
        • Writing a Tool Plugin
        • Writing a Background Plugin
        • Defining and Drawing Brush Strokes
      • Plugin API Scripting Reference
    • Open Brush Unity SDK
    • Open Brush API
      • Retrieving a preview image
      • API Commands List
    • Cameras and Exporting Video
    • Brushes
      • Brush List
      • Memory limits and brush costs
      • Experimental Brushes
      • Hiding Brushes with Brush Tags
    • Using Open Brush without a VR headset
    • Command Line Arguments
    • Tilt Brush Version 23 Release Notes
  • Get Involved!
    • How to help with Testing
  • Pre-release and Experimental Builds
    • Installing the Beta Release
    • "Experimental Mode" Builds
    • Feature: 3D Shapes Tool
    • Feature: Animation Timeline
    • Feature: Icosa Gallery Support
    • Feature: Brush Editing
    • Feature: Plugin Scripting
    • Feature: Sculpting
    • Combined Testing Build
    • Old or Completed Feature Builds
      • Feature: Polyhedra
      • Feature: Snip Tool
      • Feature: Layers
      • Insominx's (michael-g) Experimental Build
      • XR Framework Beta
      • Feature: Transform Panel and Snap Enhancements
      • Feature: Improved GLTF Importer
      • Feature: Multi-Mirror
      • Feature: New Monoscopic Mode
      • Feature: Improved Import/Export
      • Feature: Multiplayer
  • Case Studies
  • Other Resources
  • Developer Notes
    • UI Elements
    • Unity shader examples
    • Setting up CI for Open Brush using Github Actions
    • Open Brush File Format
    • Previous Github Wiki
      • Brushes
      • BuildingOpenBrush
      • BurstCompiler
      • Comparison
      • MonoscopicMode
      • PseudoCode
      • UserInterface
    • Differences between Standard and Experimental Mode
    • Open Brush AsCanvas Notes
    • Unity Versions
  • Release History
    • v2.10 Multiplayer
    • v2.9 (Maintenance)
    • v2.8 Import/Export
    • v2.7 (Maintenance)
    • v2.6 (Maintenance)
    • v2.5 (Maintenance)
    • v2.4 "Prismatic"
    • v2.2: Settings and Sketches
    • v2.1 Hotfix
    • 🚀v2.0: XR Update
    • v1.0: Happy Birthday to Us!
    • Current Beta Release Notes
  • Docs TODO
  • Contacting Us
Powered by GitBook
On this page
  • Libraries
  • Built-in functions and properties
  • Script Parameters
  • Coordinate Spaces
Edit on GitHub
Export as PDF
  1. User Guide
  2. Plugins

Writing Plugins

PreviousExample Background PluginsNextGetting Started

Last updated 5 months ago

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.

Libraries

In addition to the you can use most of the . Another included library is which you can use via require "lume"

Built-in functions and properties

The following realtime values from the sketch are examples of values that are available to use in your scripts. There are many more. Here is a

  • Brush.position: The current position of the brush pointer relative to the canvas

  • Brush.rotation: The current orientation of the brush pointer relative to the canvas

  • Brush.colorRgb: The current brush color

  • Brush.colorHsv: The current brush colour converted to HSV

  • Brush.size: The current brush size

  • Brush.pressure: The current pressure of the brush pointer (how hard the trigger is being pressed)

  • Brush.type: The current brush name

  • App.time: The time in seconds since Open Brush was launched

  • App.currentScale: The current scale of the canvas

  • Sketch.strokes A list of strokes in the current sketch

Script Parameters

Scripts can specify parameters that appear as UI widgets such as sliders. These appear in a popup when you click the "3 dots" button on the right of each row. For example you might want a script to have sliders to control "speed" or "wigglyness".

You define the widgets for each parameter in your script. Here's an example:

Parameters = {
    speed={label="Speed", type="float", min=0.01, max=32, default=16},
    radius={label="Radius", type="float", min=0.01, max=5, default=1},
}

function Main()
    angle = App.time * speed
    r = Brush.pressure * radius;
    pos = Vector3:New(Math.Sin(angle) * r, Math:Cos(angle) * r, 0)
    return Transform:New(pos)
end

Here we have defined two widgets. Both are floats (rather than integers) and we have defined a minimum, a maximum and a default value. You can set the ltext abel that appears when you hover over each slider.

The name of each widget (here "speed" and "radius") are then available to the script as variables.

Coordinate Spaces

By default each script type works relative to an origin and has a rotation that makes sense for each of the three types. Pointer and Tool Scripts are relative to the user's brush hand and Symmetry Scripts are relative to the Symmetry Widget.

You can override this. For example, here's a PointerScript that is relative to the canvas. We can then position the pointer so it is always at y=0 (the floor) but still tracks the pointer in the x and z directions:

Settings = {space="canvas"}

function Main()
    return Transform:New(
        Vector3:New(Brush.position.x, 0, Brush.position.z)
    )
end

Note that we have to manually specific pointer.position.x and pointer.position.y. If we were using space="pointer" (the default) then we wouldn't need to as coordinates are automatically relative to pointer.position

Valid spaces are currently "pointer" or "canvas".

Lua
Factorio
Garry's Mod
Roblox
LÖVR
API commands
Lua Standard Library
Lume
full list of methods and properties for each type.