Reference API Roblox

Engine API

Website

Related

Reference API Roblox

ScriptDocument

This class is not replicated. Its interface does not cross the network boundary.
This class is not creatable. Instances of this class cannot be created with Instance.new.
Tags: [NotCreatable, NotReplicated]

Member index 19

HistoryMember
543CloseAsync(): Tuple
533EditTextAsync(newText: string, startLine: int, startCharacter: int, endLine: int, endCharacter: int): Tuple
540ForceSetSelectionAsync(cursorLine: int, cursorCharacter: int, anchorLine: int? = nil, anchorCharacter: int? = nil): Tuple
531GetInternalUri(): string
536GetLine(lineIndex: int? = nil): string
532GetLineCount(): int
532GetScript(): LuaSourceContainer
538GetSelectedText(): string
534GetSelection(): Tuple
538GetSelectionEnd(): Tuple
538GetSelectionStart(): Tuple
536GetText(startLine: int? = nil, startCharacter: int? = nil, endLine: int? = nil, endCharacter: int? = nil): string
541GetViewport(): Tuple
538HasSelectedText(): bool
532IsCommandBar(): bool
649MultiEditTextAsync(edits: Array): Tuple
540RequestSetSelectionAsync(cursorLine: int, cursorCharacter: int, anchorLine: int? = nil, anchorCharacter: int? = nil): Tuple
534SelectionChanged(positionLine: int64, positionCharacter: int64, anchorLine: int64, anchorCharacter: int64)
541ViewportChanged(startLine: int64, endLine: int64)
inherited from Instance
553Archivable: bool
635Capabilities: SecurityCapabilities
553Name: string
553Parent: Instance
635Sandboxed: bool
616UniqueId: UniqueId
576AddTag(tag: string): null
573ClearAllChildren(): null
462Clone(): Instance
573Destroy(): null
486FindFirstAncestor(name: string): Instance
486FindFirstAncestorOfClass(className: string): Instance
486FindFirstAncestorWhichIsA(className: string): Instance
486FindFirstChild(name: string, recursive: bool = false): Instance
486FindFirstChildOfClass(className: string): Instance
486FindFirstChildWhichIsA(className: string, recursive: bool = false): Instance
486FindFirstDescendant(name: string): Instance
563GetActor(): Actor
486GetAttribute(attribute: string): Variant
462GetAttributeChangedSignal(attribute: string): RBXScriptSignal
631GetAttributes(): Dictionary
648GetChildren(): Instances
462GetDebugId(scopeLength: int = 4): string
486GetDescendants(): Array
486GetFullName(): string
641GetStyled(name: string): Variant
576GetTags(): Array
576HasTag(tag: string): bool
486IsAncestorOf(descendant: Instance): bool
486IsDescendantOf(ancestor: Instance): bool
580IsPropertyModified(name: string): bool
573Remove(): null
576RemoveTag(tag: string): null
580ResetPropertyToDefault(name: string): null
573SetAttribute(attribute: string, value: Variant): null
462WaitForChild(childName: string, timeOut: double): Instance
648children(): Instances
553clone(): Instance
573destroy(): null
553findFirstChild(name: string, recursive: bool = false): Instance
648getChildren(): Instances
553isDescendantOf(ancestor: Instance): bool
573remove(): null
462AncestryChanged(child: Instance, parent: Instance)
462AttributeChanged(attribute: string)
462ChildAdded(child: Instance)
462ChildRemoved(child: Instance)
462DescendantAdded(descendant: Instance)
462DescendantRemoving(descendant: Instance)
500Destroying()
553childAdded(child: Instance)
inherited from Object
647ClassName: string
647className: string
647GetPropertyChangedSignal(property: string): RBXScriptSignal
647IsA(className: string): bool
650isA(className: string): bool
647Changed(property: string)

Removed member index 1

HistoryMember
532GetNumLines(): int

Description

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.

History 32

Members 19

CloseAsync

Parameters (0)
No parameters.
Returns (1)
Tuple

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.

This function yields. It will block the calling thread until completion.

History 1

Tags: [Yields]

EditTextAsync

Parameters (5)
newTextstring
startLineint
startCharacterint
endLineint
endCharacterint
Returns (1)
Tuple

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

This function yields. It will block the calling thread until completion.

History 5

Tags: [Yields]

ForceSetSelectionAsync

Parameters (4)Default
cursorLineint
cursorCharacterint
anchorLineint?nil
anchorCharacterint?nil
Returns (1)
Tuple

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.

This function yields. It will block the calling thread until completion.

History 1

Tags: [Yields]

GetInternalUri

Parameters (0)
No parameters.
Returns (1)
string

History 1

GetLine

Parameters (1)Default
lineIndexint?nil
Returns (1)
string

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

History 2

GetLineCount

Parameters (0)
No parameters.
Returns (1)
int

Returns the number of lines in the active document.

History 1

GetScript

Parameters (0)
No parameters.
Returns (1)
LuaSourceContainer

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

History 2

GetSelectedText

Parameters (0)
No parameters.
Returns (1)
string

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

History 1

GetSelection

Parameters (0)
No parameters.
Returns (1)
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.

History 1

GetSelectionEnd

Parameters (0)
No parameters.
Returns (1)
Tuple

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

History 1

GetSelectionStart

Parameters (0)
No parameters.
Returns (1)
Tuple

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

History 1

GetText

Parameters (4)Default
startLineint?nil
startCharacterint?nil
endLineint?nil
endCharacterint?nil
Returns (1)
string

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).

History 4

  • 536 Change Parameters of GetText from (startLine: int = -1234567, startCharacter: int = -1234567, endLine: int = -1234567, endCharacter: int = -1234567) to (startLine: int? = nil, startCharacter: int? = nil, endLine: int? = nil, endCharacter: int? = nil)
  • 532 Change Parameters of GetText from () to (startLine: int = -1234567, startCharacter: int = -1234567, endLine: int = -1234567, endCharacter: int = -1234567)
  • 532 Change Security of GetText from RobloxScriptSecurity to PluginSecurity
  • 528 Add GetText

GetViewport

Parameters (0)
No parameters.
Returns (1)
Tuple

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.

History 1

HasSelectedText

Parameters (0)
No parameters.
Returns (1)
bool

Returns whether or not the editor has any text selected.

History 1

IsCommandBar

Parameters (0)
No parameters.
Returns (1)
bool

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.

History 2

MultiEditTextAsync

Parameters (1)
editsArray
Returns (1)
Tuple
This function yields. It will block the calling thread until completion.

History 1

Tags: [Yields]

RequestSetSelectionAsync

Parameters (4)Default
cursorLineint
cursorCharacterint
anchorLineint?nil
anchorCharacterint?nil
Returns (1)
Tuple

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.

This function yields. It will block the calling thread until completion.

History 1

Tags: [Yields]

SelectionChanged

Parameters (4)
positionLineint64
positionCharacterint64
anchorLineint64
anchorCharacterint64

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

History 1

ViewportChanged

Parameters (2)
startLineint64
endLineint64

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

History 1

Removed members 1

GetNumLines

Parameters (0)
No parameters.
Returns (1)
int

History 2

Settings