The Area Server Checkpoint System implements the mechanics for creating, listing and restoring area server content backups. This page describes how to access the Area Server Checkpoint system via the Hotspot Interface and HSL.
What problem(s) does this solve?
- Revision Control for Areas
- Allows restoration to the "last known good" version of an area.
- Facilitates temporary area changes to test new ideas.
- Provides snapshots of the progression of an area over time.
What problem(s) does this not solve?
- Creating and maintaining more than one set of checkpoints per area.
- Reversing changes to GOM definitions.
- Importing contents from one area into another.
- Deleting checkpoints.
- Area checkpoints consist of a set of area nodes and associations between them.
- Simple string labels are saved with each checkpoint to make them humanly distinguishable.
- Each area owns a single catalog of checkpoints.
- Checkpoint restoration is either additive or destructive.
- An additive restoration only manipulates the nodes that existed when the area checkpoint was created. Any nodes added to the area after the checkpoint was created are left alone.
- A destructive restoration performs an additive restore then removes any nodes that have been added to the area since the checkpoint was created.
Interaction with the Area Server Checkpoint System is accomplished via its exposed HSL interface or through the GUI provided by Clean Engine's HotSpot Menu. No matter which interface is used, the Area Server will refuse all checkpoint operations if the user is not currently in an Edit Instance.
Opening the Area Server Checkpoint System GUI requires you access the hidden HotSpot Menu toolbox located in the top left corner of the render window with a
cntrl-shift-leftclick or typing
F5. On the TOOLs tab, under the Areas category, you will find an option to open the Area Checkpoint GUI. In keeping with the Area Server's Edit Instance only restriction for checkpoint interaction, the Area Checkpoint GUI will only open when the user is in an Edit Instance.
The Checkpoint System GUI retrieves a list of all checkpoints for the current area when it is opened. This list is updated when you save a new checkpoint. Checkpoints created through this GUI record the time the checkpoint was created and the name of the user that created the checkpoint within the checkpoint's label. When the GUI displays the checkpoint list the checkpoint's string label, the recorded creation time and the user name are parsed out and placed within their respective columns.
Just as with other lists in HeroEngine, the list of checkpoints can be culled by typing into the search box. Text entered into the search box is compared as a phrase against the label and account column contents. Searching is automatically triggered by entering text into the search box, requiring no user intervention. The current search can be canceled by erasing all entered text or pressing the icon to the immediate left of the search box.
As a safety precaution, an area checkpoint is automatically saved any time a restoration is requested through the Checkpoint System GUI. Over time the list of auto-saves can become quite long, impairing visually scanning the list of non-auto-save checkpoints. Clicking the "Hide Auto-Saves" checkbox toggles suppression of the display of auto-save checkpoints. Auto-save checkpoints, like any other checkpoint, cannot be deleted.
Saving a new checkpoint
To save a checkpoint of the area, click on the "New" button. The Checkpoint System GUI will pop up a text input box requiring a name/description for the checkpoint. This name is displayed in the "description" column of the checkpoint list form. After a description is provided for the checkpoint, the asynchronous checkpoint creation process begins.
Restoring to a checkpoint
To restore an area to a checkpoint, select the checkpoint you wish to restore to and click on the "Restore" button. The Checkpoint System GUI will pop up a box asking whether an additive, destructive, or restricted restore is desired. After the restoration type is selected, the asynchronous checkpoint restoration process begins. While a checkpoint is being restored to the HeroBlade screen is dimmed and editing is disallowed. If checkpoint restoration succeeded the area's contents will be altered appropriately.
- Restoral types
- Additive - Additive restorals restore area instances back to the state in which they were saved in the selected checkpoint. Any instances added since the checkpoint will be left untouched.
- Destructive - Destructive restorals restore area instances back to the state in which they were saved in the selected checkpoint. Any instances added since the checkpoint will be DESTROYED.
- Restricted - Restrictive restorals are also additive or destructive in nature with an additional restriction limiting it to affect ONLY the nodes you have selected or to EXCLUDE the nodes you have selected.
The Area Server Checkpoint System can also be accessed via external functions provided by the edit instance of area servers. Due to the asynchronous nature of checkpoint operations, the HSL functions do not return success information and instead rely on a callback node that is supplied to the external functions.
List Area Checkpoints
This function retrieves a list of all checkpoints created for the current Area. The supplied callerRef is given to the checkpoint system and used to return the list (as a list of String containing the labels for the checkpoints) in a callback.
external function ListAreaCheckpoints(callerRef as NodeRef)
Save Area Checkpoint
This function creates a new checkpoint with the Area's current contents. The checkpointLabel is applied to the newly created checkpoint's entry in the checkpoint catalog. The supplied callerRef node is given to the checkpoint system and will be used for all callback interaction during the checkpoint creation process.
external function SaveAreaCheckpoint(checkpointLabel as String, callerRef as NodeRef)
Restore Area Checkpoint
This function selects an area checkpoint to restore from. The supplied callerRef node is given to the checkpoint system and will be used for all callback interaction during the checkpoint restoration process. The decision to preform a destructive or additive checkpoint is made by passing TRUE or FALSE as the allowDestructiveChanges parameter
- TRUE: destructive restore
- FALSE: additive restore
external function RestoreAreaCheckpoint(checkpointVersionID as ID, callerRef as NodeRef, allowDestructiveChanges as Boolean)
The Checkpoint system utilizes several callback functions on the supplied callerRef node to query decisions while it works and to communicate the final status of each operation. The list of methods required to exist for callerRef are:
method _QueryNodeCheckpointable( nodeID as ID ) as Boolean
This method is called for each node, identified by its ID nodeID, encountered while the checkpoint system crawls through an area's node hierarchy. The return value determines whether or not the node will be saved in the checkpoint file.
method _QueryAssociationCheckpointable( sourceNodeID as ID, targetNodeID as ID, associationType as ID ) as Boolean
This method is called for each association encountered while the checkpoint system crawls through an area's checkpoint eligible nodes. The return value determines whether or not the association will be saved in the checkpoint file. This method is NOT called for hard associations, as they are always written out if their targets are checkpoint eligible nodes. The parameters sourceNodeID, targetNodeID and associationType describe, by ID, the source, target and type of the association respectively.
method _QueryCheckpointedNodeUserData( nodeID as ID ) as String
This method is called for each checkpoint eligible node, identified by its ID nodeID, from the area. The returned string is saved alongside the node in the checkpoint file and fed back to the _QueryCheckpointRestoreAfterNodeParsed callback function on checkpoint node load.
method _SaveAreaCheckpointResult( checkpointSaved as Boolean, statusMessage as String )
This method is called when a requested Checkpoint save has completed. The checkpointSaved boolean denotes whether the save was successful. The statusMessage string contains a message describing the success or failure in greater detail.
method _ListAreaCheckpointVersions( versionsString as List of String )
This method is called when a requested Checkpoint list has completed. The versionsString contains a list of checkpoint labels as strings. The index of each label in the list corresponds to the ID used to load that checkpoint via RestoreAreaCheckpoint.
method _QueryCheckpointRestoreAfterDiscrepancy( discrepancies as List of String ) as Boolean
This method is called on checkpoint load when a discrepancy is detected between the Area Server's DOM and the DOM mini-dump saved within the checkpoint file. The return value determines if the checkpoint restore should continue. The discrepancies parameter is a list of strings each of which describes a detected discrepancy in a CLI command like manner. The discrepancy values are:
DACD - Could not list class defs DCD ID# - Class has been deleted MDT ID# - Definition type has changed MDN ID# - Definition name has changed MDD ID# - Definition description has changed MCU ID# - Class uber type has changed MCRP ID# PARENT# - Class parent has been removed MCAP ID# PARENT# - Class parent has been added DAFD - Could not list field defs DFD ID# - Field has been deleted MFL ID# - Field lightweight flag has changed MFVT ID# - Field value type has changed MFR ID# - Field reflect to client has changed MFW ID# - Field write strategy has changed MFS ID# - Field watching script has changed MFP ID# - Field privacy has changed DAED - Could not list enum defs DED ID# - Enum has been deleted MERV ID# VALUESTRING - Enum value has been removed MEAV ID# VALUESTRING - Enum value has been added
method _QueryCheckpointRestoreAfterNodeParsed( nodeID as ID, userData as String ) as Boolean
This method is called after a node, identified by its ID nodeID, has been parsed from the checkpoint file. The nodeID is not necessarily a valid node ID in the Area Server's GOM as it may have been removed since the checkpoint file was written. The User Data string is the value supplied by the call to _QueryCheckpointedNodeUserData during checkpoint creation. The return value determines if the checkpoint restore should continue.
method _QueryCheckpointRestoreAfterNodeLoaded( nodeID as ID, userData as String ) as Boolean
This method is called after a node, identified by its ID nodeID, has been parsed from the checkpoint file and reloaded into the Area Server's GOM. It is NOT called for nodes whose class or field value makeup only changed. The userData string is the value supplied by the call to _QueryCheckpointedNodeUserData during checkpoint creation. The return value determines if the checkpoint restore should continue.
method _QueryRemoveNonCheckpointNode( nodeID as ID ) as Boolean
This method is called during a destructive restore when a node, identified by its ID nodeID, is encountered in the Area Server's GOM that was not in the checkpoint. The return value specifies whether the node should be deleted from the Area Server's GOM.
method _RestoreAreaCheckpointResult( checkpointLoaded as Boolean, statusMessage as String )
This method is called when a requested Checkpoint restore has completed. The checkpointLoaded boolean denotes whether the save was successful. The statusMessage string contains a message describing the success or failure in greater detail.
First a new checkpoint is created:
callbackNode as NodeRef of Class myCheckpointCallbackClass SaveAreaCheckpoint("ImportantCheckpoint", callbackNode)
Second the checkpoint list is queried:
callbackNode as NodeRef of Class myCheckpointCallbackClass ListAreaCheckpoints(callbacknode)
And the list of checkpoints is returned to myCheckpointCallbackClass' _ListAreaCheckpointVersions implementation:
method _ListAreaCheckpointVersions( versionsString as List of String ) checkPointID as ID = 1 foreach s in versionsString if ("ImportantCheckpoint" == s) // Finally if the checkpoint we're interested in is found, it is restored to with an additive restore callbackNode as NodeRef of Class myCheckpointCallbackClass RestoreAreaCheckpoint(checkPointID, callbackNode, false) return . checkPointID += 1 . .
Area Checkpoint restoration example
Say you save a checkpoint, when an object (the blue sphere) is on the left side of the area:
Then you move that sphere to another location, and add a new object:
You then do a restore, in one of two possible ways, an additive restore, or a destructive restore: