插件 是负责创建基本 Studio widget、插件工具栏、插件按钮等的主要对象。它是为 Studio 添加的自定义附加组件,添加了不通常包含的新行为和功能。插件 对象可以通过在 中执行为插件的全球参考访问。
代码示例
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
概要
属性
返回用户在模型选项卡下是否启用了 Collisions 。
返回用户在工作室设置的网格捕捉尺寸。
方法
将调用插件的状态设置为激活。
- CreatePluginAction(actionId : string,text : string,statusTip : string,iconName : string,allowBinding : boolean):PluginAction
创建一个 PluginAction ,这是一个在 Roblox Studio 中代表通用执行行动的对象,没有直接关联的 Toolbar 或 Enum.Button 。
创建一个新的插件菜单。
创建一个新的 PluginToolbar 与给定的名称。
禁用插件。
返回用户在工作室中设置在模型选项卡下的 Enum.JointCreationMode。
返回一个 Mouse 可在插件激活时使用的返回值。
返回当前选择的 Enum.RibbonTool 。
使用给定的键检索以前存储的值,或 nil 如果给定的键不存在。
如果此插件当前已激活,通过 Plugin:Activate() 函数激活后,返回真值。
如果此插件当前激活并拥有专属鼠标,在激活过程中通过 Plugin:Activate() 函数激活后,返回真值。
否定给定的部分,并返回结果的否定操作。
用于在编辑器窗口中打开指定的脚本实例,在 Roblox 工作室中,在指定行。如果没有线作为参数提供,它将默认为 1。
打开上下文帮助窗口到那个 wiki 页面,该页面上有 url 链接。
打开用户当前选择的上传窗口。
激活指定的 Roblox Studio 工具。
分离给定的联合操作,返回结果的零件。
存储给定值以便在指定的键下使用。值将在 Studio 关闭后仍然存在。
启动给出参数字典的拖动操作。
将给定的部件联合并返回结果的联合操作。
- CreateDockWidgetPluginGui(pluginGuiId : string,dockWidgetPluginGuiInfo : DockWidgetPluginGuiInfo):DockWidgetPluginGui
创建一个 DockWidgetPluginGui ,给予一个 DockWidgetPluginGuiInfo .
提示用户打开一个 .fbx 动画文件,可以加载到 ,然后继续将动画插入 中。
提示用户打开 .fbx 文件,上传模型的个体组件作为网格,生成用于动画中使用的角色骨架,该骨架被加载到 Workspace 中。
在 Roblox Studio 中打开一个窗口,提示用户根据指定的 assetType 选择资产。返回选择了哪个资产ID,或关闭窗口时 -1。
提示用户保存当前选择与指定的文件名称。如果用户保存了文件,返回真值。
属性
方法
Activate
这个函数将调用插件的状态设置为激活。激活插件通过 Plugin:GetMouse() 方法实现鼠标控制。
在任何时候,有 0 或 1 个激活插件。激活插件会禁用所有其他插件(它们将收到一个 Plugin.Deactivation 事件)。
还见:
- Plugin:IsActivatedWithExclusiveMouse() , 如果此插件当前激活并拥有专属鼠标,通过此函数激活后返回真值
- Plugin.Unloading , 在插件通过卸载或重新加载而被禁用或更新之前立即发生火灾
参数
一个用于确定是否启用插件专用鼠标的 boolean 参数。如果为 true,那么 PluginMouse 可以通过 Plugin:GetMouse() 来检索。
返回
CreatePluginAction
这个函数创建了一个 PluginAction ,这是一个在 Roblox Studio 中代表通用执行行动的对象,没有直接关联的 Toolbar 或 Enum.Button 。在 Roblox Studio 中,它们可以在 File → Advanced → Customize Shortcuts… 下分配键盘快捷键,还可以添加到快速访问工具栏。
当触发一个行动时,PluginAction.Triggered事件被警告。
为了使插件操作按预期工作,它们必须使用此函数创建。
还见:
- PluginMenu , 可以在 Studio 中显示的上下文菜单,显示一个列表的插件操作并支持子菜单
- Plugin:CreatePluginMenu() , 创建一个插件菜单
参数
必须是唯一的字符串,用于从其他插件行动中识别此插件行动。
行动作的显示名称。
动作动的显示描述。
用于显示插件的图标名称。
是否将 PluginAction 隐藏在 Studio 的快捷方式查看图中。对于上下文行动有用。默认为 true。
返回
代码示例
This code sample visualizes how to create a PluginAction. These must be created using the Plugin:CreatePluginAction() method in order to work.
In order to work as expected, the code block must but pasted into the Command Bar, but only once. Consecutive attempts at executing the code in the Command Bar will result in an error because a plugin cannot create more than one PluginMenu with the same ID.
When the created action is bound and Triggered, it outputs Hello world!.
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
这个函数创建了一个新的 PluginMenu ,这是 Studio 可以显示的上下文菜单,显示一个列表的 PluginActions 并支持子菜单。
为了使插件菜单按预期工作,它们必须使用此函数创建。
还见:
- Plugin:CreatePluginAction() , 创建一个插件行动
- PluginMenu.Title , 在使用作为子菜单时显示的文本
- PluginMenu.Icon , 在使用作为子菜单时显示的图标
- PluginMenu:AddAction() , 将给定的行动添加到菜单
- PluginMenu:AddNewAction() , 创建一个暂时的操作,隐藏在 Studio 的自定义快捷方式窗口
- PluginMenu:AddMenu() , 添加指定菜单作为分隔符
- PluginMenu:AddSeparator() , 添加菜单中项目之间的分隔符
- PluginMenu:Clear() , 清除菜单
- PluginMenu:ShowAsync() , 在鼠标指针处显示菜单。直到选择一个项目或关闭菜单为止提供。选定的行动触发其触发的事件
参数
返回
代码示例
This code sample visualizes how PluginMenus and PluginActions behave when created for a Plugin. Outside of this example, you should not parent the plugin or its functional components to the experience's workspace.
In order to work as expected, the code block must but pasted into the Command Bar, but only once. Consecutive attempts at executing the code in the Command Bar will result in an error because a plugin cannot create more than one PluginMenu with the same ID.
After executing the code, changing the created BoolValue in the experience's workspace opens the plugin's menus. Selecting an action from the menus the function connected to the trigger signal.
-- 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
创建工具栏 函数创建一个新的PluginToolbar,带有给定名称的。工具栏可以用来创建插件按钮。
参数
工具栏上的可见文本,用于标记包含按钮组的内容。
返回
代码示例
This code creates a toolbar with the name "ExampleToolbar".
plugin:CreateToolbar("ExampleToolbar")
Deactivate
禁用插件。如果已激活,将解除关联的 PluginMouse 如果已激活
还见:
- Plugin:Activate() ,将调用插件的状态设置为激活
- Plugin.Deactivation , 在插件被禁用时发射
- Plugin.Unloading , 在插件通过卸载或重新加载而被禁用或更新之前立即发生火灾
返回
GetMouse
获取鼠标 返回一个 PluginMouse 可在插件激活期间使用的 Plugin:Activate() .
返回
代码示例
This code would print Button 1 pressed from PluginMouse each time the mouse's left button was clicked.
local mouse = plugin:GetMouse()
local function button1Down()
print("Button 1 pressed from PluginMouse")
end
mouse.Button1Down:Connect(button1Down)
GetSelectedRibbonTool
GetSelectedRibbonTool 返回当前选择的 Enum.RibbonTool 。它返回一个与特定工具相对应的枚数。这将返回工具是否通过 Plugin:SelectRibbonTool() 手动或程序化选择。
返回
代码示例
This code must be run from a plugin. This code selects the move tool, checks which tool is selected, then prints out to the console which tool is selected. SelectRibbonTool will not return the value until the next frame.
plugin:SelectRibbonTool(Enum.RibbonTool.Move, UDim2.new())
task.wait() -- wait for next frame
local selectedRibbonTool = plugin:GetSelectedRibbonTool()
print("The selected RibbonTool is", selectedRibbonTool)
GetSetting
使用给定的键检索以前存储的值,或 nil 如果给定的键不存在。
因为同一个插件的多个实例可以同时运行(例如,如果多个 Studio 窗口打开),你不应该依赖这个值在不同时间保持相同。其他插件实例可随时更新设置。
此调用可静默失败并返回 nil 如果多个实例相同插件正在阅读和写入数据。如果您的插件期望频繁写入设置,您应该在短时间后检查返回的值以区分是否存在暂时不可用的设置和不存在的设置。
参数
返回
代码示例
The below example would print the value saved to the key FirstTime. If the key doesn't exist, it would print nil.
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
IsActivatedWithExclusiveMouse
此函数返回 true,如果此插件在激活过程中使用独家鼠标,然后通过 Plugin:Activate() 函数激活后仍然激活,这个插件将返回 true 。如果返回真值,那么通过 PluginMouse 可以检索到一个 Plugin:GetMouse() 。
还见:
- Plugin.Deactivation , 在插件被禁用时发射
- Plugin.Unloading , 在插件通过卸载或重新加载而被禁用或更新之前立即发生火灾
返回
这个插件目前是否激活并使用专属鼠标。
Negate
否定给定的部分,并返回结果的否定操作。
参数
返回
OpenScript
用于在编辑器窗口中打开指定的脚本实例,在 Roblox 工作室中,在指定行。如果没有线作为参数提供,它将默认为 1。
参数
返回
代码示例
The following would open a newly created Script in Workspace, assuming the variable "Plugin" was already declared.
local newScript = Instance.new("Script")
newScript.Parent = workspace
plugin:OpenScript(newScript)
OpenWikiPage
打开上下文帮助窗口到那个 wiki 页面,该页面上有 url 链接。
参数
返回
代码示例
The following, when executed in a plugin, will open the BasePart API page in the context help.
plugin:OpenWikiPage("API:Class/BasePart")
SaveSelectedToRoblox
打开用户当前选择的上传窗口。
返回
SelectRibbonTool
激活指定的 Roblox Studio 工具。如果工具打开窗口,位置参数指定它应该在屏幕上显示的位置。
注意:
- 为了使这一操作正确运行,必须选择一个对象。
- 更改 position 属性的缩放字段不会影响对话框。
参数
返回
Separate
分离给定的联合操作,返回结果的零件。
参数
返回
SetSetting
为指定的值存储在指定的键下以后使用。值将在 Roblox Studio 关闭后仍然存在。这些设置保存为 JSON 格式的地图,包含字符键。阵列首先通过将数字键转换为字符串来自动转换为地图。
请注意,JSON 格式会加以额外限制,包括以下可能损坏设置文件的字符:
- 在键或值中的撤消符(\),特别是逃出的引号(\")。
- 新行(\n)在键上。
- 在键中引用(")报价。
- 键中的时间段(.)。
如果多个实例的同一个插件正在阅读和写入数据,该调用可静默失败。如果你的插件期望频繁写入设置,你可以通过调用 Plugin:GetSetting() 来检查数据是否已正确写入。
参数
返回
代码示例
This code sample demonstrates use of the Plugin:GetSetting() and Plugin:SetSetting() functions. They detect if a plugin is running for the first time by setting a key. If the key is true, it prints a "welcome back" message; otherwise it prints a "first run" message and sets the key to true.
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
开始拖动 使用参数词典启动拖动操作。参数如下:
<th>类型</th><th>默认</th><th>描述</th></tr></thead><tbody><tr><td><b>发件人</b></td> <td>字符串</td> <td><code>""</code></td><td>识别拖动操作的来源到掉落目标</td></tr><tr><td><b>MimeType</b></td> <td>字符串</td> <td><code>""</code></td><td><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types">MIME</a>类型的<b>数据</b>。</td></tr><tr><td><b>数据</b></td> <td>字符串</td> <td><code>""</code></td><td>关于拖动操动作的信息,例如拖动的内容。应该由掉落目标使用。</td></tr><tr><td><b>鼠标图标</b></td> <td><code>数据类型.内容</code></td> <td><code>""</code> ></td><td>拖动期间使用鼠标滚轮的图标。如果为空,使用默认滚轮。</td></tr><tr><td><b>拖动图标</b></td> <td><code>数据类型.内容</code></td> <td><code>""</code> ></td><td>在拖动期间在鼠标滚轮下渲染的图像。这应该代表被拖动的物品。</td></tr><tr><td><b>热点</b></td> <td><code>数据类型。Vector2</code></td> <td><code>数据类型。Vector2.new(0, 0)</code> ></td><td>从左上角向下的像素偏移,鼠标应该“按住” <b>拖动图标</b> 。</td></tr></tbody>
名称 |
---|
还见:
参数
返回
代码示例
This code sample creates two plugin widget windows: a drag source and a drop target. In the source window, the script creates a TextBox and TextButton to allow the user to begin a plugin drag action. The drop target window will display the MimeType of whatever is dragged into it using a TextLabel. If the MimeType is text/plain, it will display the plain text data instead.
To run this code sample as a plugin, paste it into a Script. Then, right-click the script in the Explorer window and choose "Save as Local Plugin".
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)
CreateDockWidgetPluginGui
创建DockWidgetPluginGui 从给定的 DockWidgetPluginGui 创建了一个新的 DockWidgetPluginGuiInfo 。第一个参数, pluginGuiId , 应该是独一且一致的字符串。用于保存 widget 的靠近状态和其他内部细节的状态。
参数
一个独特且一致的标识符,用于存储 widget 的靠码状态和其他内部细节。
描述要创建的 DockWidgetPluginGui (初始状态、大小等)。
返回
代码示例
This code, when ran inside a Plugin, creates a DockWidgetPluginGui with a simple TextButton.
-- 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
ImportFbxAnimation
此函数提示用户打开一个 .fbx 动画文件,可以加载到 ,然后继续将动画插入 中。
参数
返回
PromptForExistingAssetId
在 Roblox Studio 中打开一个窗口,提示用户根据指定的 assetType 选择资产。返回选择了哪个资产ID,或关闭窗口时 -1。
参数
返回
活动
Deactivation
当 Plugin 被禁用时发射。这发生在插件代码调用 Plugin:Deactivate() 或因为另一个插件调用了 Plugin:Activate(),导致所有其他插件都失去了活动状态。
还见:
- Plugin.Unloading , 在插件通过卸载或重新加载而被禁用或更新之前立即发生火灾
Unloading
此事件在 Plugin 停止运行之前立即发射。禁用、卸载、即将更新或当地关闭时,插件都会被卸下。
它可以让插件在停止运行脚本之前清理自己,例如从 DataModel 中移除不必要的实例。如果插件没有正确清理,旧副本将留存。当这发生时,用户可能被迫关闭并重新打开一个坏用户体验的地方。
插件相关实例,例如 PluginToolbarButtons , DockWidgetPluginGuis 和 PluginGuis 在插件卸载时自动清理,因此无需删除它们。