19 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

ScriptDocument

Inherits from: Instance → Object

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 Drafts Mode, 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.

Inherits from: Instance

Memory category: Instances

Tags: NotCreatable, NotReplicated

Methods

Name	Type / Returns	Description
ScriptDocument:CloseAsync	Tuple	Requests that the editor associated with this document close. Yields the current thread until the editor responds to the request.
ScriptDocument:EditTextAsync	Tuple	Replaces the text in the specified range from (`startLine`, `startColumn`) to (`endLine`, `endColumn`) with newText.
ScriptDocument:ForceSetSelectionAsync	Tuple	Asks the editor to set its cursor selection to the argument values.
ScriptDocument:GetLine	string	Returns the text of the specified line. When no argument is provided, returns the line of the current cursor position.
ScriptDocument:GetLineCount	int	Returns the number of lines in the document.
ScriptDocument:GetScript	LuaSourceContainer	Returns the underlying `LuaSourceContainer` instance, if one exists, otherwise `nil`.
ScriptDocument:GetSelectedText	string	Gets the text selected in the editor, or an empty string if there is no selection.
ScriptDocument: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`.
ScriptDocument:GetSelectionEnd	Tuple	Gets the larger of the cursor position and anchor. If the editor has no selection, they are the same value.
ScriptDocument:GetSelectionStart	Tuple	Gets the smaller of the cursor position and anchor. If the editor has no selection, they are the same value.
ScriptDocument:GetText	string	Returns text from the open editor.
ScriptDocument:GetViewport	Tuple	Returns the currently displayed line numbers in the editor change.
ScriptDocument:HasSelectedText	boolean	Returns whether or not the editor has any text selected.
ScriptDocument:IsCommandBar	boolean	Returns true if the `ScriptDocument` represents the Command bar.
ScriptDocument:MultiEditTextAsync	Tuple	Applies a batch of text edits to the document as a single atomic operation. Yields the current thread until the editor responds.
ScriptDocument:RequestSetSelectionAsync	Tuple	Asks the editor to set its cursor selection to the argument values.
ScriptDocument:ReviewableTextEditsAsync	Tuple	Applies a batch of line-based text edits that appear in the editor as reviewable inline diffs, allowing users to accept or reject each change.

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

ScriptDocument:CloseAsync

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

Type	Description
Tuple	A tuple where the first element is `true` if the editor closed successfully, or `false` followed by a string describing the failure reason.

Field	Value
tags	["Yields"]
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (ScriptDocument-CloseAsync).

ScriptDocument:EditTextAsync

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 one Unicode character, for example replace 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

Name	Type	Description
newText	string	The replacement string to insert into the specified range.
startLine	int	The 1-indexed line number where the replacement range begins.
startCharacter	int	The 1-indexed UTF-8 byte offset within `startLine` where the replacement range begins.
endLine	int	The 1-indexed line number where the replacement range ends (exclusive).
endCharacter	int	The 1-indexed UTF-8 byte offset within `endLine` where the replacement range ends (exclusive).

Returns

Type	Description
Tuple	A tuple where the first element is `true` if the edit was applied successfully, or `false` followed by a string describing the failure reason.

Field	Value
tags	["Yields"]
security	PluginSecurity
thread safety	Unsafe

ScriptDocument:ForceSetSelectionAsync

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

Name	Type	Default	Description
cursorLine	int		The 1-indexed line number for the cursor position.
cursorCharacter	int		The 1-indexed UTF-8 byte offset within the line for the cursor position.
anchorLine	int?	nil	The 1-indexed line number for the anchor position. Defaults to `cursorLine` if not provided.
anchorCharacter	int?	nil	The 1-indexed UTF-8 byte offset within the line for the anchor position. Defaults to `cursorCharacter` if not provided.

Returns

Type	Description
Tuple	A tuple where the first element is `true` if the cursor was updated, or `false` followed by a string explaining why the update was declined.

Field	Value
tags	["Yields"]
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (ScriptDocument-ForceSetSelectionAsync).

ScriptDocument:GetLine

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

Parameters

Name	Type	Default	Description
lineIndex	int?	nil	The 1-indexed line number to retrieve. Defaults to the current cursor line if not provided.

Returns

Type	Description
string	The text content of the specified line as a string.

Field	Value
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (ScriptDocument-SelectionChanged-GetLine).

ScriptDocument:GetLineCount

Returns the number of lines in the active document.

Returns

Type	Description
int	The total number of lines in the document.

Field	Value
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (ScriptDocument-GetLineCount).

ScriptDocument:GetScript

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

Returns

Type	Description
LuaSourceContainer	The `LuaSourceContainer` that the document is editing, or `nil` if the document does not represent a script instance in the place (e.g. the Command Bar is not a real script instance).

Field	Value
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (ScriptDocument-GetScript).

ScriptDocument:GetSelectedText

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

Returns

Type	Description
string	The currently selected text as a string, or an empty string if nothing is selected.

Field	Value
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (ScriptDocument-HasSelectedText-GetSelectedText).

ScriptDocument:GetSelection

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

Type	Description
Tuple	CursorLine, CursorChar, AnchorLine, AnchorChar.

Field	Value
security	PluginSecurity
thread safety	Unsafe

ScriptDocument:GetSelectionEnd

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

Returns

Type	Description
Tuple	A tuple of (line, character) representing the larger of the cursor and anchor positions, both 1-indexed.

Field	Value
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (ScriptDocument-GetSelectionStart-GetSelectionEnd).

ScriptDocument:GetSelectionStart

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

Returns

Type	Description
Tuple	A tuple of (line, character) representing the smaller of the cursor and anchor positions, both 1-indexed.

Field	Value
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (ScriptDocument-GetSelectionStart-GetSelectionEnd).

ScriptDocument:GetText

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

Name	Type	Default	Description
startLine	int?	nil	The 1-indexed line number where the text range begins. Optional; omit all arguments to get the entire document.
startCharacter	int?	nil	The 1-indexed UTF-8 byte offset within `startLine` where the text range begins.
endLine	int?	nil	The 1-indexed line number where the text range ends (exclusive). Optional; omit to read from `startLine`/`startCharacter` to the end of the document.
endCharacter	int?	nil	The 1-indexed UTF-8 byte offset within `endLine` where the text range ends (exclusive).

Returns

Type	Description
string	The text content within the specified range as a string.

Field	Value
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (ScriptDocument-GetText).

ScriptDocument:GetViewport

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

Type	Description
Tuple	A tuple of (startLine, endLine) representing the 1-indexed range of lines currently visible in the editor.

Field	Value
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (ScriptDocument-GetViewport).

ScriptDocument:HasSelectedText

Returns whether or not the editor has any text selected.

Returns

Type	Description
boolean	`true` if the editor has a non-empty text selection, `false` otherwise.

Field	Value
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (ScriptDocument-HasSelectedText-GetSelectedText).

ScriptDocument:IsCommandBar

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

Type	Description
boolean	`true` if this document represents the Command bar, `false` otherwise.

Field	Value
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (ScriptDocument-IsCommandBar).

ScriptDocument:MultiEditTextAsync

Applies a batch of text edits to the document as a single atomic operation, then yields the current thread until it receives a reply from the editor. Each entry in the edits array is a table describing one replacement, with the same meaning as the arguments to ScriptDocument:EditTextAsync(), and the following fields:

NewText: The replacement text.
StartLine: The line of the start of the range to replace.
StartCharacter: The character of the start of the range to replace.
EndLine: The line of the end of the range to replace.
EndCharacter: The character of the end of the range to replace.

The edits are applied together, so either all of them succeed or none of them are applied. Before applying any edit, the function validates every edit and throws an error if:

Any range is invalid.
Any range would slice one Unicode character, for example replace only some of the bytes of the unicode character.
Any NewText itself contains invalid UTF-8.
The ranges of two edits overlap.

If the function succeeds, it returns (true, nil). If the function fails, it returns (false, string), where the string describes the problem. As with ScriptDocument:EditTextAsync(), the most common failure is a version mismatch, which occurs when the ScriptDocument is momentarily out of sync with the contents of the editor; if this happens, you can retry the edits.

Parameters

Name	Type	Default	Description
edits	Array		An array of tables, each describing a text replacement with fields `NewText`, `StartLine`, `StartCharacter`, `EndLine`, and `EndCharacter`.

Returns

Type	Description
Tuple	A tuple where the first element is `true` if all edits were applied successfully, or `false` followed by a string describing the failure reason.

Field	Value
tags	["Yields"]
security	PluginSecurity
thread safety	Unsafe

ScriptDocument:RequestSetSelectionAsync

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

Name	Type	Default	Description
cursorLine	int		The 1-indexed line number for the cursor position.
cursorCharacter	int		The 1-indexed UTF-8 byte offset within the line for the cursor position.
anchorLine	int?	nil	The 1-indexed line number for the anchor position. Defaults to `cursorLine` if not provided.
anchorCharacter	int?	nil	The 1-indexed UTF-8 byte offset within the line for the anchor position. Defaults to `cursorCharacter` if not provided.

Returns

Type	Description
Tuple	A tuple where the first element is `true` if the cursor was updated, or `false` followed by a string explaining why the update was declined.

Field	Value
tags	["Yields"]
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (ScriptDocument-RequestSetSelectionAsync).

ScriptDocument:ReviewableTextEditsAsync

Applies a batch of line-based text edits to the document that are presented to the user as reviewable inline diffs in the Script Editor gutter. Each entry in the changes array is a table with the following fields:

Text: The replacement text to insert. Must be a non-empty string unless EndLine is provided.
StartLine: The 1-indexed line number where the edit begins. If EndLine is omitted, the text is inserted before this line. If EndLine is provided, lines from StartLine through EndLine are replaced.
EndLine: Optional. The 1-indexed last line of the range to replace (inclusive). Must be greater than or equal to StartLine.

The edits must not overlap or border each other; there must be at least one unchanged line between any two edits. Edits are applied atomically. The function throws an error if any entry has invalid fields. If the function fails due to a version mismatch or other editor-side issue, it returns (false, string).

This method cannot be used on the Command bar.

Parameters

Name	Type	Default	Description
changes	Array		An array of tables, each with a `Text` field (the replacement string), a `StartLine` field (1-indexed line to insert or begin replacing at), and an optional `EndLine` field (1-indexed last line to replace, inclusive).

Returns

Type	Description
Tuple	A tuple where the first element is `true` if the edits were applied successfully, or `false` followed by a string describing the failure reason.

Field	Value
tags	["Yields"]
security	PluginSecurity
thread safety	Unsafe

Events

Name	Type / Returns	Description
ScriptDocument.SelectionChanged		Fires when the ScriptDocument changes, including immediately after a text change.
ScriptDocument.ViewportChanged		Fires when the displayed line numbers in the editor change.

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.

ScriptDocument.SelectionChanged

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

Parameters

Name	Type	Description
positionLine	int64	The 1-indexed line number of the cursor position after the change.
positionCharacter	int64	The 1-indexed UTF-8 byte offset of the cursor position after the change.
anchorLine	int64	The 1-indexed line number of the selection anchor after the change.
anchorCharacter	int64	The 1-indexed UTF-8 byte offset of the selection anchor after the change.

Field	Value
security	PluginSecurity

Code samples: View on Creator Hub (ScriptDocument-SelectionChanged-GetLine).

ScriptDocument.ViewportChanged

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

Parameters

Name	Type	Default	Description
startLine	int64		The 1-indexed first line currently visible in the editor viewport.
endLine	int64		The 1-indexed last line currently visible in the editor viewport.

Field	Value
security	PluginSecurity

Code samples: View on Creator Hub (ScriptDocument-ViewportChanged).

Properties

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string