插件 是負責創建基本 Studio 視窗、插件工具欄、插件按鈕等的主要對象。這是一種自訂添加到 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 在 Studio 中。
返回使用者在工作室設定的網格縮放尺寸。
方法
將呼叫插件的狀態設為啟用。
- CreatePluginAction(actionId : string,text : string,statusTip : string,iconName : string,allowBinding : boolean):PluginAction
創建一個 PluginAction ,這是一個在 Roblox Studio 中代表一般可執行行動的對象,沒有直接相關的 Toolbar 或 Enum.Button 。
創建新的插件選單。
創建一個新的 PluginToolbar 使用指定名稱。
停用外掛程式。
返回使用者在 Studio 中設定在模型標籤下的 Enum.JointCreationMode。
返回一個 Mouse 可在插件啟用時使用的方法。
返回目前選擇的 Enum.RibbonTool 。
使用指定的鍵取回先前存儲的值,或 nil 如果指定的鑰匙不存在。
如果此插件目前已啟用,且已通過 Plugin:Activate() 函數啟用,則返回真值。
如果此插件目前使用獨家滑鼠,在使用 Plugin:Activate() 函數後啟用,則返回真值。
否認指定的零件,並返回結果的否認操作。
用於在 Roblox Studio 中開啟指定的腳本實例在編輯器窗口,在指定行。如果沒有線提供為參數,它將默認為 1。
開啟上下文幫助窗口到連結到的wiki頁面。url
開啟使用者當前選擇的上傳窗口。
啟用指定的 Roblox Studio 工具。
分開指定的聯繫操作,並返回結果的零件。
儲存給定值以供稍後使用,在給定的鍵匙下會持續存在,即使 Studio 已關閉。
開始拖動操作,給予一個參數字典。
結合指定的零件,並返回結果的聯繫操作。
- CreateDockWidgetPluginGui(pluginGuiId : string,dockWidgetPluginGuiInfo : DockWidgetPluginGuiInfo):DockWidgetPluginGui
創建一個 DockWidgetPluginGui ,給予一個 DockWidgetPluginGuiInfo 。
提示用戶打開可以加載到 rigModel 的 .fbx 動畫文件,然後進行插入動畫為 KeyframeSequence 在 Workspace 。
提示用戶打開 .fbx 文件,上傳模型的個別組件作為網格,並生成用於動畫的角色骨架,該骨架被載入 Workspace 。
在 Roblox Studio 中開啟一個窗口,提示用戶根據指定的 assetType 選擇資產。返回選擇了哪個資產ID,或-1如果窗口已關閉。
提示用戶儲存目前選擇的文件以指定的文件名稱。如果用戶儲存了文件,返回真值;否則返回假值。
屬性
方法
Activate
此功能將呼叫插件的狀態設置為啟用。啟用插件通過 Plugin:GetMouse() 方法進行鼠標控制。
在任何時候,有 0 或 1 個啟用的插件。啟用插件會停用所有其他插件(它們將收到Plugin.Deactivation事件)。
也見:
- Plugin:IsActivatedWithExclusiveMouse() , 如果此插件目前使用獨家滑鼠,通過此函數啟用後,返回真值
- Plugin.Unloading , 在插件通過卸載、重新載入或通過卸载、停用或更新而被關閉之前立即發生火災
參數
一個boolean指定是否啟用插件專用滑鼠。如果真實,PluginMouse 可以通過 Plugin:GetMouse() 來恢復。
返回
CreatePluginAction
此功能創建了一個 PluginAction ,這是一個在 Roblox Studio 中代表一般可執行行動的對象,沒有直接相關的 Toolbar 或 Enum.Button 。在 Roblox Studio 中,它們可以在 File → Advanced → Customize Shortcuts… 下配置快捷鍵,也可以添加到快速存取工具欄中。
當行動被觸發時,PluginAction.Triggered事件會被警告。
為了使插件行動如預期般運作,它們必須使用此函數創建。
也見:
- PluginMenu , 可以在 Studio 中顯示的上下文選單,顯示一個列表的插件行動並支持子選項
- Plugin:CreatePluginMenu() , 創建一個插件選單
參數
必須是獨一無二的字串,用於識別此 PluginAction 與其他人。
行動作的顯示名稱。
行動作的顯示說明。
用於顯示外掛程式的圖示名稱。
無論 PluginAction 是否會被從 Studio 的快捷方式檢視圖隱藏。對於上下文行動有用。默認為真。
返回
範例程式碼
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
此功能如果此插件目前使用獨家滑鼠,然後通過 Plugin:Activate() 函數啟用後,返回真值。如果這樣返回真值,那麼 PluginMouse 可以通過 Plugin:GetMouse() 來恢復。
也見:
- Plugin.Deactivation,在插件被禁用時發生
- Plugin.Unloading , 在插件通過卸載、重新載入或通過卸载、停用或更新而被關閉之前立即發生火災
返回
這個插件目前是否使用獨家滑鼠。
Negate
否認指定的零件,並返回結果的否認操作。
參數
返回
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頁面。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>MIME <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types">類型</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
PromptForExistingAssetId
在 Roblox Studio 中開啟一個窗口,提示用戶根據指定的 assetType 選擇資產。返回選擇了哪個資產ID,或-1如果窗口已關閉。
參數
返回
活動
Deactivation
當 Plugin 被禁用時發射。這會發生當插件代碼呼叫 Plugin:Deactivate() 或當某些其他插件呼叫 Plugin:Activate(),導致所有其他插件都失去活動狀態。
也見:
- Plugin.Unloading , 在插件通過卸載、重新載入或通過卸载、停用或更新而被關閉之前立即發生火災
Unloading
此事件在 Plugin,在停止運行之前立即發生。在停用、卸載、即將更新或當地關閉時,插件會被卸下。
它讓插件在停止運行其腳本之前先清理自己,例如從 DataModel 中移除不需要的實例。如果插件無法正確清理,舊副本將會留存。當發生這種情況時,使用者可能被迫關閉並重新開啟壞用戶體驗的地方。
插件相關實例,例如 PluginToolbarButtons , DockWidgetPluginGuis 和 PluginGuis 在插件卸載時會自動清理,因此不需要移除它們。