Plugin

Show Deprecated
Not Creatable

Plugin is the main object responsible for creating basic studio widgets. It is a custom add-on to Studio which adds new behavior and features that are not normally included.

Summary

Properties

Returns whether the user enabled Collisions in studio under the Model tab.

READ ONLY
NOT REPLICATED

Returns the grid size the user has set in studio under the Model tab.

READ ONLY
NOT REPLICATED
HIDDEN
READ ONLY
NOT REPLICATED
HIDDEN
READ ONLY
NOT REPLICATED
HIDDEN
NOT REPLICATED

Events


Fired when the plugin is deactivated.


Fires immediately before the Plugin stops running.

Methods

Activate(exclusiveMouse: boolean): void  

Sets the state of the calling plugin to activated.

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 Button.


Creates a new plugin menu.


Creates a new PluginToolbar with the given name.

Deactivate(): void  

Deactivates the plugin.

GetItem(key: string, defaultValue: Variant): Variant  



Returns the 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 RibbonTool.


Retrieves a previously stored value with the given key, or nil if the given key doesn't exist.

Invoke(key: string, arguments: Tuple): void  



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.

Negate(objects: Objects): Objects  

Negates the given parts and returns the resulting NegateOperations.

OnInvoke(key: string, callback: function): Instance  


OnSetItem(key: string, callback: function): Instance  


OpenScript(script: LuaSourceContainer, lineNumber: number): void  

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.

OpenWikiPage(url: string): void  

Opens the context help window to the wiki page that url links to.

PauseSound(sound: Instance): void  


PlaySound(sound: Instance, normalizedTimePosition: number): void  


ResumeSound(sound: Instance): void  



Opens an upload window for the user's current selection.

SelectRibbonTool(tool: RibbonTool, position: UDim2): void  

Activates the specified Roblox Studio tool.

Separate(objects: Objects): Objects  

Separates the given UnionOperations and returns the resulting parts.

SetItem(key: string, value: Variant): void  


SetReady(): void  


SetSetting(key: string, value: Variant): void  

Stores a given value for later use under the given key. The value will persist even after studio is closed.

StartDecalDrag(decal: Instance): void  


StartDrag(dragData: table): void  

Starts a drag action given a dictionary of parameters.

StopAllSounds(): void  


Union(objects: Objects): Instance  

Unions the given parts and returns the resulting UnionOperation.

CreateQWidgetPluginGui(pluginGuiId: string, pluginGuiOptions: table): QWidgetPluginGui  YIELDS


ImportFbxAnimation(rigModel: Instance, isR15: boolean): Instance  YIELDS

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.

ImportFbxRig(isR15: boolean): Instance  YIELDS

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.

PromptForExistingAssetId(assetType: string): number  YIELDS

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.

PromptSaveSelection(suggestedFileName: string): boolean  YIELDS

Prompts the user to save their current selection with the specified file name. Returns true if the user did save the file.

Callbacks

ProcessAssetInsertionDrag(assetId: string, assetTypeId: number, instances: Objects)  NO YIELD


Properties

CollisionEnabled

Read Only
Not Replicated

Returns whether the user enabled Collisions in studio under the Model tab.

GridSize

Read Only
Not Replicated

Returns the grid size the user has set in studio under the Model tab. This can be 1, 0.2 or 0.01, but has rounding errors. The 1/5th option should return 0.2, but could return 0.20000000298023 instead. This code can be used to get the real gridsize:


1local gridsize = plugin.GridSize
2if math.abs(gridsize-0.2) < 0.005 then -- Check if the gridsize is between 0.195 and 0.205
3 gridsize = 0.2
4elseif math.abs(gridsize-0.01) < 0.005 then -- Between 0.005 and 0.015
5 gridsize = 0.01
6else -- Assume it's 1
7 gridsize = 1
8end
9

HostDataModelType

Hidden
Read Only
Not Replicated

HostDataModelTypeIsCurrent

Hidden
Read Only
Not Replicated

MultipleDocumentInterfaceInstance

Hidden
Read Only
Not Replicated

UsesAssetInsertionDrag

Hidden
Not Replicated

Events

Deactivation

Plugin Security

Fired when the Plugin is deactivated. This occurs when either the plugin code calls Plugin:Deactivate(), or because some other plugin called Plugin:Activate(), which forces all other plugins to lose their active state.

See also:

  • Plugin.Unloading, fires immediately before the plugin is unloaded or reloaded via uninstallation, deactivation, or updating

Ready

Roblox Script Security

Unloading

Plugin Security

This event fires immediately before the Plugin stops running. Plugins are unloaded when disabled, uninstalled, about to be updated, or when the place is closing.

It enables a plugin to clean up after itself before its scripts stop running, e.g. to remove unnecessary instances from the DataModel. If a plugin does not clean up properly, the old copies will remain. When this occurs, users may be forced to close and reopen the place which is a bad user experience.

Plugin-related instances such as PluginToolbarButtons, DockWidgetPluginGuis, and PluginGuis are automatically cleaned up when the plugin is unloaded so there is no need to remove them.


Methods

Activate

void
Plugin Security

This function sets the state of the calling plugin to activated. Activating the plugin allows mouse control through the Plugin:GetMouse() method.

At any given time there are either 0 or 1 Activated Plugins. Activating a plugin will deactivate all other plugins (they will receive a Plugin.Deactivation event).

See also:

  • Plugin:IsActivatedWithExclusiveMouse(), returns true if this plugin is currently active with an exclusive mouse, after having been activated via this function
  • Plugin.Unloading, fires immediately before the plugin is unloaded or reloaded via uninstallation, deactivation, or updating

Parameters

exclusiveMouse: boolean

A boolean specifying whether to activate the plugin with exclusive mouse. If true, a PluginMouse can be retrieved via Plugin:GetMouse().


Returns

void

No return.

CreatePluginAction

Plugin Security

This function creates a PluginAction which is an object that represents a generic performable action in Roblox Studio, with no directly associated Toolbar or Button. In Roblox Studio, they can be assigned a keyboard shortcut under File → Advanced → Customize Shortcuts…, and they can also be added to the Quick Access Toolbar.

When an action is triggered, the PluginAction.Triggered event is signaled.

In order for PluginActions work as expected, they must be created using this function.

See also:

Parameters

actionId: string

Must be a unique string that identifies this PluginAction from others.

text: string

The displayed name of the action.

statusTip: string

The displayed description of the action.

iconName: string

The name of the icon used to display the plugin.

Default Value: ""
allowBinding: boolean

Whether the PluginAction will be hidden from Studio's shortcuts view. Useful for contextual actions. Defaults to true.

Default Value: "true"

Code Samples

Creating a PluginAction

1local plugin = plugin or getfenv().PluginManager():CreatePlugin()
2plugin.Name = "Plugin"
3
4local function actionTriggered()
5 print("Hello world!")
6end
7
8local pluginAction = plugin:CreatePluginAction(
9 "HelloWorldAction",
10 "Hello World",
11 "Prints a 'Hello world!'",
12 "bxasset://textures/sparkle.png",
13 true
14)
15
16pluginAction.Triggered:Connect(actionTriggered)

CreatePluginMenu

Plugin Security

This function creates a new PluginMenu, which is a context menu that can be shown in Studio that displays a list of PluginActions and supports submenus.

In order for PluginMenus to work as expected, they must be created using this function.

See also:

Parameters

id: string

Unique ID for the menu.

title: string

The text to be displayed when used as a sub menu.

Default Value: ""
icon: string

The icon to be displayed when used as a sub menu.

Default Value: ""

Returns

Code Samples

Creating a PluginMenu and PluginMenuAction

1-- This code can be pasted into the command bar, but only once.
2
3local plugin = plugin or getfenv().PluginManager():CreatePlugin()
4plugin.Name = "Plugin"
5plugin.Parent = workspace
6
7local pluginMenu = plugin:CreatePluginMenu(math.random(), "Test Menu")
8pluginMenu.Name = "Test Menu"
9
10pluginMenu:AddNewAction("ActionA", "A", "rbxasset://textures/loading/robloxTiltRed.png")
11pluginMenu:AddNewAction("ActionB", "B", "rbxasset://textures/loading/robloxTilt.png")
12
13local subMenu = plugin:CreatePluginMenu(math.random(), "C", "rbxasset://textures/explosion.png")
14subMenu.Name = "Sub Menu"
15
16subMenu:AddNewAction("ActionD", "D", "rbxasset://textures/whiteCircle.png")
17subMenu:AddNewAction("ActionE", "E", "rbxasset://textures/icon_ROBUX.png")
18
19pluginMenu:AddMenu(subMenu)
20pluginMenu:AddSeparator()
21
22pluginMenu:AddNewAction("ActionF", "F", "rbxasset://textures/sparkle.png")
23
24local toggle = Instance.new("BoolValue")
25toggle.Name = "TogglePluginMenu"
26toggle.Parent = workspace
27
28local function onToggled()
29 if toggle.Value then
30 toggle.Value = false
31
32 local selectedAction = pluginMenu:ShowAsync()
33 if selectedAction then
34 print("Selected Action:", selectedAction.Text, "with ActionId:", selectedAction.ActionId)
35 else
36 print("User did not select an action!")
37 end
38 end
39end
40
41toggle.Changed:Connect(onToggled)

CreateToolbar

Plugin Security

The CreateToolbar function creates a new PluginToolbar with the given name. The toolbar can then be used to create plugin buttons.

Parameters

name: string

The visible text on the toolbar, labeling the group of buttons contained within.


Code Samples

Plugin:CreateToolbar

1plugin:CreateToolbar("ExampleToolbar")

Deactivate

void
Plugin Security

Deactivates the plugin. This will disengage the associated PluginMouse if it has been activated

See also:


Returns

void

No return.

GetItem

Roblox Script Security

Parameters

key: string
defaultValue: Variant

Returns

Plugin Security

Returns the JointCreationMode the user has set in studio under the Model tab.


GetMouse

Plugin Security

GetMouse returns a PluginMouse that can be used while the plugin is active through Plugin:Activate().


Code Samples

Plugin:GetMouse

1local mouse = plugin:GetMouse()
2
3local function button1Down()
4 print("Button 1 pressed from PluginMouse")
5end
6
7mouse.Button1Down:Connect(button1Down)

GetSelectedRibbonTool

Plugin Security

GetSelectedRibbonTool return the currently selected RibbonTool. It returns an Enum that corresponds to a particular tool. This will return whether the tool is selected manually or programmatically via Plugin:SelectRibbonTool().


Returns

Code Samples

Plugin:GetSelectedRibbonTool

1plugin:SelectRibbonTool(Enum.RibbonTool.Move, UDim2.new())
2task.wait() -- wait for next frame
3local selectedRibbonTool = plugin:GetSelectedRibbonTool()
4print("The selected RibbonTool is", selectedRibbonTool)

GetSetting

Plugin Security

Retrieves a previously stored value with the given key, or nil if the given key doesn't exist.

Parameters

key: string

Returns

Code Samples

Plugin:GetSetting

1local RAN_BEFORE_KEY = "RanBefore"
2local didRunBefore = plugin:GetSetting(RAN_BEFORE_KEY)
3
4if didRunBefore then
5 print("Welcome back!")
6else
7 plugin:SetSetting(RAN_BEFORE_KEY, true)
8 print("Welcome! Thanks for installing this plugin!")
9end

Invoke

void
Roblox Script Security

Parameters

key: string
arguments: Tuple

Returns

void

IsActivated

Plugin Security

This function returns true if this plugin is currently active, after having been activated via the Plugin:Activate() function.


Returns

A boolean indicating whether the plugin is currently active.

IsActivatedWithExclusiveMouse

Plugin Security

This function returns true if this plugin is currently active with an exclusive mouse, after having been activated via the Plugin:Activate() function. If this returns true, a PluginMouse can be retrieved via Plugin:GetMouse().

See also:

  • Plugin.Deactivation, fires when the plugin is deactivated
  • Plugin.Unloading, fires immediately before the plugin is unloaded or reloaded via uninstallation, deactivation, or updating

Returns

Whether this plugin is currently active with an exclusive mouse.

Negate

Plugin Security

Negates the given parts and returns the resulting NegateOperations.

Parameters

objects: Objects

Returns

OnInvoke

Roblox Script Security

Parameters

key: string
callback: function

Returns

OnSetItem

Roblox Script Security

Parameters

key: string
callback: function

Returns

OpenScript

void
Plugin Security

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.

Parameters

lineNumber: number
Default Value: "1"

Returns

void

Code Samples

Plugin:OpenScript

1local newScript = Instance.new("Script")
2newScript.Parent = workspace
3plugin:OpenScript(newScript)

OpenWikiPage

void
Plugin Security

Opens the context help window to the wiki page that url links to.

Parameters

url: string

Returns

void

Code Samples

Plugin:OpenWikiPage

1plugin:OpenWikiPage("API:Class/BasePart")

PauseSound

void
Roblox Script Security

Parameters

sound: Instance

Returns

void

PlaySound

void
Roblox Script Security

Parameters

sound: Instance
normalizedTimePosition: number
Default Value: "0"

Returns

void

ResumeSound

void
Roblox Script Security

Parameters

sound: Instance

Returns

void

SaveSelectedToRoblox

void
Plugin Security

Opens an upload window for the user's current selection.


Returns

void

SelectRibbonTool

void
Plugin Security

Activates the specified Roblox Studio tool. If the tool opens a window, the position parameter specifies where it should be shown on the screen.

Note:

  • An object must be selected in order for this to work correctly.
  • Altering the scale fields of the position property will not affect the dialog popups.

Parameters

position: UDim2

Returns

void

Separate

Plugin Security

Separates the given UnionOperations and returns the resulting parts.

Parameters

objects: Objects

Returns

SetItem

void
Roblox Script Security

Parameters

key: string
value: Variant

Returns

void

SetReady

void
Roblox Script Security

Returns

void

SetSetting

void
Plugin Security

Stores a given value for later use under the given key. The value will persist even after studio is closed.

Parameters

key: string
value: Variant

Returns

void

Code Samples

Plugin:GetSetting and Plugin:SetSetting

1local RAN_BEFORE_KEY = "RunBefore"
2local hasRunBefore = plugin:GetSetting(RAN_BEFORE_KEY)
3
4if hasRunBefore then
5 print("Welcome back!")
6else
7 print("Thanks for installing this plugin!")
8 plugin:SetSetting(RAN_BEFORE_KEY, true)
9end

StartDecalDrag

void
Roblox Script Security

Parameters

decal: Instance

Returns

void

StartDrag

void
Plugin Security

StartDrag initiates a drag action using a dictionary of parameters. The parameters are as follows:

NameTypeDefaultDescription
Senderstring"" Identifies the source of the drag action to the drop target
MimeTypestring"" The MIME type of Data.
Datastring"" Information about the drag action (eg. what is being dragged). Should be used by the drop target.
MouseIconContent"" The icon to use for the mouse cursor during the drag. If empty, uses the default cursor.
DragIconContent"" An image to render under the mouse cursor during the drag. This should represent the item being dragged.
HotSpotVector2Vector2.new(0, 0) The pixel offset from the top-left where the cursor should "hold" the DragIcon.

See also:

Parameters

dragData: table

Returns

void

Code Samples

Plugin Drag and Drop

1assert(plugin, "This script must be run as a Studio plugin")
2
3local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
4
5local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Drag Source", widgetInfo)
6dragSourceWidget.Title = "Drag Source"
7
8local textBox = Instance.new("TextBox")
9textBox.Parent = dragSourceWidget
10textBox.Size = UDim2.new(1, 0, 0, 32)
11textBox.Text = "Hello, plugin drags"
12
13local dragButton = Instance.new("TextButton")
14dragButton.Size = UDim2.new(1, 0, 1, -32)
15dragButton.Position = UDim2.new(0, 0, 0, 32)
16dragButton.Text = "Edit the text above, then start drag here"
17dragButton.Parent = dragSourceWidget
18
19function onMouseButton1Down()
20 local dragData = {
21 Sender = "SomeDragSource",
22 MimeType = "text/plain",
23 Data = textBox.Text,
24 MouseIcon = "",
25 DragIcon = "",
26 HotSpot = Vector2.new(0, 0),
27 }
28 plugin:StartDrag(dragData)
29end
30
31dragButton.MouseButton1Down:Connect(onMouseButton1Down)
32
33-- This widget will receive drops
34local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Drop Target", widgetInfo)
35dragTargetWidget.Title = "Drop Target"
36
37-- This TextLabel will display what was dropped
38local textLabel = Instance.new("TextLabel")
39textLabel.Size = UDim2.new(1, 0, 1, 0)
40textLabel.Text = "Drop here..."
41textLabel.Parent = dragTargetWidget
42
43local function onDragDrop(dragData)
44 if dragData.MimeType == "text/plain" then
45 textLabel.Text = dragData.Data
46 else
47 textLabel.Text = dragData.MimeType
48 end
49end
50
51dragTargetWidget.PluginDragDropped:Connect(onDragDrop)
52
53dragTargetWidget.PluginDragEntered:Connect(function(_dragData)
54 print("PluginDragEntered")
55end)
56
57dragTargetWidget.PluginDragLeft:Connect(function(_dragData)
58 print("PluginDragLeft")
59end)
60
61dragTargetWidget.PluginDragMoved:Connect(function(_dragData)
62 print("PluginDragMoved")
63end)

StopAllSounds

void
Roblox Script Security

Returns

void
Plugin Security

Unions the given parts and returns the resulting UnionOperation.

Parameters

objects: Objects

Returns

CreateDockWidgetPluginGui

Yields
Plugin Security

CreateDockWidgetPluginGui creates a new DockWidgetPluginGui from the given DockWidgetPluginGuiInfo. The first parameter, pluginGuiId, should be a unique and consistent string. It is used to save the state of the widget's dock state and other internal details.

Parameters

pluginGuiId: string

A unique and consistent identifier used to storing the widget's dock state and other internal details.

dockWidgetPluginGuiInfo: DockWidgetPluginGuiInfo

Describes the DockWidgetPluginGui to create (initial state, size, etc).


Code Samples

Widget GUI Text Button

1-- Create new 'DockWidgetPluginGuiInfo' object
2local widgetInfo = DockWidgetPluginGuiInfo.new(
3 Enum.InitialDockState.Float, -- Widget will be initialized in floating panel
4 true, -- Widget will be initially enabled
5 false, -- Don't override the previous enabled state
6 200, -- Default width of the floating window
7 300, -- Default height of the floating window
8 150, -- Minimum width of the floating window (optional)
9 150 -- Minimum height of the floating window (optional)
10)
11
12-- Create new widget GUI
13local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
14
15local testButton = Instance.new("TextButton")
16testButton.BorderSizePixel = 0
17testButton.TextSize = 20
18testButton.TextColor3 = Color3.new(1, 0.2, 0.4)
19testButton.AnchorPoint = Vector2.new(0.5, 0.5)
20testButton.Size = UDim2.new(1, 0, 1, 0)
21testButton.Position = UDim2.new(0.5, 0, 0.5, 0)
22testButton.SizeConstraint = Enum.SizeConstraint.RelativeYY
23testButton.Text = "Click Me"
24testButton.Parent = testWidget

CreateQWidgetPluginGui

Yields
Roblox Script Security

Parameters

pluginGuiId: string
pluginGuiOptions: table

ImportFbxAnimation

Yields
Plugin Security

This function 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.

Parameters

rigModel: Instance
isR15: boolean
Default Value: "true"

Returns

ImportFbxRig

Yields
Plugin Security

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.

Parameters

isR15: boolean
Default Value: "true"

Returns

PromptForExistingAssetId

Yields
Plugin Security

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.

Parameters

assetType: string

Returns

PromptSaveSelection

Yields
Plugin Security

Prompts the user to save their current selection with the specified file name. Returns true if the user did save the file.

Parameters

suggestedFileName: string
Default Value: ""

Returns

Callbacks

ProcessAssetInsertionDrag

No Yield
Roblox Script Security

Parameters

assetId: string
assetTypeId: number
instances: Objects

Returns

ProcessAssetInsertionDrop

void
No Yield
Roblox Script Security

Returns

void