RFC - Loading And Saving Game Data

Version: $Id: RFC-LoadSave.html,v 1.4 2001/11/15 12:10:03 mkrohn5 Exp $

Abstract: The following text gives an overview how loading and saving of game data in Stellar Legacy works. FIXME

Please address any suggestions or comments about this RFC to our mailinglist.


1. Definitions

To avoid misunderstandings we define that

2. Storing data in files

First of all one needs to define what kind of data has to be loaded from (respectively saved to) files and who has access to this data.

2.1 Game StartUp

Creating a new game and starting gameplay consists of several steps, namely:

  1. The Universe Definition File (UDF) stores all data describing the universe. That means the rule set and campaign data (the latter includes the position of systems, events etc.). Note that this data is only accessible for the server.
  2. The server reads the UDF and the game master decides which of the data should be made public (e.g. he could decide that the game rules and the galaxy size, shape etc. are public, but the exact position of the systems is not. Out of this data the server generates the Game Description File (GDF) which is public available.
  3. The client reads the GDF and shows it to the player.
  4. It also allows the player to create his Race File (RF) according to the rules described in the game description file.
  5. If the race file is conform to the GDF the race file is send to the server (which of course also checks if the race file is valid).
  6. Now the server puts everything together (and adds some additional data such as the starting points for the players) and finaly writes the Server Master File (SMF) to disk which contains all the game information. This file only resides on the server and is basically the full game database.

StartUp Overview

2.2 Game Play

After the game is initialized the normal game play is a bit different from the Game StartUp phase described in the previous section. Apart from loading and saving the files

  1. All information the server needs is now stored in the "Server Master File".
  2. The players transmit the Player Order File (POF) to the server. The POF contains all orders for the next turn.
  3. The server than resolves conflicts and interactions between the players, and stores the overall data in the SMF.
  4. The information for the players is saved in the Player Data File (PDF). This file is than send to the player.
  5. The player uses the client to combine the PDF and the Player History File (PHF).

Game Play Overview

FIXME this generates the game files: - player data file: the file sent to the players to generate the turn. This is a small part of the server mega-file, containing only the information available to a specified player at a specified turn. - player order file: the file sent back to the server by the players. it contains only a list of action and nothing else. All actions are checked for consistency against the server mega-file to prevent cheating. - player history file: just like in stars, keeps track of the data a player saw in the past."

3. Transport Of Data

This section describes in more detail how the objects load and save the data to (respectively from) disk. If you are interested in implementing load and save for your own class you can skip the subsections 3.1 and 3.2 and move on to 3.3 which describes everything necessary to write the methods.

3.1 Data Package

A data package is a wrapper for all kind of elementary data, mostly used to transfer data between the parser and the Load & Save methods of the different classes. More complex data (e.g. TPlanet) is handled as a composite data object consisting of many data packages. It is important to know that TDataPackage is not only a wrapper but also stores the type of the stored data. As said only elementary data types are part of TDataPackage. At the moment these elementary data types are: The following diagram gives an example for the data (here: int4) and the TDataPackage object.

TDP example

pData points to the real data. Setting bAutodelete to true means that TDataPackage will delete the data in the moment pData is changed or in case the data package itself is deleted. Note also that it is possible to give each data package an identifier which will be useful for finding a specific data package among other data packages (see 3.2).

Assuming you have a pointer pPackage to a TDataPackage the following code gives you the content of the data package:

*pData = *( (string*) *pPackage );

Note that TDataPackageList offers several methods which make things a lot easier and thereby reduce the need to understand to almost zero. Be careful about the auto delete feature of TDataPackage. If you need the data you should make a copy, like in the example above.

3.1.1 Adding Another Elementary Data Type To TDataPackage

It should be quite easy to add another elementary data type to TDataPackage. All you have to do is:
  1. Adding another type to tType,
  2. Write the constructor, conversion operator and SetData methods,
  3. make the obvious changes in CheckAutoDelete(),
  4. and finaly adapt TDataPackageList::WriteDataPackage.
  5. (Perhaps you might also want to write Add() and Get() methods for TDataPackageList)

3.2 Data Package List

the order is not important block type => see TDataPackageList::Save => unique identifiers within one block
Data hierarchy including TDPList
deleting and so on

3.3 Writing Load & Save Methods

Example: Loading Stellar Objects

3 types of objects: * elementary objects - int, string, TObjectID => handled in TDataPackage * object which are data elements of other objects - TWaypoint * data groups like TGalaxy are represented as { data }
system {
  stellarobject = {
    property = {
      linkable = {
        id = [5,0,0,0,0,0];
      }
      creator = [0,0,0,0,0,0];
      owner = [0,0,0,0,0,0];
    }
    galaxy_link = [4,0,0,0,0,0];
    pos = {
      link = [0,0,0,0,0,0];
      pos = vec3d(0, 0, 0);
    }
    waypoint = {
      autodelete = true;
    }
    speed = 0.00000;
    name = "Antares";
  }
}
Stellar Objects ... load galaxy first .... ... parser reads data => TDataPackageList (example) => create right stellar object (mention TRuleSystem- also one of the important objects) => call: stobj->Load(...) which will then do the following.... => add the stellar object to the right galaxy another example: TPList?

4. File Format

As mentioned in the previous sections the order of the data is important. For example the galaxies should be read before the stellar objects. The following list gives a complete overview of the order of the data.
  1. TRuleSystem
  2. TRace
  3. [TGalaxy, TStellarObject]

3.1 Technical Details

Copying TDataPackageList

1.