EgoWiki > Documentation > GameSavingPlans	EgoWiki webs: Main | TWiki | Know | Sandbox
	Documentation . { Changes | Index | Search | Go }

Plans for Allowing Players to Save Their Games

At least for now, we are going to attempt to allow saving of the game by a full dump of state information, including lua data, to file. This will be difficult, however, since Zippy's state includes data maintained by both C and Lua code, and since it involves many pointers and reference loops. To help with this, I've made up a simple framework for saving such data to file and restoring it.

The Savefile Framework

The file savefile.h defines functions for writing savefiles and reading them. In this scheme, data to be saved is divided up into "objects," which consist of two kinds of information: references to other objects, and strings of binary data. References are simply C pointers to sections of memory which represent the objects they refer to in some fashion.

When a savefile is written, the savefile framework keeps track of the size of each object in memory. It interns objects, assigns them index numbers, and translates references accordingly.

When a savefile is read, the framework allocates the memory for each object according to the sizes given in the writing stage and resolves the references back to C pointers. It then calls a callback for each object, which is responsible for determining the type of the object and restoring it using the references and data that were stored with it.

restore_first() and read_reference_restoring_first()

Caution must be excercised in calling the above-mentioned functions. The general rule is that when a particular object is being restored, as much information as possible should be retreived by other methods and stored before one of these functions is called. For example, the function to restore a Lua table must call read_reference_restoring_first(), but it does so only after creating a Lua reference for the table and storing it in the allocated memory. This is so that other objects which refer cyclically to the table will be able to work with this reference without referring to uninitialized memory.

get_object_data() and reset_object_data()

The savefile framework provides two functions for accessing object data. The first function provides a simple iterator over the data segments in an object, returning the first datum first, the second next, and NULL after the last segment has been returned. reset_object_data() can be used to put start the process over again with the first datum.

The conventional use of these functions in the restoring of a particular data type is as follows:

• Call reset_object_data() first. Sometimes other restore functions will

• Call get_object_data() in order for each data segment needed to restore

Note: The memory pointed to by the return values of get_object_data() are freed after the current savefile is restored. You should never save these pointers for use outside the scope of the restore function, and you should never attempt to free them.

Representing Lua Data

The mapping of C structures to the framework above is relatively simple, but this is not the case for Lua data, which is not normally referred to using C pointers. The file luasave.h defines functions that save and restore lua data. The method employed is to intern each object to be saved, mapping it to a C pointer to an integer, which is itself a canonical Lua reference to the object. This pointer is used within the savefile framework to represent the object and to refer to it.

Interacting with Saved Lua Data

If a C structure is being saved, and it needs to store a reference to some Lua data, the appropriate method is as follows:

1. Push the Lua value onto the stack.
2. Call save_lua_value() on it.

This will add the Lua data to the file and associate a reference to it with the C structure in the savefile. When the C structure is to be restored, the appropriate method of retreiving the Lua reference is as follows:

1. Call read_reference_restoring_first() to restore the Lua data and retreive a C pointer to a Lua reference to it.
2. Call lua_getref() to push the Lua data onto the stack.
3. Make a new Lua reference to the data. Do NOT save or refer to the pointer or Lua reference returned by read_reference_restoring_first(), as both will be released when the restoring process is complete.

Savefile Representations of Lua Data

For your reference, here's how Lua data is represented in the savefile. As you can see, at this point every Lua value starts with the string, "LUA". I may change this as the framework matures.

Nil:

Number:

String:

Table:

Userdata:

Object Headers

Saved objects fall somewhat arbitrarily into two categories: those containing Lua values and those containing some other kind of value. To differentiate, each object should start with one of two four-byte tags, "LUA\0" or "DATA", corresponding to the integers 0x4C554100 or 0x44415441.

Note: the integers given above correspond to different binary representations depending on the endian-ness of the platform. adatasave.h defines a constant ADATA_TAG, which should be compared to the tag interpreted as an integer. An analogous constant, LUA_TAG, is defined by luasave.h.

C Structure Representations

For reference, here are the representations used for various C structures in Zippy. Note that all structures begin with the ADATA_TAG mentioned above, followed by a constant from the DataType enum defined in luascript/data.h.

Vector:

Range:

List:

A list will be stored from Node** (or, equivalently, List*) to the following representation:

Class:

Instance:

-- ElminI - 21 Oct 2004