插件 是創建基本 Studio widget、插件工具欄、插件按鈕等內容的主要對象。它是一個自訂的 add-on 到 Studio ,它添加新行為和功能,不是通常包含的。 插件 對象可以通過 plugin
範例程式碼
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 在模型標籤下啟用的用戶是否啟用在工作室中。
返回 Studio 中用戶設定的網格鎖定尺寸。
方法
將呼叫插件的狀態設置為 "啟用"。
- CreatePluginAction(actionId : string,text : string,statusTip : string,iconName : string,allowBinding : bool):PluginAction
創建一個 PluginAction ,這是在 Roblox Studio 中代表一般執行程式的對象,沒有直接關聯的 Toolbar 或 Enum.Button 。
建立新的插件選單。
建立新 PluginToolbar 以指定的名稱。
停用外掛程式。
返回 Enum.JointCreationMode 用戶在 Studio 的模型標籤下設定的用戶。
返回 Mouse 可以在插件啟用時使用。
返回目前選擇的 Enum.RibbonTool。
取回以前儲存的值,或為空,如果指定的鍵匙不存在。
如果此插件目前啟用,則會返回 true,這是因為它啟用過 Plugin:Activate() 函數。
如果這個插件目前啟用使用獨家滑鼠,並且在 Plugin:Activate() 函數後,則返回 true。
取消指定的零件並且返回結果的 NegateOperations。
用於在 Roblox Studio 中的編輯器窗口中開啟指定的指令碼實例,並在指定的行中。如果沒有行指定為參數,它將預設為 1。
開啟上下文協助視窗到連結到的 wiki 頁面。
開啟一個用戶的當前選擇的上傳窗口。
啟用指定的 Roblox Studio 工具。
分離指定的聯盟運作並且返回結果的零件。
在指定的鑰鍵下儲存指定值,以便在後續使用。值會在 Studio 關閉後持續存在。
啟動一個拖曳操作,提供一個參數典型。
聯合指定的零件,並且返回結果的 UnionOperation。
- CreateDockWidgetPluginGui(pluginGuiId : string,dockWidgetPluginGuiInfo : DockWidgetPluginGuiInfo):DockWidgetPluginGui
創建一个 DockWidgetPluginGui 獲得 DockWidgetPluginGuiInfo 。
提示用戶開啟一個 .fbx 動畫檔案,可以載入在 rigModel 上,然後進行插入動畫作為 KeyframeSequence 在 Workspace 中。
提示用戶開啟 .fbx 檔案,上傳模型的個別零件以網格的形式上傳,並且生成一個角色網格以便在動畫中使用,這是載入到 Workspace 的。
在 Roblox Studio 中開啟一個窗口,提示使用者選擇指定的 assetType 類型。返回指定的資產ID,或 -1 如果窗口已關閉。
提示使用者儲存他們目前的選擇以指定的檔案名稱。如果使用者儲存了檔案,則返回真。
活動
發射時發生插件無效化。
立即在 Plugin 停止運行前發射。
屬性
方法
Activate
此函數將調用插件的狀態設置為"啟用"。啟用插件可以通過 Plugin:GetMouse() 方法來控制鼠標。
在任何時間,有 0 或 1 個已啟用的插件。啟用一個插件會取消所有其他插件的效果 (它們會收到一個 Plugin.Deactivation 事件)。
也看:
- Plugin:IsActivatedWithExclusiveMouse() , 如果滑鼠過此功能啟動此插件時是否為啟動此功能的主要目標,則返回 true
- Plugin.Unloading,在插件被重新載入或重新載入時立即啟動
參數
一個Boolean指定是否啟用插件以獨家滑鼠。如果是, PluginMouse 可以透過 Plugin:GetMouse() 取回。
返回
CreatePluginAction
此功能在 Roblox Studio 中創建一個 PluginAction ,這是一個代表 Roblox Studio 中的通用執行程序的對象,沒有直接儲存的 Toolbar 或 Enum.Button 。在 Roblox Studio 中,它們可以在 2>File → 進階 → 自��������
當有動作啟動時,PluginAction.Triggered 事件會被發送。
要讓 PluginActions 作為預期的工作,必須使用此功能創建。
也看:
- PluginMenu,一個可以在 Studio 中顯示的上下文菜單,其中顯示一個列表的 PluginActions 和支持子菜單
- Plugin:CreatePluginMenu() , 建立 PluginMenu
參數
必須是一個獨特的字串,識別這個 PluginAction 從其他人。
顯示行動作的顯示名稱。
顯示行動作的詳細說明。
顯示外掛程式的圖示名稱。
Class.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
此功能在 Studio 中建立新的 PluginMenu ,這是一個可以顯示 Studio 中顯示列表的 PluginActions 和支持子菜單的區域選單。
要讓 PluginMenus 正常運行,必須使用此功能創建。
也看:
- Plugin:CreatePluginAction(),創建一個 PluginAction
- PluginMenu.Title ,當作為子選單顯示時顯示的文字
- PluginMenu.Icon ,用作子菜單時顯示的圖示
- PluginMenu:AddAction() , 將指定的動作添加到菜單
- PluginMenu:AddNewAction() 建立一個暫時行動,它從 Studio 自訂快捷鍵窗口隱藏
- PluginMenu:AddMenu() , 添加指定的菜單作為分隔符
- PluginMenu:AddSeparator() , 在菜單中添加分隔符
- PluginMenu:Clear() , 清除菜單
- PluginMenu:ShowAsync() ,在鼠標指针上顯示菜單。在選擇一個項目或關閉菜單時,它的 Triggered 事件會發動。 選擇的動作會啟動其 Triggered 事件
參數
返回
範例程式碼
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
CreateToolbar 函數會創建一個新的 PluginToolbar 以指定的名稱。工具欄可以用於創建按鈕。
參數
工具欄中的可見文字,標記內含的按鈕群。
返回
範例程式碼
This code creates a toolbar with the name "ExampleToolbar".
plugin:CreateToolbar("ExampleToolbar")
Deactivate
停用此外掛程式。如果它已啟用,則會解除對PluginMouse的關聯
也看:
- Plugin:Activate() , 設置呼叫插件的狀態為"啟用"
- Plugin.Deactivation,啟動時發生
- Plugin.Unloading,在插件被重新載入或重新載入時立即啟動
返回
GetMouse
取得滑鼠 返回一個 PluginMouse 可以在啟用插件時使用的滑鼠。
返回
範例程式碼
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
選擇RibbonTool 將返回目前選擇的 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
取回以前儲存的值,或為空,如果指定的鍵匙不存在。
因為多個版本的相同插件可以同時執行 (例如,如果多個 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
此功能在此插件目前啟用時,如果它啟用過 Plugin:Activate() 功能,會返回 true。如果它返回 true, PluginMouse 可以透過 Plugin:GetMouse() 取回。
也看:
- Plugin.Deactivation,啟動時發生
- Plugin.Unloading,在插件被重新載入或重新載入時立即啟動
返回
這個插件目前是否使用獨家滑鼠。
Negate
取消指定的零件並且返回結果的 NegateOperations。
參數
返回
OpenScript
用於在 Roblox Studio 中的編輯器窗口中開啟指定的指令碼實例,並在指定的行中。如果沒有行指定為參數,它將預設為 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 頁面。
參數
返回
範例程式碼
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 屬性的尺寸變更不會影響對話框 pop-up。
參數
返回
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
開始拖曳 會使用參數典型表來啟動拖曳行動。參數如下:
<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>MINE 類型的 <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>Datatype.Content</code></td><td><code>""</code></td><td>拖曳時使用的滑鼠指針。如果是空的,則會使用預設滑鼠指針。</td></tr><tr><td><b>拖曳圖示</b></td><td><code>Datatype.Content</code></td><td><code>""</code></td><td>一張在拖曳時在鼠標指针下顯示的圖像。這應該代表正在拖曳的項目。</td></tr><tr><td><b>熱點</b></td><td><code>Datatype.Vector2</code></td><td><code>Datatype.Vector2.new(0, 0)</code></td><td>從左上角開始的像素 Offset ,其中 <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
CreateDockWidgetPluginGui 建立了一個名為 DockWidgetPluginGui 的新 DockWidgetPluginGuiInfo 。第一個參數, 0> uginGuiId0> ,應該是一個獨一無二的字串。它用來儲存 widget 的 dock 狀態和其他內部細節。
參數
一種獨特且一致的標識,用於儲存 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 動畫檔案,可以載入到 rigModel 上,然後將動畫作為 KeyframeSequence 在 Workspace 中插入。
參數
返回
PromptForExistingAssetId
在 Roblox Studio 中開啟一個窗口,提示使用者選擇指定的 assetType 類型。返回指定的資產ID,或 -1 如果窗口已關閉。
參數
返回
活動
Deactivation
發生在 Plugin 被無效化時。這發生當 Plugin:Deactivate() 或其他插件呼叫 Plugin:Activate() 時,這使所有其他插件都必須失去積極狀態。
也看:
- Plugin.Unloading,在插件被重新載入或重新載入時立即啟動
Unloading
此事件在 Plugin 停止執行之前立即發生。當停止執行時,插件會卸載,未安裝,即將更新或關閉。
它可以讓插件在其指令碼停止執行後自動清理,例如移除 DataModel 中的不必要例子。如果插件無法正確清理,舊副本將會剩下。當發生這樣的情況時,用戶可能會被強迫關閉並重新開啟位置,這是一個不佳的使用者體驗。
如 PluginToolbarButtons 、 DockWidgetPluginGuis 和 PluginGuis 等插件相關例子,會自動清理,因此不需要將它們移除。