RFC - Object ID Handling

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

Abstract: The following text explains the different types of IDs (real, temp) and how IDs are used in general within Stellar Legacy. It covers the server and client side (loading, saving, creation) and how TLinkUpdate works.

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


1. Overview & Motivation

A normal Stellar Legacy game uses hundreds or even thousand of objects and some of these objects are linked to others (for example a fleet does belong to a race). For Stellar Legacy we need an ID handling system which fulfil at least the following criteria:

2. TObjectID, TLinkable

The main objects we deal with in this RFC are TObjectID and TLinkable.

TObjectID is a wrapper for a number of bytes, thus an TObjectID is not much different from an int variable. One difference is that an ID (for simplicity we call TObjectID also ID) has 6 bytes which allows approximately 2.8 * 1014 unique IDs. This should be more than enough for all purposes. Another difference is that there are two types of IDs, namely the so called "normal" (or "real") and the "temp" ones. The latter are used on the client side only (see below for more information.)

(The current implementation of TObjectID has the disadvantage that it is much slower than an int so for the future it might be a good idea to make TObjectID virtual and allow different representations of TObjectID where one could be a wrapped int4.)

The TLinkable class is the parent of all objects which need to be linked or saved to disk (for example TRace, TFleet). TLinkable has its own unique ID and also stores a list of all links which are pointing to the object. Note that you can only set links to objects which are derived from TLinkable

3. Temp IDs And Client/Server ID Space

Creating objects on the server side happens quite often (e.g. building of new fleets). Unfortunately creating objects can happen on the client side as well. The standard example is the "Split Fleet" command which makes two fleets out of one. In this case we need to introduce a new unique IDs on the client side. A possible solution would be to send a list of "unused" IDs from the server to the client, but this approach has several disadvantages:

Our solution makes use of the fact that the newly created IDs on the client side are only accessible by the creator client itself and not by other clients. In other words: if client A creates a new fleet with split fleet, client B can not interact with that fleet, because it does not exist in his data file.

The solution to solve all problems is the introduction of so called Temp IDs. Temp IDs exist on the client side only and become "real" IDs (the ones which are not temp) immediately when loaded by the server. Temp IDs are unique in one client space, but may also be used in another client space. We use the term client ID space for the ID space of one client (which may contain Temp IDs) and Server ID Space for the IDs on the server side (these ID space never contains Temp IDs).

Note: using the same Temp ID two (or more) times in different client ID spaces is no problem because no player can link objects which are created by "split fleet" and because the server takes care of mapping the Temp IDs to unique ones on the server side.

The following two sections will give some more details of ID handling on the server and client side (e.g. importing of Temp IDs on the server side).

4. Server: Creation, Saving, Loading

4.1 Creation / Uniqueness

A few words about the uniqueness of the ID on the server side: TLinkable contains a static TObjectID variable called UniqueID which always points to the highest ID used so far + 1. Thus UniqueID is always a "free" ID. After creating a new object UniqueID is increased by one. Loading is a bit more tricky: if during the loading process an object occurs which ID is greater than UniqueID, then UniqueID is set to the loaded ID and increased by one. Doing so guarantees that UniqueID always points to a unique ID.

UniqueID handling

4.2 Loading And Saving The "Server Master File"

Loading and saving of IDs to the "Server Master File" (SMF) (see RFC Load / Save for more information) is very simple. During the creation process of an object on the server side the object gets a unique ID. This ID is used once and forever for this object (the ID will never change on the server side). Therefore saving (and loading) the ID to (from) the SMF is done by writing (reading) the ID "as is".

4.3 Saving The "Player Data File"

4.4 Loading The Player Order File (Importing TempIDs)

The player order file as described in RFC Load / Save contains the actions from a player. One problem that occurs is that the client side also creates new objects and even worse: creates references to these objects. The solution to control this behaviour are so called "temp IDs" as described in the next section. (If you do not know anything about temp IDs you can skip this subsection and go on with the next section.)

Now the big question is: what does the server do with temp IDs?

Actually the answer is quite simple: for every player file the server (or to be more precise TLinkUpdate) transforms the tempID to a "real" one. How this works in detail is described in FIXME. The following example shows how the temp IDs are handled on the server side and what happens with temp IDs as well as real IDs.

As you can see there are two clients and one server which use the same set of real IDs. On the server side UniqueID always points to the next unique ID. As mentioned below all objects created on the client side get temp IDs. Note that both clients use the same temp IDs, but that within a client all IDs are unique. Also note that the server has a "copy" of all (non-temp) objects in his ID space. (Of course it can happen that two clients have information about the same object. In this case both clients will use the same ID in their client ID-space. For simplicity this is not shown in the following images.)

server and two clients

When client 1 completes his turn he sends the Player Order File (POF) to the server (1). All objects within in the client ID space (including the temp IDs) can interact with each other. The next step for the server is reading the POF and mapping the temp IDs to real ones (red arrows). All links which refer to these (former temp) objects are automatically updated so that they point to real IDs after the loading process has finished. Updating the links is done by TLinkUpdate.

integrating client1 temp IDs in server ID space

Client 2 has created only one new object and after sending his POF to the server file this temp ID becomes a real one in the same way as this was done for client 1. Note again that the same temp ID was used by both clients.

integrating client2 temp IDs in server ID space
Finaly the server has
clients read player data file
As you can how to integrate temp IDs in the server and transform them to unique IDs

4. Client: Creation, Interaction With The Server

4.1. Client ID Space (Temp IDs)

Problem: client also creates IDs -- Example split fleet

possible solution: send list of available IDs to client bad: bad width, don't know how many IDs the client needs, not easy to find free IDs without wasting too many solution: temp IDs nobody else can refer to these IDs (only races under the command of the player) temp IDs are unique in _one_ client space, but may also be used appear in another client space => server has to solve this having two times the same temp ID somewhere is no problem because _no_ player can refer to other temp IDs (he can refer to other IDs though)

4.2. Cheating Clients

Of course we have to assume that the Server Master File is all the time valid. Than the only chance for a cheating client is to manipulate the Player Order File (changing the Player Data File of the Player History File will not effect the server). The Player Order File contains the actions and therefore real as well as temp IDs.

  1. Changing real IDs:

5. Things To Consider For The Future


ChangeLog:

$Log: RFC-ObjectID.html,v $ Revision 1.3 2001/11/15 12:10:03 mkrohn5 various updates Revision 1.2 2001/08/01 16:52:46 mkrohn5 improved documentation and added 4 new images Revision 1.1 2001/07/31 23:55:06 mkrohn5 new rfc describes the ID handling used for SL (not yet complete though)