Plugin
Plugin is the main object responsible for creating basic Studio widgets, plugin toolbars, plugin buttons, and more. It is a custom add-on to Studio which adds new behavior and features that are not normally included. The Plugin object can be accessed through the plugin global reference in a Script that is executed as a plugin.
Code Samples
The plugin global reference is not passed to ModuleScripts within the plugin. In order to use it in a ModuleScript, you must explicitly pass it as seen in the example below.
assert(plugin, "This script must be run as a plugin!")
-- Code beyond this point will execute only if the script is run as a plugin
-- Load the module and pass the plugin reference
local pluginModule = require(script.Parent.PluginModule)
pluginModule:Initialize(plugin)
-- Verify if the plugin reference was initialized
pluginModule:CheckForPluginGlobal()
local pluginModule = {}
local plugin -- Local plugin reference
-- Initialize the plugin reference if not already set
function pluginModule:Initialize(pluginReference: Plugin)
if plugin ~= pluginReference then
plugin = pluginReference
else
error("Plugin is already initialized")
end
end
-- Check if the plugin reference is set and print out appropriate info
function pluginModule:CheckForPluginGlobal()
if plugin ~= nil then
print("Plugin reference is set!")
else
warn("Plugin reference is missing!")
end
end
return pluginModule
Summary
Properties
Returns whether the user enabled Collisions in Studio under the Model tab.
Returns the grid snapping size the user has set in Studio.
Methods
Sets the state of the calling plugin to activated.
- CreateDockWidgetPluginGui(pluginGuiId : string,dockWidgetPluginGuiInfo : DockWidgetPluginGuiInfo):DockWidgetPluginGui
Creates a DockWidgetPluginGui given a DockWidgetPluginGuiInfo.
- CreatePluginAction(actionId : string,text : string,statusTip : string,iconName : string,allowBinding : boolean):PluginAction
Creates a PluginAction which is an object that represents a generic performable action in Roblox Studio, with no directly associated Toolbar or Enum.Button.
Creates a new plugin menu.
Creates a new PluginToolbar with the given name.
Deactivates the plugin.
Returns the Enum.JointCreationMode the user has set in Studio under the Model tab.
Returns a Mouse that can be used while the plugin is active.
Returns the currently selected Enum.RibbonTool.
Retrieves a previously stored value with the given key, or nil if the given key doesn't exist.
Prompts the user to open a .fbx animation file that can be loaded onto the rigModel, then proceeds to insert the animation as a KeyframeSequence in the Workspace.
Prompts the user to open a .fbx file, uploads the individual components of the model as meshes, and generates a character rig for use in animation, which is loaded into the Workspace.
Returns true if this plugin is currently active, after having been activated via the Plugin:Activate() function.
Returns true if this plugin is currently active with an exclusive mouse, after having been activated via the Plugin:Activate() function.
Negates the given parts and returns the resulting NegateOperations.
Used to open the given script instance in an editor window, in Roblox studio, at the given line. If no line is given as an argument it will default to 1.
Opens the context help window to the wiki page that url links to.
Opens a window in Roblox Studio, which prompts the user to select an asset based on the assetType specified. Returns what assetId was selected, or -1 if the window was closed.
Prompts the user to save their current selection with the specified file name. Returns true if the user did save the file.
Opens an upload window for the user's current selection.
Activates the specified Roblox Studio tool.
Separates the given UnionOperations and returns the resulting parts.
Stores a given value for later use under the given key. The value will persist even after Studio is closed.
Starts a drag action given a dictionary of parameters.
Unions the given parts and returns the resulting UnionOperation.
Events
Fired when the plugin is deactivated.
Fires immediately before the Plugin stops running.
Properties
Methods
CreateDockWidgetPluginGui
Parameters
Returns
Code Samples
-- Create new 'DockWidgetPluginGuiInfo' object
local widgetInfo = DockWidgetPluginGuiInfo.new(
Enum.InitialDockState.Float, -- Widget will be initialized in floating panel
true, -- Widget will be initially enabled
false, -- Don't override the previous enabled state
200, -- Default width of the floating window
300, -- Default height of the floating window
150, -- Minimum width of the floating window (optional)
150 -- Minimum height of the floating window (optional)
)
-- Create new widget GUI
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
local testButton = Instance.new("TextButton")
testButton.BorderSizePixel = 0
testButton.TextSize = 20
testButton.TextColor3 = Color3.new(1, 0.2, 0.4)
testButton.AnchorPoint = Vector2.new(0.5, 0.5)
testButton.Size = UDim2.new(1, 0, 1, 0)
testButton.Position = UDim2.new(0.5, 0, 0.5, 0)
testButton.SizeConstraint = Enum.SizeConstraint.RelativeYY
testButton.Text = "Click Me"
testButton.Parent = testWidget
CreatePluginAction
Parameters
Returns
Code Samples
local pluginAction = plugin:CreatePluginAction(
"HelloWorldAction",
"Hello World",
"Prints a 'Hello world!'",
"rbxasset://textures/sparkle.png",
true
)
pluginAction.Name = "Test Action"
local function actionTriggered()
print("Hello world!")
end
pluginAction.Triggered:Connect(actionTriggered)
CreatePluginMenu
Parameters
Returns
Code Samples
-- This code can be pasted into the command bar, but only once
local pluginMenu = plugin:CreatePluginMenu(math.random(), "Test Menu")
pluginMenu.Name = "Test Menu"
pluginMenu:AddNewAction("ActionA", "A", "rbxasset://textures/loading/robloxTiltRed.png")
pluginMenu:AddNewAction("ActionB", "B", "rbxasset://textures/loading/robloxTilt.png")
local subMenu = plugin:CreatePluginMenu(math.random(), "C", "rbxasset://textures/explosion.png")
subMenu.Name = "Sub Menu"
subMenu:AddNewAction("ActionD", "D", "rbxasset://textures/whiteCircle.png")
subMenu:AddNewAction("ActionE", "E", "rbxasset://textures/icon_ROBUX.png")
pluginMenu:AddMenu(subMenu)
pluginMenu:AddSeparator()
pluginMenu:AddNewAction("ActionF", "F", "rbxasset://textures/sparkle.png")
local toggle = Instance.new("BoolValue")
toggle.Name = "TogglePluginMenu"
toggle.Parent = workspace
local function onToggled()
if toggle.Value then
toggle.Value = false
local selectedAction = pluginMenu:ShowAsync()
if selectedAction then
print("Selected Action:", selectedAction.Text, "with ActionId:", selectedAction.ActionId)
else
print("User did not select an action!")
end
end
end
toggle.Changed:Connect(onToggled)
CreateToolbar
Parameters
Returns
Code Samples
plugin:CreateToolbar("ExampleToolbar")
Deactivate
Returns
GetMouse
Returns
Code Samples
local mouse = plugin:GetMouse()
local function button1Down()
print("Button 1 pressed from PluginMouse")
end
mouse.Button1Down:Connect(button1Down)
GetSelectedRibbonTool
Returns
Code Samples
plugin:SelectRibbonTool(Enum.RibbonTool.Move, UDim2.new())
task.wait() -- wait for next frame
local selectedRibbonTool = plugin:GetSelectedRibbonTool()
print("The selected RibbonTool is", selectedRibbonTool)
GetSetting
Parameters
Returns
Code Samples
local RAN_BEFORE_KEY = "RanBefore"
local didRunBefore = plugin:GetSetting(RAN_BEFORE_KEY)
if didRunBefore then
print("Welcome back!")
else
plugin:SetSetting(RAN_BEFORE_KEY, true)
print("Welcome! Thanks for installing this plugin!")
end
ImportFbxAnimation
Parameters
Returns
Negate
Parameters
Returns
OpenScript
Parameters
Returns
Code Samples
local newScript = Instance.new("Script")
newScript.Parent = workspace
plugin:OpenScript(newScript)
OpenWikiPage
Parameters
Returns
Code Samples
plugin:OpenWikiPage("API:Class/BasePart")
SaveSelectedToRoblox
Returns
Separate
Parameters
Returns
SetSetting
Parameters
Returns
Code Samples
local RAN_BEFORE_KEY = "RunBefore"
local hasRunBefore = plugin:GetSetting(RAN_BEFORE_KEY)
if hasRunBefore then
print("Welcome back!")
else
print("Thanks for installing this plugin!")
plugin:SetSetting(RAN_BEFORE_KEY, true)
end
StartDrag
Parameters
Returns
Code Samples
assert(plugin, "This script must be run as a Studio plugin")
local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Drag Source", widgetInfo)
dragSourceWidget.Title = "Drag Source"
local textBox = Instance.new("TextBox")
textBox.Parent = dragSourceWidget
textBox.Size = UDim2.new(1, 0, 0, 32)
textBox.Text = "Hello, plugin drags"
local dragButton = Instance.new("TextButton")
dragButton.Size = UDim2.new(1, 0, 1, -32)
dragButton.Position = UDim2.new(0, 0, 0, 32)
dragButton.Text = "Edit the text above, then start drag here"
dragButton.Parent = dragSourceWidget
function onMouseButton1Down()
local dragData = {
Sender = "SomeDragSource",
MimeType = "text/plain",
Data = textBox.Text,
MouseIcon = "",
DragIcon = "",
HotSpot = Vector2.new(0, 0),
}
plugin:StartDrag(dragData)
end
dragButton.MouseButton1Down:Connect(onMouseButton1Down)
-- This widget will receive drops
local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Drop Target", widgetInfo)
dragTargetWidget.Title = "Drop Target"
-- This TextLabel will display what was dropped
local textLabel = Instance.new("TextLabel")
textLabel.Size = UDim2.new(1, 0, 1, 0)
textLabel.Text = "Drop here..."
textLabel.Parent = dragTargetWidget
local function onDragDrop(dragData)
if dragData.MimeType == "text/plain" then
textLabel.Text = dragData.Data
else
textLabel.Text = dragData.MimeType
end
end
dragTargetWidget.PluginDragDropped:Connect(onDragDrop)
dragTargetWidget.PluginDragEntered:Connect(function(_dragData)
print("PluginDragEntered")
end)
dragTargetWidget.PluginDragLeft:Connect(function(_dragData)
print("PluginDragLeft")
end)
dragTargetWidget.PluginDragMoved:Connect(function(_dragData)
print("PluginDragMoved")
end)