ScriptDocument

Show Deprecated
Not Creatable
Not Replicated

A ScriptDocument instance is a proxy of the document of a Studio Script Editor. It's different from the LuaSourceContainer open in the editor in that it represents the ephemeral state of an open document, and its representation is in a format that's more suited for reading and editing code than executing it. In particular, ScriptDocument reflects any changes that have been made to the open script in Collaborative Editing, which the source property doesn't.

The Script Editor itself exists and changes on a different thread than any DataModel, so the ScriptDocument replicates the open Script Editor, but it isn't the open editor. Because of the replication, there's sometimes a slight delay between changing the text in the editor and updating the ScriptDocument. The delay usually occurs because the DataModel is busy, and it's almost always extremely small, but it still exists.

The existence of a ScriptDocument indicates that a document is open in the Script Editor. All ScriptDocument instances have ScriptEditorService as its parent. Each instance adheres to the following encoding conventions:

  • All text in ScriptDocument is UTF-8 encoded.
  • All line indices are 1-indexed.
  • All character indices are 1-indexed and count UTF-8 bytes, not graphemes, so the same warning from TextBox.CursorPosition applies: many Unicode characters take more than one byte.
  • All ranges are inclusive of their start position and exclusive of their end position, so start == end implies an empty range.

All APIs for ScriptDocument are at Plugin level security.

Summary

Properties

Methods

GetInternalUri(): string  

GetLine(lineIndex: number?): string  

Returns the text of the specified line. When no argument is provided, returns the line of the current cursor position.

GetLineCount(): number  

Returns the number of lines in the document.

GetScript(): LuaSourceContainer  

Returns the underlying LuaSourceContainer instance, if one exists, otherwise nil.

GetSelectedText(): string  

Gets the text selected in the editor, or an empty string if there is no selection.

GetSelection(): Tuple  

Returns the last known selection of the Script Editor in the format: CursorLine, CursorChar, AnchorLine, AnchorChar. If the Script Editor has no selection, CursorLine == AnchorLine and CursorChar == AnchorChar.

GetSelectionEnd(): Tuple  

Gets the larger of the cursor position and anchor. If the editor has no selection, they are the same value.

GetSelectionStart(): Tuple  

Gets the smaller of the cursor position and anchor. If the editor has no selection, they are the same value.

GetText(startLine: number?, startCharacter: number?, endLine: number?, endCharacter: number?): string  

Returns text from the open editor.

GetViewport(): Tuple  

Returns the currently displayed line numbers in the editor change.

HasSelectedText(): boolean  

Returns whether or not the editor has any text selected.

IsCommandBar(): boolean  

Returns true if the ScriptDocument represents the Command bar.

CloseAsync(): Tuple  YIELDS

Requests that the editor associated with this document close. Yields the current thread until the editor responds to the request.

EditTextAsync(newText: string, startLine: number, startCharacter: number, endLine: number, endCharacter: number): Tuple  YIELDS

Replaces the text in the specified range from (startLine, startColumn) to (endLine, endColumn) with newText.

ForceSetSelectionAsync(cursorLine: number, cursorCharacter: number, anchorLine: number?, anchorCharacter: number?): Tuple  YIELDS

Asks the editor to set its cursor selection to the argument values.

RequestSetSelectionAsync(cursorLine: number, cursorCharacter: number, anchorLine: number?, anchorCharacter: number?): Tuple  YIELDS

Asks the editor to set its cursor selection to the argument values.

Events

SelectionChanged(positionLine: number, positionCharacter: number, anchorLine: number, anchorCharacter: number): RBXScriptSignal  

Fires when the ScriptDocument changes, including immediately after a text change.

ViewportChanged(startLine: number, endLine: number): RBXScriptSignal  

Fires when the displayed line numbers in the editor change.

Properties

Methods

GetInternalUri

string
Roblox Script Security

Returns

string

GetLine

string
Plugin Security

Returns the text of the specified line. When no argument is provided, returns the line of the current cursor position.

Parameters

lineIndex: number?
Default Value: "nil"

Returns

string

Code Samples

ScriptDocument.SelectionChanged and ScriptDocument:GetLine()
game:GetService("ScriptEditorService").TextDocumentDidOpen:Connect(

	function(doc) 

		doc.SelectionChanged:Connect(

			function() 

				print(doc:GetLine()) 

			end) 

	end)

GetLineCount

number
Plugin Security

Returns the number of lines in the active document.


Returns

number

Code Samples

ScriptDocument:GetLineCount()
game:GetService("ScriptEditorService").TextDocumentDidOpen:Connect(

	function(doc) 

		print("Opened a doc with", doc:GetLineCount(), "lines!") 

	end)

GetScript

LuaSourceContainer
Plugin Security

Returns the underlying LuaSourceContainer instance, if one exists, otherwise nil.


Returns

LuaSourceContainer

Code Samples

ScriptDocument:GetScript()
game:GetService("ScriptEditorService").TextDocumentDidOpen:Connect(

	function(doc) 

		print("Opened ", doc:GetScript()) 

	end)

GetSelectedText

string
Plugin Security

Gets the text selected in the editor, or an empty string if there is no selection.


Returns

string

Code Samples

ScriptDocument:HasSelectedText() and :GetSelectedText()
local ScriptEditorService = game:GetService("ScriptEditorService")

ScriptEditorService.TextDocumentDidOpen:Connect(function(Doc)

	Doc.SelectionChanged:Connect(function()

		if Doc:HasSelectedText() then

			print("Your currently selected text is: ", Doc:GetSelectedText())

		else 

			print("You have no text currently selected.")

		end

	end)

end)

GetSelection

Tuple
Plugin Security

Returns the last known selection of the Script Editor in the format: CursorLine, CursorChar, AnchorLine, AnchorChar. If the Script Editor has no selection, CursorLine == AnchorLine and CursorChar == AnchorChar.


Returns

Tuple

CursorLine, CursorChar, AnchorLine, AnchorChar.

GetSelectionEnd

Tuple
Plugin Security

Gets the larger of the cursor position and anchor. If the editor has no selection, they are the same value.


Returns

Tuple

Code Samples

ScriptDocument:GetSelectionStart() and :GetSelectionEnd()
local ScriptEditorService = game:GetService("ScriptEditorService")

local Document = ScriptEditorService:FindScriptDocument(workspace.Script) 

local sL, sC = Document:GetSelectionStart()

local eL, eC = Document:GetSelectionEnd()

Document:EditTextAsync("Replacement!", sL, sC, eL, eC)

GetSelectionStart

Tuple
Plugin Security

Gets the smaller of the cursor position and anchor. If the editor has no selection, they are the same value.


Returns

Tuple

Code Samples

ScriptDocument:GetSelectionStart() and :GetSelectionEnd()
local ScriptEditorService = game:GetService("ScriptEditorService")

local Document = ScriptEditorService:FindScriptDocument(workspace.Script) 

local sL, sC = Document:GetSelectionStart()

local eL, eC = Document:GetSelectionEnd()

Document:EditTextAsync("Replacement!", sL, sC, eL, eC)

GetText

string
Plugin Security

Returns text from the open editor. Must be called with 0, 2 or 4 arguments:

  • If called with 0 arguments, gets the entire contents of the open editor.
  • If called with 2 arguments, gets the text of the document starting at (startLine, startColumn).
  • If called with 4 arguments, gets the text of the document starting at (startLine, startColumn) and ending at (endLine, endColumn).

Parameters

startLine: number?
Default Value: "nil"
startCharacter: number?
Default Value: "nil"
endLine: number?
Default Value: "nil"
endCharacter: number?
Default Value: "nil"

Returns

string

Code Samples

ScriptDocument:GetText()
game:GetService("ScriptEditorService").TextDocumentDidChange:Connect(

	function(doc, _) 

		print("New Contents", doc:GetText()) 

	end)

GetViewport

Tuple
Plugin Security

Returns the currently displayed line numbers in the editor change. The editor displays the lines between startLine and endLine, inclusive. The first and last line might only display partially. For example, only the topmost pixel of the last line might be on screen. Furthermore, code folding might hide lines between startLine and endLine.


Returns

Tuple

Code Samples

ScriptDocument:GetViewport
local ScriptEditorService = game:GetService("ScriptEditorService")

print(ScriptEditorService:FindScriptDocument(workspace.Script):GetViewport())

HasSelectedText

boolean
Plugin Security

Returns whether or not the editor has any text selected.


Returns

boolean

Code Samples

ScriptDocument:HasSelectedText() and :GetSelectedText()
local ScriptEditorService = game:GetService("ScriptEditorService")

ScriptEditorService.TextDocumentDidOpen:Connect(function(Doc)

	Doc.SelectionChanged:Connect(function()

		if Doc:HasSelectedText() then

			print("Your currently selected text is: ", Doc:GetSelectedText())

		else 

			print("You have no text currently selected.")

		end

	end)

end)

IsCommandBar

boolean
Plugin Security

Returns true if the ScriptDocument represents the Command bar. The command bar has special rules and limitations in this API:

  • Studio creates the Command bar before running plugins, so it doesn't always fire the opened event, although it does close and reopen as Studio transitions between DataModels.
  • You can't edit the Command bar with EditTextAsync for security reasons.

Returns

boolean

Code Samples

ScriptDocument:IsCommandBar()
for _, v in pairs(game:GetService("ScriptEditorService"):GetChildren()) do 

	if v:IsCommandBar() then 

		print(v) 

	end 

end

CloseAsync

Tuple
Yields
Plugin Security

Requests that the editor associated with this document close. Yields the current thread until the editor responds to the request. If the function succeeds, it returns (true, nil). If the function fails, it returns (false, string) as a description of the problem.

This function can't close the command bar.


Returns

Tuple

Code Samples

ScriptDocument:CloseAsync
local ScriptEditorService = game:GetService("ScriptEditorService")

print(ScriptEditorService:FindScriptDocument(workspace.Script):CloseAsync())

EditTextAsync

Tuple
Yields
Plugin Security

Replaces the text in the specified range from (startLine, startColumn) to (endLine, endColumn) with newText. If the range is empty, then the function inserts the text at (startLine, startColumn). If the text cursor is within the specified range, the cursor moves to the end position of the edit. Otherwise, the text cursor doesn't move. This function yields the current thread until it receives a reply from the editor about the edit.

If the function succeeds, it returns (true, nil).

The function throws an error if:

  • The range is invalid.
  • The range would slice a unicode character (e.g., replacing only some of the bytes of the unicode character).
  • The newText itself contains invalid UTF-8.

If the function fails, it returns (false, string). The string is a description of the problem. The most common failure type is a version mismatch. This occurs when you try to call EditTextAsync during the time when the ScriptDocument is out of sync with the contents of the editor. If this happens, you can retry the edit.

Parameters

newText: string
startLine: number
startCharacter: number
endLine: number
endCharacter: number

Returns

Tuple

ForceSetSelectionAsync

Tuple
Yields
Plugin Security

Asks the editor to set its cursor selection to the argument values. Both anchor arguments must be passed, or neither. If neither is passed, then they each default to being the same as the corresponding cursor argument. The editor might decline to update its cursor if the text content of the document has changed. Unlike ScriptDocument:RequestSetSelectionAsync(), the editor will not decline to move its cursor if the cursor has moved since the request was made. Returns (true, nil) if the cursor was updated, and (false, string) with an explanation string if it was not. Yields the current thread until the editor replies.

Parameters

cursorLine: number
cursorCharacter: number
anchorLine: number?
Default Value: "nil"
anchorCharacter: number?
Default Value: "nil"

Returns

Tuple

Code Samples

ScriptDocument:ForceSetSelectionAsync()
local ScriptEditorService = game:GetService("ScriptEditorService")

local Document = ScriptEditorService:FindScriptDocument(workspace.Script) 

local Line = Document:GetSelection()

local MatchStart, MatchEnd = Document:GetLine(Line):find("%d+")

if MatchStart and MatchEnd then

	Document:ForceSetSelectionAsync(Line, MatchStart, Line, MatchEnd + 1)

end

RequestSetSelectionAsync

Tuple
Yields
Plugin Security

Asks the editor to set its cursor selection to the argument values. Both anchor arguments must be passed, or neither. If neither is passed, then they each default to being the same as the corresponding cursor argument. The editor might decline to update its cursor if the text content of the document has changed, or the cursor has moved since the request was made. Returns (true, nil) if the cursor was updated, and (false, string) with an explanation string if it was not. Yields the current thread until the editor replies.

Parameters

cursorLine: number
cursorCharacter: number
anchorLine: number?
Default Value: "nil"
anchorCharacter: number?
Default Value: "nil"

Returns

Tuple

Code Samples

ScriptDocument:RequestSetSelectionAsync()
local ScriptEditorService = game:GetService("ScriptEditorService")

local Document = ScriptEditorService:FindScriptDocument(workspace.Script) 

local Line = Document:GetSelection()

local MatchStart, MatchEnd = Document:GetLine(Line):find("%d+")

if MatchStart and MatchEnd then

	Document:RequestSetSelectionAsync(Line, MatchStart, Line, MatchEnd + 1)

end

Events

SelectionChanged

Plugin Security

Fires when the ScriptDocument changes, including immediately after a text change.

Parameters

positionLine: number
positionCharacter: number
anchorLine: number
anchorCharacter: number

Code Samples

ScriptDocument.SelectionChanged and ScriptDocument:GetLine()
game:GetService("ScriptEditorService").TextDocumentDidOpen:Connect(

	function(doc) 

		doc.SelectionChanged:Connect(

			function() 

				print(doc:GetLine()) 

			end) 

	end)

ViewportChanged

Plugin Security

Fires when the displayed line numbers in the editor change. See ScriptDocument.GetViewport for details.

Parameters

startLine: number
endLine: number

Code Samples

ScriptDocument.ViewportChanged
local ScriptEditorService = game:GetService("ScriptEditorService")

local document = ScriptEditorService:FindScriptDocument(workspace.Script)

document.ViewportChanged:Connect(print)