Open Brush Lua Plugin Development

This skill helps you create and modify Lua plugins for Open Brush, a VR painting application. You have access to the complete Open Brush Lua API documentation.

Quick Start

Plugin File Structure

CRITICAL: Plugin Naming Convention Plugins MUST be named with the correct prefix or Open Brush won't recognize them:

• PointerScript.PluginName.lua (e.g., PointerScript.Wobble.lua)
• SymmetryScript.PluginName.lua (e.g., SymmetryScript.ManyAround.lua)
• ToolScript.PluginName.lua (e.g., ToolScript.Circle.lua)
• BackgroundScript.PluginName.lua (e.g., BackgroundScript.Lines.lua)

A basic plugin structure:

-- Plugin metadata (in Settings table)
Settings = {
  description = "What this plugin does"
}

-- Optional parameters (exposed as UI sliders)
Parameters = {
  speed = {label = "Speed", type = "float", min = 1, max = 100, default = 50}
}

-- Main function (required) - runs every frame
function Main()
  -- Your plugin logic here
  -- Return value determines plugin type (Transform, Path, PathList, or nothing)
end

-- Optional: runs once when plugin starts
function Start()
  -- Setup code
end

-- Optional: runs once when plugin ends
function End()
  -- Cleanup code
end

Where to Find Information

IMPORTANT: All documentation files are located inside this skill's directory. The skill directory is typically at: ~/.claude/skills/open-brush-plugin-skill/ (or C:\Users\USERNAME\.claude\skills\open-brush-plugin-skill\ on Windows)

All paths below are relative to the skill directory, NOT the user's project directory.

When creating a new plugin:

1. Read references/instructions.md for critical API syntax rules and plugin structure
2. Check references/examples/ directory for similar working code (PointerScript., SymmetryScript., ToolScript., BackgroundScript.)
3. Read references/guides/example-plugins/ for explanations of what example plugins do
4. Read references/guides/writing-plugins/ for step-by-step tutorials on each plugin type

When you need API details:

1. Check references/lua-modules/__autocomplete.lua for complete list of available classes/methods/properties
2. Read specific files in references/api-docs/ directory: app.md, brush.md, vector3.md, path.md, etc.

External reference (for context only): https://icosa.gitbook.io/open-brush-plugin-scripting-docs

Instructions for AI Agents

Critical API Rules

MOST IMPORTANT: Only use APIs listed in references/lua-modules/__autocomplete.lua. NEVER invent methods or properties. If unsure, say "I'm unsure - let me check the API documentation" and read __autocomplete.lua. Favor the Open Brush API over standard Lua library functions.

Core Syntax Rules:

• Constructors: ClassName:New(...) (capital N, always use colon)
• Properties: object.property (dot notation)
• Methods: object:method() (colon notation)
• API classes start with capital letters (e.g., Vector3, Transform, Path)
• Methods do NOT return self - no method chaining
• Use Math (capital M) library, not lua's math

Plugin Structure: All plugins define:

• Main() - called every frame (required)
• Start() - called when plugin begins (optional)
• End() - called when plugin ends (optional)
• Settings table - plugin metadata (optional)
• Parameters table - UI sliders for user input (optional)

Settings = {
  description = "Plugin description",
  space = "pointer" -- or "canvas", "world", etc.
}

Parameters = {
  speed = {label = "Speed", type = "float", min = 1, max = 100, default = 50}
}
-- Access as: Parameters.speed

Four Plugin Types:

1. Pointer Plugin - Returns single Transform

   • Modifies the user's primary brush pointer position while user draws

2. Symmetry Plugin - Returns Path or list of Transform

   • Controls multiple brush pointers while the user draws
   • Each transform generates one additional stroke
   • Important to understand its special use of coordinate spaces (especially the symmetry widget)
   • Can be combined with Pointer plugins
   • Overrides and replaces mirror or multimirror symmetry modes

3. Tool Plugin - Returns Path or PathList

   • Generates a complete stroke or strokes in one action based on the users actions
   • Return the stroke data as Path or PathList in Main() - do not use Path:Draw() etc directly
   • Typically triggered on button press/release
   • Active mirror, multimirror or symmetry plugin modes are automatically applied to the output

4. Background Plugin - Returns nothing

   • Runs autonomously every frame
   • Draws strokes using explicit Draw() methods

Important Constraints:

• Brush type cannot change during a stroke - only between strokes
• Brush size cannot change during a stroke but modifying pressure within a stroke often affects size
• Brush color cannot change during a stroke but color overrides can be applied within a stroke.
• Understand coordinate spaces - default varies by plugin type (check Settings.space)
• Transform scale component affects stroke width/thickness

For complete details, examples, and edge cases, read references/instructions.md

Common Gotchas

1. Coordinate Spaces: By default, Pointer/Tool plugins use space="pointer" (relative to brush hand) while Symmetry plugins use the symmetry widget as origin. Override with Settings.space="canvas" or Settings.space="pointer".

2. Path Smoothing: Open Brush smooths paths for hand-drawn strokes. For geometric shapes, add extra points with Path:SubdivideSegments(n) to prevent rounding.

3. Multiple Active Plugins: You can run multiple Background plugins simultaneously, but only one of each other type (Pointer/Symmetry/Tool). You can combine the effects of Pointer and Symmetry. Or Symmetry and Tool.

Plugin Development Workflow

When helping users with Open Brush Lua plugins:

1. Check example plugins for similar functionality - Consult both references/examples/ (actual code) and references/guides/example-plugins/ (explanations). The examples demonstrate working patterns.
2. Verify API calls - Check references/lua-modules/__autocomplete.lua before using any API methods or properties
3. Ask clarifying questions about what the plugin should do before writing code
4. Provide complete, working examples that users can copy and test
5. Consider performance - Warn if operations might be slow (e.g., processing thousands of strokes every frame)

Example Plugin Templates

Simple Stroke Counter (Background Plugin)

Settings = {
  description = "Counts total strokes in sketch"
}

local hasCountedOnce = false

function Main()
  if not hasCountedOnce then
    local sketch = App.sketch()
    local strokes = sketch:strokes()
    local count = strokes:count()
    print("Total strokes: " .. count)
    hasCountedOnce = true
  end
end

Position Logger (Background Plugin)

Settings = {
  description = "Logs user position every 2 seconds"
}

local timer = Timer:New()

function Start()
  timer:Start()
end

function Main()
  if timer:Elapsed() > 2.0 then
    local pos = User.position()
    print(string.format("User at: %.2f, %.2f, %.2f", pos.x, pos.y, pos.z))
    timer:Reset()
  end
end

Additional Resources

• API Documentation Repository: https://github.com/icosa-foundation/open-brush-plugin-scripting-docs
• Main Documentation Repository: https://github.com/icosa-foundation/open-brush-docs
• Example Plugins: Browse the LuaScriptExamples directory in the API docs repo for real-world plugin examples