The Snapshot module provides
a mechanism for saving and restoring the state for a collection of objects.
Unlike TADS’ saveGame(), restoreGame(), and undo() mechanisms, which affect the entire game state, the
snapshot pattern allows an author control down to the level of an individual
object.
Any TadsObject class object’s state can be saved as a snapshot by
executing its saveState() method.
foo.saveState();
The object’s state at this
point in time is stored in a snapshot object that is then added to the object’s
snapshot list. You can build a queue of object state images by simply issuing
multiple saveState() statements.
To restore an object’s state
to its last snapshot, simply execute its restoreState()
method:
foo.restoreState();
The object’s state will be
restored and the snapshot removed from its snapshot list. Multiple rollbacks of
the object’s state can be achieved by issuing repeated restoreState() statements.
Each time a snapshot is taken
of an object’s state a new clone of
the object is created and stored in the snapshot table using the TADS 3 createClone() method.
A snapshot is “shallow” in that properties with
object datatypes reference the same object as the original object. Any change
made to the state of the referenced object is reflected in the snapshot.
TADS 3 allows an author to save
a game and restore it, or even undo the consequences of a player command.
Snapshot provides a means for an author to save and restore an object’s state,
which provides the opportunity for an author to check for specific state
changes, or to use an object to monitor for state changes, rolling back the
state of a given set of objects.
In TADS 2, for example,
executing travel direction properties might result in game-state changes, which
made it difficult to develop an Exits command. Although TADS 3 library adopts a
different approach to travel direction properties, similar situations arise
where it might be desirable to rollback state changes that result from a
tentative exploration of properties.
Using undo() to rollback game-state is inappropriate in these
cases, because we need to keep information that was acquired after the
state-change was detected, but before the rollback occurred. Because undo() rolls back the state of every game object this
information is lost. Snapshot provides an easier mechanism for saving and
restoring the state of a subset of objects, retaining information acquired
before the rollback occurs.
The idea is that an object
might retain its own state, collecting information regarding state-changes
resulting from messages sent to a collection of objects, then issue a restore
of state to these other objects, effectively rolling back the consequences of
an action, while at the same time retaining knowledge regarding the
consequences of the action.
The saveStateAll() method will take a snapshot of a collection of
objects.
foo.saveStateAll(flgs, [bypass]);
The saveStateAll() method call iterates over all TadsObject class objects. The flgs parameter indicates whether the firstObj() / nextObj() loop is to
include objects, classes, or both. The optional bypass variable list parameter is a list of all objects that
are to be excluded from having their state saved.
The object that issues the saveStateAll()
statement is automatically included in the bypass list, making it exempt from
having its state saved.
The restoreStateAll() method will restore the state of a collection of
objects to its last snapshot value.
foo.restoreStateAll(flgs, [bypass]);
The restoreStateAll() method call iterates over all TadsObject class objects. The flgs parameter indicates whether the firstObj() / nextObj() loop is to
include objects, classes, or both. The optional bypass variable list parameter is a list of all objects that
are to be excluded from having their state restored.
The object that issues the restoreStateAll()
statement is automatically included in the bypass list, making it exempt from
having its state restored.
This file is part of the TADS 3
Proteus Library Extension
Copyright ©
2001-2004 Kevin Forchione. All rights reserved.