ChangeHistoryService

Show Deprecated

Not Creatable

Service

Plugin developers must use ChangeHistoryService to tell Studio how to undo and redo changes that their plugins make to experiences by recording. Before making changes, a plugin calls ChangeHistoryService:TryBeginRecording(), remembering the identifier it assigns, then after making changes, the Plugin calls ChangeHistoryService:FinishRecording() to complete the recording.

Plugins may also programmatically invoke an undo or redo through ChangeHistoryService:Undo() or ChangeHistoryService:Redo().

ChangeHistoryService is not enabled at runtime, so calling its methods in a running experience has no effect.

Summary

Properties

Properties inherited from Instance

Methods

FinishRecording(identifier: string, operation: FinishRecordingOperation, finalOptions: table?): void

Communicates to Studio that the identified recording is finished and to take the final operation to complete the recording.

GetCanRedo(): Tuple

Returns whether there are actions that can be redone, and, if there are, returns the last of them.

GetCanUndo(): Tuple

Returns whether there are actions that can be undone, and, if there are, returns the last of them.

IsRecordingInProgress(identifier: string?): boolean

Redo(): void

Executes the last action that was undone.

ResetWaypoints(): void

Clears the history, causing all undo/redo waypoints to be removed.

SetEnabled(state: boolean): void

Sets whether or not the ChangeHistoryService is enabled.

SetWaypoint(name: string): void

Sets a new waypoint which can be used as an undo or redo point.

TryBeginRecording(name: string, displayName: string?): string?

Begins tracking changes made to the data model into a recording.

Undo(): void

Undos the last action taken, for which there exists a waypoint.

Methods inherited from Instance

Events

OnRecordingFinished(name: string, displayName: string?, identifier: string?, operationn: FinishRecordingOperation, finalOptions: table?): RBXScriptSignal

Fired when the user completes an action. Parameters come from TryBeginRecording() and FinishRecording().

OnRecordingStarted(name: string, displayName: string?): RBXScriptSignal

Fired when the user begins an action. Parameters come from TryBeginRecording().

OnRedo(waypoint: string): RBXScriptSignal

Fired when the user reverses the undo command. Waypoint describes the type action that has been redone.

OnUndo(waypoint: string): RBXScriptSignal

Fired when the user undoes an action in studio. Waypoint describes the type action that has been undone.

Events inherited from Instance

Properties

Properties inherited from Instance

Methods

FinishRecording

void

Plugin Security

Parameters

identifier: string

Identifies the recording from the previous call to TryBeginRecording(). If the operation is Enum.ChangeHistoryService.FinishRecordingOperation.Cancel, this value is ignored, and the recording is determined by context.

operation: FinishRecordingOperation

Specifies the operation to take.

finalOptions: table?

Optional table of values to pass to OnFinishRecording.

Returns

void

Code Samples

ChangeHistoryService:TryBeginRecording

local ChangeHistoryService = game:GetService("ChangeHistoryService")
local Selection = game:GetService("Selection")

local toolbar = plugin:CreateToolbar("Example Plugin")
local button = toolbar:CreateButton("Neon it up", "", "")

button.Click:Connect(function()
	local parts = {}
	for _, part in pairs(Selection:Get()) do
		if part:IsA("BasePart") then
			parts[#parts + 1] = part
		end
	end

	if #parts < 1 then
    -- Nothing to do.
    return
  end

  local recording = ChangeHistoryService:TryBeginRecording("Set selection to neon")
  if not recording then
    -- Handle error here. This indidcates that your plugin began a previous
    -- recording and never completed it. You may only have one recording
    -- per plugin active at a time.
    return
  end
  
  for _, part in pairs(parts) do
    part.Material = Enum.Material.Neon
  end

  ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
end)

GetCanRedo

Tuple

Plugin Security

Returns whether there are actions that can be redone, and, if there are, returns the last of them.

Returns

Tuple

GetCanUndo

Tuple

Plugin Security

Returns whether there are actions that can be undone, and, if there are, returns the last of them.

Returns

Tuple

IsRecordingInProgress

boolean

Plugin Security

Parameters

identifier: string?

Returns

boolean

Redo

void

Plugin Security

Executes the last action that was undone.

Returns

void

ResetWaypoints

void

Plugin Security

Clears the history, causing all undo/redo waypoints to be removed.

Returns

void

SetEnabled

void

Plugin Security

Sets whether or not the ChangeHistoryService is enabled. When set to false, the undo/redo list is cleared, and does not repopulate. When set to true again, the original list is not restored, but further operations append to the list once more

Parameters

state: boolean

Returns

void

SetWaypoint

void

Plugin Security

This method will be deprecated soon in favor of TryBeginRecording().

ChangeHistoryService tracks plugin history as a stream of property changes. SetWaypoint() creates a cut in that stream of property changes so that the undo and redo actions know where to stop.

By convention, user-invoked actions in Studio must call SetWaypoint() after completing their set of changes to the experience. Calling it before a set of changes may clean up another misbehaving plugin which failed to set a waypoint, but it's a poor reason to justify such usage in your own plugin.

Parameters

Returns

void

Code Samples

ChangeHistoryService:SetWaypoint

local ChangeHistoryService = game:GetService("ChangeHistoryService")
local Selection = game:GetService("Selection")

local toolbar = plugin:CreateToolbar("Example Plugin")
local button = toolbar:CreateButton("Neon it up", "", "")

button.Click:Connect(function()
	local parts = {}
	for _, part in pairs(Selection:Get()) do
		if part:IsA("BasePart") then
			parts[#parts + 1] = part
		end
	end

	if #parts > 0 then
		-- Calling SetWaypoint before the work will not cause any issues, however 
		-- it is redundant, only the call AFTER the work is needed.
		--ChangeHistoryService:SetWaypoint("Setting selection to neon")
		
		for _, part in pairs(parts) do
			part.Material = Enum.Material.Neon
		end

		-- Call SetWaypoint AFTER completing the work
		ChangeHistoryService:SetWaypoint("Set selection to neon")
	else
		-- Nothing to do. You do not need to call SetWaypoint in the case where
		-- the action did not end up making any changes to the experience.
	end
end)

TryBeginRecording

string?

Plugin Security

This method begins a recording to track changes to the data model. You must call it prior to making changes to avoid future warnings or errors.

When the recording is completed, you call FinishRecording() with the returned recording identifier to complete the recording and update the undo/redo stack.

If the plugin already has a recording in progress, this method will fail and return nil.

You may use IsRecordingInProgress() to check the recording status of the plugin.

Parameters

Name of the action being performed suitable for logging and coding purposes.

displayName: string?

Name of the action being performed to display to the user.

Returns

string?

Code Samples

ChangeHistoryService:TryBeginRecording

local ChangeHistoryService = game:GetService("ChangeHistoryService")
local Selection = game:GetService("Selection")

local toolbar = plugin:CreateToolbar("Example Plugin")
local button = toolbar:CreateButton("Neon it up", "", "")

button.Click:Connect(function()
	local parts = {}
	for _, part in pairs(Selection:Get()) do
		if part:IsA("BasePart") then
			parts[#parts + 1] = part
		end
	end

	if #parts < 1 then
    -- Nothing to do.
    return
  end

  local recording = ChangeHistoryService:TryBeginRecording("Set selection to neon")
  if not recording then
    -- Handle error here. This indidcates that your plugin began a previous
    -- recording and never completed it. You may only have one recording
    -- per plugin active at a time.
    return
  end
  
  for _, part in pairs(parts) do
    part.Material = Enum.Material.Neon
  end

  ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
end)

Undo

void

Plugin Security

Undos the last action taken, for which there exists a waypoint.

Returns

void

Methods inherited from Instance

Events

OnRecordingFinished

Plugin Security

Parameters

Name of the action being performed suitable for logging and coding purposes.

displayName: string?

Name of the action being performed to display to the user.

identifier: string?

The identifier for the recording.

operationn: FinishRecordingOperation

finalOptions: table?

Optional table from FinishOperation().

OnRecordingStarted

Plugin Security

Parameters

Name of the action being performed suitable for logging and coding purposes.

displayName: string?

Name of the action being performed to display to the user.

OnRedo

Plugin Security

Fired when the user reverses the undo command. Waypoint describes the type action that has been redone.

Parameters

waypoint: string

OnUndo

Plugin Security

Fired when the user undoes an action in studio. Waypoint describes the type action that has been undone.

Parameters

waypoint: string

Events inherited from Instance