Hi Plugin Developers,
Today we are introducing an evolution of the ChangeHistoryService API, which will make undo handling in Studio more robust and open up additional undo-related capabilities. Please review the new API and consider taking the time to migrate your plugins.
Previously you would call ChangeHistoryService:SetWaypoint after making changes to the DataModel.
- Call ChangeHistoryService:TryBeginRecording before making changes to find out whether your plugin is allowed to begin making changes to the DataModel.
- Call ChangeHistoryService:FinishRecording after making changes, with parameters controlling what happens to the changes you’ve just made.
Basic usage looks like this:
local CHS = game:GetService("ChangeHistoryService") --… local recording = CHS:TryBeginRecording("MyAction") if recording then -- Take your action here CHS:FinishRecording(recording, Enum.FinishRecordingOperation.Commit) end
Studio is transitioning to a richer model for undo handling, where changes to the DataModel are placed into explicitly specified buckets called “recordings” rather than groups of changes being implicitly specified via waypoints. The new API exposes this new undo model.
This will help Studio know what actions are currently being performed against the DataModel, and by which source. With this additional information, Studio can better coordinate between your plugins, other plugins, and built-in Studio behaviors.
Recordings mean Studio can differentiate between long-running actions like terrain generation and other actions you take in the meantime. They also let you express that you canceled an action without it affecting the DataModel or extended a prior action. Here are a few examples of things we couldn’t do with the old API which we will be able to do once plugins begin migrating to the new API:
- Immediately warn developers when they fail to use recordings in their plugin.
- Use the cancellation mechanics to not mark packages as modified after canceling previewed changes to them.
- Avoid auto-saving in the middle of a plugin performing a long-running action such as dragging or generating terrain.
It will take time for both your plugins and our internal Studio code to migrate towards this new Recording API, and there will be a transitional period where both APIs are in use. Here’s our planned timeline for the migration:
- You can update your plugins to use the Recording API.
- We will begin updating Studio to internally use the Recording API.
In the coming months
- SetWaypoint will be deprecated assuming a smooth migration.
- Calls to SetWaypoint will warn that you should migrate to the new API.
- Studio systems such as the Package system will begin relying on the new API and possibly have degraded interactions with plugins that haven’t migrated.
- We want to internally replace the Waypoint system entirely with the Recording system. We’ll evaluate how to proceed on an ongoing basis depending on developer feedback and how the migration is progressing.
If you notice any issues adopting the new API. Please fill a bug in the bug reports section, or send a message to our @Bug-Support team. Since this new API and the existing Waypoints API exist in parallel for the time being, we want to make sure that your adoption goes smoothly.
Finally, shout-out to the many folks in the Creator Collaboration Team who made this work possible: