Hey Developers,
Hope you’re having a great summer! For all the Plugin devs out there, we’re thrilled to announce something we hope you’ll be as excited about as we are: the Script Editor API beta.
This API vastly expands the extent to which Plugins can interact with the Script Editor, providing the ability to:
- Monitor when Scripts are opened, closed, and edited
- Access information on a user’s cursor, including selected text
- Read and edit specified portions of a Script without overwriting the entire contents
The beta can be enabled by toggling Studio > Beta Features > Script Editor API.
See below for more detailed information!
API Overview
ScriptDocument
A ScriptDocument instance is a proxy of an open Script Editor document (including the Command Bar). It represents the contents of the document, including ephemeral data such as cursor position and selection, as well as uncommitted edits made in Team Create Collab Editing mode (which may not be in the .Source property yet). The provided ScriptDocument methods allow you to asynchronously query and modify the state of these contents.
For example, the following method retrieves text from a Script at a specified location:
string ScriptDocument:GetText(int startLine?, int startColumn?, int endLine?, int endColumn?)
While the following method edits text in at a specified location:
bool, string? ScriptDocument:EditTextAsync(string newText, int startLine, int startColumn, int endLine, int endColumn)
The existence of a ScriptDocument signifies a Script being open in the Script Editor. All ScriptDocuments are parented to the ScriptEditorService.
All APIs for ScriptDocument are at Plugin level security.
Click here for more info and documentation on the ScriptDocument API.
ScriptEditorService
ScriptEditorService provides the ability to both monitor and interact with the ScriptDocuments it owns. Specifically, it allows you to access ScriptDocuments in order to utilize the ScriptDocument API, and to handle events when a ScriptDocument is opened, closed or edited.
For example, the following code attempts to retrieve a ScriptDocument corresponding the Script “myScript” in the workspace:
game:GetService("ScriptEditorService"):FindScriptDocument(workspace.myScript)
While the following Plugin code prints a statement to the output when any ScriptDocument is edited:
game:GetService("ScriptEditorService").TextDocumentDidChange:Connect(function(doc, tbl) print("Changed", doc, tbl) end)
Click here for more info and documentation on ScriptEditorService.
Example Usage
The following Plugin is an example of what can be done with the Script Editor Plugin API: when the user types GS(<some_service>), it replaces the text with <some_service> = game:GetService("<some_service>"):
function IsValidServiceName(ServiceName)
local Success, Service = pcall(function() return game:GetService(ServiceName) end)
return Success and Service
end
game:GetService("ScriptEditorService").TextDocumentDidChange:Connect(function(Document, _)
local Line = Document:GetLine()
local ServiceName = string.match(Line, "GS%((%w+)%)")
if not ServiceName or not IsValidServiceName(ServiceName) then return end
local LineNumber, _, _, _ = Document:GetSelection()
local NewText = string.format("local %s = game:GetService(\"%s\")", ServiceName, ServiceName)
Document:EditTextAsync(NewText, LineNumber, 1, LineNumber, string.len(Line) + 1)
end)
Looking Forward
The Script Editor Plugin API beta revolutionizes what’s possible for Script Editor Plugins, and we can’t wait to see what the community builds with these new tools. We look forward to hearing your feedback on what we have provided, and hope to continue to expand what the API offers.
Please note: Because this API is still in beta, we may make code-breaking changes based on your feedback. If this is necessary, we will let you know.
A huge thanks to the following who’ve contributed to the project: @swmaniac, @code4xp, @cruiser_forever, @windy0724, @infomancer
Happy scripting!
