fusion-plugin

Build powerful plugins for Roblox Studio with Fusion, a modern reactivity library for Roblox Luau.

Table of Contents

• Installation
• Usage
  • Dockable Widgets
  • Toolbars
  • Plugin Actions
  • Plugin Menus
• Example
• Contribution
• License

Installation

fusion-plugin is available on the wally package manager. Copy the install string from the project page and paste it into your wally.toml. Then, run wally install.

Usage

Everything you'll need is available in the module. You acquire it like so, providing the appropriate ModuleScripts:

local Fusion = require(...)
-- .Value, .Computed, .New

local FusionPlugin = require(...)(Fusion, plugin)
-- .DockWidget, .Toolbar, .ToolbarButton

You must call the required result, passing in your Fusion and plugin context. This is necessary because automatic dependency capturing only works on reactive objects from the same Fusion instance.^{[citation needed]}

Dockable Widgets

Dockable widgets are exposed through a function called DockWidget. Here's an example of what a settings panel might look like:

local DockWidget = FusionPlugin.DockWidget

local open = Value(false) --whether the dockable is open or not

DockWidget "examplePluginSettings" {
    Title = "Example Plugin Settings",
    Enabled = open,
    [Out "Enabled"] = open,
    [Children] = ... --mount panel root component

    -- NON-REACTIVE
    Size = Vector2.new(400, 300),
    MinimumSize = Vector2.new(100, 100), --Defaults to .Size
}

Note how some props are not reactive due to the immutability of DockWidgetPluginGuiInfo.

Toolbars

Toolbars can be elegantly expressed with two functions, as so:

local Toolbar = FusionPlugin.Toolbar
local ToolbarButton = FusionPlugin.ToolbarButton

Toolbar "Example Plugin" {
    ToolbarButton "settings" {
        Active = ..., --whether the button is shaded gray
        ClickableWhenViewportHidden = true,
        [OnEvent "Click"] = function()
            print("TODO: open example plugin settings widget")
        end,

        -- NON-REACTIVE
        Text = "Settings",
        Tooltip = "Open example plugin's settings",
        Icon = "rbxassetid://4458900760",
    }
}

Note how some props are not reactive due to the immutability of PluginToolbar:CreateButton()'s arguments.

Plugin Actions

Plugin actions are declared with the function Action: ``

local Action = FusionPlugin.Action

Action "coolaction" {
    Bindable = true, --whether this action should be visible in the keybinds window
    Icon = image,
    Text = "Cool Action",
    Tooltip = "this means only good things",

    [OnEvent "Triggered"] = function()
        print("cool things underway.......")
    end,
}

Plugin Menus

PluginMenus are not yet supported. Feel free to contribute an implementation.

Example

A comprehensive sample file has been written for your reference. Build commands can be found in the vscode tasks.json file.

Contribution

File an issue if you encounter a bug. Pull requests for bugfixes and improvements are welcome.

License

This library is licensed under the MIT License.