Saving and Loading Individual Objects
<< previous | Chapter 11. Archiving, Dearchiving and Networking Objects and Simulations | next >>

## Saving and Loading Individual Objects

This technique is used to export and import individual objects or subsets of objects in a simulation. When an object is dearchived with this technique, a new instance is created for the saved object and loaded into a running simulation. This approach is in contrast to the method described in Saving and Loading the Entire State of a Simulation the section called “Saving and Loading the Entire State of a Simulation”, which creates an entirely new simulation from an archived world. The steps described here also apply to sending and receiving objects over a network, as described in Sending and Receiving breve Objects the section called “Sending and Receiving breve Objects”.

### Saving and Loading Objects With No Dependencies

In a "simple" object archive, only a single object is encoded. If the object has `object` variables or `pointer` variables, they will be set to 0 when the object is dearchived. All other variable types will be restored to their pre-archived values. For simple object archiving and dearchiving, no additional code or preparation is required.

### Saving and Loading Objects With Dependencies

Variables of type `object` and `pointer` cannot be automatically maintained without special treatment. This is because an `object` may reference another, which in turn references several others, and so forth. If all `object` variables were maintained, then a huge chain reaction would result every time an instance was saved.

To avoid this, saving objects does not include an object variable unless the the object being saved has declared it as a dependency, using the Object method add-dependency. If you define an object, Y, as a dependency of X, then saving X will also save Y. Loading the saved instance X will also recreate the instance Y.

Because adding dependencies also has the potential to lead to chain-reactions of archiving, it should be used with care. Generally, an object should only add dependencies on objects it has created and for which it is exclusively responsible. So while a simulated creature might legitimately add a dependency on an object containing its genome or an object which determines its movement (a "brain"), it would be inappropriate for the object to add a dependency on the controller object, or other creatures in the world.

When an object is to be archived using this technique, the user-supplied method `archive` is executed for the object. In your `archive` method, you should include code that might be needed to prepare the object for archiving such as updating variables which will be required when the object is dearchived. Your `archive` method must, on success, return 1. Any other return value is considered failure and will abort the archive.

When an object is to be dearchived using this method, the user-supplied method `dearchive` is executed for the object. In your `dearchive` method, you should include code that might be needed to restore the state of the object, or to inform the rest of the simulation of its presence if necessary. Your dearchive method must, on success, return 1. Any other return value is considered failure and will abort the archive.

Once dependencies, archive methods and dearchive methods (all of which may prove to be unnecessary for most straightforward classes) are addressed, you may initiate an archive using the Object method archive-as-xml.

To dearchive an object previously archived with this technique, use the Control method dearchive-xml. Note that this creates new instances of the objects in the archived file, instead of "filling" an existing object.

<< previous | Up | next >>
Chapter 11. Archiving, Dearchiving and Networking Objects and Simulations | Table of Contents | Saving and Loading the Entire State of a Simulation