Undo System

The editor has a history (undo/redo) system that allows us to register editing actions and be able to undo/redo them at any time.

Warning

The editor APIs do NOT have undo inside the functions, you must handle undo on the GUI side of the editor tools.

You also need to make sure you encapsulate the data and the undo/redo procedure inside the undo/redo functions.

Do not do any modification of the scene or data outside those functions, because it will break the reproduction of undo/redo for that operation.

The redo function is called inside the history:addAction, so no need to call it yourself.

If you add a function that is also adding a history action, it will be better to call it: addSomeThingWithUndo(…..) the postfix WithUndo will tell us, or yourself, that the function is also registering undo operations. The other functions, by default will be considered without undo support. That function can be on the API side or on UI, as long as it has that postfix to be easily understood what it does.

Action names should be PascalCase, without the Action as postfix, and should be unique globally, “AdSodmeThing” instead of just “Add”.

Check the history API for more complex usage or transactions of actions and so forth. (see History Class)

To create an undoable action you need to write two functions, like so:

History Action Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
-- undo the action of naming an object
local function setObjectNameUndo(actionData)
        local obj = scenetree.findObjectById(actionData.objectId)
        if obj then
                -- for undo, we set the old name
                obj:setName(actionData.oldName)
        end
end

-- redo the action of naming an object
local function setObjectNameRedo(actionData)
        local obj = scenetree.findObjectById(actionData.objectId)
        if obj then
                -- for redo we set the new name
                obj:setName(actionData.newName)
        end
end

-- our GUI-side and undo enabled editor function that sets the name of an object
local function setObjectNameWithUndo(objectId, name)
        local obj = scenetree.findObjectById(objectId)
        local oldName = ""
        if obj then
                oldName = obj:getName(objectId)
        end
        -- add the action to the history, first argument is the name of the action,
        -- second is the action data where you store your undo/redo info
        -- last arguments are the undo redo functions
        editor.history:addAction("SetObjectName", {objectId = objectId, newName = name, oldName = oldName}, setObjectNameUndo, setObjectNameRedo)
        -- the redo function WILL BE EXECUTED in the addAction function right away
        -- thus doing the actual operation
end

The function is added to the editor table (see `Extending Editor API`_), and we can call from anywhere: editor.setObjectNameWithUndo(3422, “MyName”). After that, anytime we call editor.undo() the old name will be set, and if we call editor.redo() the new name will be restored.