PcoWSkbVqDnWTu_dm2ix
We use cookies on this site to enhance your user experience

Intro to Plugins

Intro to Plugins

Sep 26 2018, 12:47 PM PST 10 min

A plugin is a custom add-on to Studio which adds new behavior and features that are not normally included. Both the Animation Editor and Terrain Tools were originally developed as plugins. There are also many plugins made by the Roblox community that you can use to help make games and experiences. Plugins don’t have to be complicated; they can be simple tools that make your development life easier.

In this tutorial, we’ll be creating a custom plugin that will let us insert new scripts into our game without the default “Hello world!” print function.

Creating a New Plugin

While plugins can have many objects in them, they all start off as a Script. We can create this plugin script in Studio.

  1. Create a new Script in ServerStorage.
  2. Name the script EmptyScriptAdder.
  1. Right click on the script and select Save as Local Plugin….
  1. Click Save. This will insert the plugin into your plugins folder.

You may have noticed that the Studio Output window will show a message that the plugin was successfully saved. You might also have noticed “Hello world!” appears in the Output window.

That was actually our plugin running for the first time! Whenever you save a plugin in this way, all of your plugins will refresh and run. This is important, as you’ll want to refresh your plugin after you make changes to make sure that it works.

Creating a Toolbar Button

Buttons are a great way to get input from the user. Let’s change our plugin so that it adds a button to the Studio toolbar that inserts a new script into our game.

First, we need to make a toolbar to hold the button. For that, we’ll use the Plugin/CreateToolbar|Plugin:CreateToolbar() function. That function will return a toolbar object. We can then call the Toolbar/CreateButton|Toolbar:CreateButton() function of that toolbar to insert a custom button for the plugin.

  1. Open the EmptyScriptAdder script and delete print("Hello world!").
  2. Copy and paste the following code into the script:
local toolbar = plugin:CreateToolbar("Empty Script Adder")

local newScriptButton = toolbar:CreateButton("Add Script", "Create an empty Script", "rbxassetid://1507949215")
  1. Save the plugin with Save as Local Plugin…. After this you’ll see the button in the Plugins tab of Studio.
  1. The button doesn’t do anything yet, so let’s add some code to have the button create a new script. After that, we’ll use the Script/Source property to change the default content of the inserted script. Add the highlighted code to your script:
local toolbar = plugin:CreateToolbar("Empty Script Adder")

local newScriptButton = toolbar:CreateButton("Add Script", "Create an empty Script", "rbxassetid://1507949215")

local function onNewScriptButtonClicked()
	local newScript = Instance.new("Script")
	newScript.Source = ""
	newScript.Parent = game:GetService("ServerScriptService")
end

newScriptButton.Click:Connect(onNewScriptButtonClicked)
  1. Save the plugin again through Save as Local Plugin…. Now if you click the Add Script plugin button, it will insert a new script into ServerScriptService. What’s more, the new script no longer has the print("Hello world!") command at the top!

Supporting Undo/Redo

When building a plugin that makes changes to a place, it’s important to make sure that the plugin works well with the Studio undo/redo feature. Let’s look at how undo works so we can figure out how to add it to our plugin.

Undo and redo in Studio are managed by waypoints in ChangeHistoryService. After every action in Studio, such as the user dragging a part or inserting something new, Studio automatically adds a new waypoint. When you undo an action, Studio goes back to its last waypoint and undoes everything that happened after that waypoint.

The catch with plugins is that they do not add any new waypoints by default. If a plugin makes a change to a place and the user clicks Undo, Studio will go back to the last place it had a waypoint, meaning it will undo the last non-plugin action and all the things the plugin did.

All we need to do to make sure that Studio can cleanly undo our plugin’s action is:

  1. Add a local variable for ChangeHistoryService called ChangeHistoryService.
  2. Call ChangeHistoryService/SetWaypoint|SetWaypoint() in the final line of the onNewScriptButtonClicked() function.
local ChangeHistoryService = game:GetService("ChangeHistoryService")

local toolbar = plugin:CreateToolbar("Empty Script Adder")

local newScriptButton = toolbar:CreateButton("Add Script", "Create an empty Script", "rbxassetid://1507949215")

local function onNewScriptButtonClicked()
	local newScript = Instance.new("Script")
	newScript.Source = ""
	newScript.Parent = game:GetService("ServerScriptService")
	ChangeHistoryService:SetWaypoint("Adding new empty script")
end

newScriptButton.Click:Connect(onNewScriptButtonClicked)

Sharing Your Plugin

One of the best things you can do with a plugin is to share it with others! If you make a tool that helps you make games, chances are there are many others who could also use it.

There are two ways to share a plugin with others: by sending them the Lua script file, or by publishing the plugin to Roblox.

Share Plugin Locally

When you save a plugin through Save as Local Plugin…, Studio saves it to your Plugins folder automatically. If you want to share a plugin that you made, you can find the saved file there — just navigate to the Plugins tab in Studio and click Plugins Folder to open the folder with all of your locally installed plugins.

Once you open the folder, you can copy the script file for your plugin and give it to others. They can then place the script file into their own Plugins folder.

Publish to Roblox

Just like places and models, plugins can be published to Roblox to make them easy to share and install. To publish a plugin:

  1. Right-click on the plugin script in Studio and select Publish as Plugin….
  2. Publish to a new slot or update one of your existing plugins.
  3. Enter a name and description for the plugin.
  4. Click Finish. Once the plugin has finished publishing, you’ll be given a link which you can share with anyone you want to have the plugin.

To install a plugin from the linked page:

  1. Click the Install button on the page. This will launch Studio where you’ll see another prompt to install.
  2. Click the Install button in Studio. This will install the plugin and refresh all of your plugins. Once this is done, the plugin is ready to use!

Managing Installed Plugins

At some point you may want to deactivate or even remove plugins. You can do this in the Manage Plugins view of Studio. This is also where you can update plugins.

  1. Find Plugins — Find new plugins to install.
  2. Active — Toggles whether the plugin is active or not.
  3. Remove — Uninstalls the plugin.
  4. Update — Gets the latest version of the plugin.

Other Plugin Examples

Insert Empty Folder

Many plugins use the Selection service to find out what objects the user has selected. The following script introduces a new button that checks if the user has anything selected and, if so, adds a folder to that selection.

local ChangeHistoryService = game:GetService("ChangeHistoryService")
local Selection = game:GetService("Selection")

local toolbar = plugin:CreateToolbar("Folder Tools")
local createFolderButton = toolbar:CreateButton("Create Folder", "Create a new folder", "rbxassetid://1581292991")

local function onCreateFolder()
    local selectedObjects = Selection:Get()
    local parent = game.Workspace
    if #selectedObjects > 0 then
        local firstSelection = selectedObjects[1]
        parent = firstSelection
    end

    local newFolder = Instance.new("Folder")
    newFolder.Parent = parent

    Selection:Set({newFolder})

    ChangeHistoryService:SetWaypoint("Adding new folder")
end

createFolderButton.Click:Connect(onCreateFolder)
Tags:
  • ui
  • coding