This document describes version 2 of the Virtual Universe System (Vu2). Vu is primarily an entity management system which also provides seamless support for:

The Virtual Universe System consists of two main components -- the Entity Database and the Event Manager. Although the operation of these two components is somewhat segregated, they are designed to work together, and it is inadvisable to attempt to operate the Entity Database without the Event Manager. This is primarily because of the way the Entity Database works to ensure that an entity is not released (and it’s allocated memory freed) until after all threads and internal Vu contexts have been informed of the pending delete.

One of the driving factors in the design of Vu and the selection of C++ as the implementation language was to ensure that Vu could very easily be customized to fit the needs of the target game without modifying the Vu code itself. This is accomplished primarily though the judicious use of inheritance and strategically placed virtual functions. In addition, Vu provides some key helper components, such as filters and iterators, which are small classes which work with the other Vu classes to modify the behavior of those components. For example, a VuFilter subclass can specify the sort order for an ordered collection (such as a VuOrderedList or a VuRedBlackTree), as well as set membership (specifying whether or not a given entity belongs in a collection at all).

Vu2 was tested with MS Visual C++ version 4.1, though the source release uses a makefile approach (using nmake) rather than the MSVC project files. This allows the most flexibility in good source code control and independence from client project configuration. Some client projects have extended the makefiles, merging the Vu library with their own environment, while others have integrated the Vu source distribution into their own project files.

The Vu package is delivered with the following directory structure:

The \VU2\INCLUDE2 directory contains the files that Game Developers will need to include in their source code if they wish to use the Virtual Universe system. See the INCLUDE FILES section for a detailed description.

• apitypes.h includes macros and data structures that define or rename certain data types that are used by the Vu modules.
• vu2.h is the system include file. This has #defines which are used to determine which of Vu’s components are compiled in, as well as an #include directive for each of the needed header files from \VU2\INCLUDE. All compile time options specified by the user are in this file.
• netapi.h is a definition of the net layer interface. It is likely that this file will disappear from the face of the earth in a near future release of Vu2.

The \VU2\SRC directory contains the source code for the entire Vu system:

• Vu source code:

vu.cpp the Vu initialization and ‘thread’ implementation.

• Internal header file:

While the emphasis for the Virtual Universe has been directed towards multi-player situations, single player systems can also use the Virtual Universe to help organize data.

The following bullets list the game developer configurable elements of the Vu system.

If you are compiling this system from the source code, the following define switches are supported:

VU_USE_COMMS -- define this to activate comms support. If inactive, the event system will

never dispatch messages to the comms layer nor poll for events.

VU_AUTO_UPDATE -- Sets up and maintains a stream of VuFullUpdate events, send at standard

VU_THREAD_SAFE -- Causes activation of VuEnterCriticalSection and VuExitCriticalSection,

VU_AUTO_COLLISION -- Turns on automatic collision detection. This tests for collision between

all entities in the database which have the collision_ flag set to TRUE, every

frame. Most games will want to limit the scope of this a bit, although Vu does

a fair job of limiting collision checks to only those entities which are near to

each other (see VuGridTree for more details on this).

This #include file contains macros, typedef’s and data structures that are used through-out the Vu system. Game Developers should include this file and use the same data types to assure data compatibility. Note that scalar values are typedef’d to float in the distribution, but can easily be changed to double or converted to a fixed point class type implementation. Note that VU_SESSION_ID and VU_ID are defined as class types, with provided cast operations to unsigned short and VU_KEY (a typedef of unsigned long), respectively. In most cases, most compilers will to the appropriate automatic conversion, but explicit casting is required where varargs are used (as in printf).

Vu strictly adheres to several conventions. Understanding these conventions makes it easier to understand the code.

Below are the naming conventions used in Vu. All names use descriptive intercap, and underscores are only used in macro names and as a trailer to member variables.

• VuNameString - Vu defined classes, structures, and global functions.
• vuNameString - Vu defined global variables
• nameString_ - (with trailing underscore) class member variable
• VU_NAME_STRING - Vu defined macros and types, classes which are basic types also follow this convention
• VuxNameString - a global function declared and used by Vu, but defined by the game programmer.
• vuxNameString - a global variable declared and used by Vu, but defined and set by the game programmer.

In general, return values fall into five general categories:

1. Pointer values – (e.g. VuDatabase::Find(VU_ID id) ) Where a pointer value is returned, a zero value indicates that the function failed, while a non zero value indicates success and a valid pointer.
1. VU_BOOL – (e.g. VuEntity::IsLocal() ) A VU_BOOL will have a return value of TRUE (1) or FALSE(0). The meaning of these should be obvious.
1. VU_ERRCODE – (e.g. VuEntity::Handle(VuEvent *event) ) This returns one of the following:

• VU_ERROR (-1) indicates that an error condition occurred which caused premature return
• VU_NO_OP (0) indicates that no error occurred, but no action was taken either
• VU_SUCCESS (1) indicates that the function action completed successfully

1. int – An integer return value usually indicates a count of some type. 0 means a zero count, a negative value indicates error.
1. other – (e.g. VuEntity::Id() ) other return types are almost always access functions to internal data. The returned value is the value requested. There is no inherent VU convention to indicate error here.

One of the most significant features of the Vu Entity Database is its ability to manage entity utilization without reference counting or garbage collection. Very basically, entities are allocated using the new operator of C++ and then inserted into the Vu system by calling vuDatabase->Insert() with the new entity. Vu is then responsible for calling the delete operator when it is safe to do so. As a result, application code should not call delete on VuEntity’s which have been added to the entity database. This is a slight divergence from the usual mode of memory management, but adopting the Vu convention does pay off. There are also two other Vu components with slightly different memory management conventions as well. All three are summarized below:

Deallocation: user must free the filters they pass to Vu, Vu will take care of the copy.

The following figure illustrates how the Vu Entity Database and Event Manager work together with the game code and communications layer.

• Starting from the bottom, the low-level communications layer provides an interface to the hardware. This level is responsible for interfacing with the hardware driver (for a modem or direct connect interface) or the net driver (for a Winsock interface, for example). Vu itself interacts with the communications layer using a well defined interface. Messages are always received through a polling mechanism, and outgoing messages are written to the communication layer as soon as they are posted. Any required buffering is left up to the communications layer.
• The Event Manager is next, and it provides an interface between the Communications Layer and the Entity Database, as well as a generic event posting and dispatching system which can be used directly by the Game code. Whenever an entity is created, deleted, moved, changes state, or changes station ownership, the Event Manager ensures that each thread on each station has an opportunity to see the change in state. Event Posts are sent immediately to the communications layer, while events received from the communications layer (or the game, for that matter) are placed in each interested queue for processing on dispatch. This allows for multiple threads, each with interest in the same event, to process the event at their own time. The Event Manager is also used to post Delete events and guarantee that each control thread is notified of the pending delete before the memory is finally released.
• The final module is the Entity Database. This is a database of all of the objects in the game. Whenever an object (entity) is inserted into or removed from the vuDatabase, the Entity Database will automatically post appropriate event to the Event Manager. This will propagate the change in the database to all of the other machines on the network.

This section briefly explains the bare minimum skeleton required to integrate and run with Vu 2.0. The code provided here can be used as a starting point for integrating the game code with Vu, or copy/edit of the test code found in vu2\test or the zoomers code found in vu2\nettest.

The sample provided here is really bare bones. The entity class used is just the raw VuEntity, which has only the most basic of variables. In addition, only one type of entity is provided, game time uses a positively silly increment scheme, and the main loop is also a toy example. Since the nature of the game loop and time keeping are generally unique for each game (and generally involve a fair amount of setup code) the simple schemes provided here should be a sufficient place holder. Finally, this example assumes that VU_USE_COMMS is not defined (see the chapter on VuSession to get information on how to connect to a network).

The organization of this example will include brief snippets of code with interspersed annotation.

This example includes stdio.h (for printf) and vu2.h (for vu). As stated earlier, we are assuming that VU_USE_COMMS was not defined. For that matter, let’s assume that none of the configuration options are defined.

These defines create our entity type so that we can determine at run time what kind of an object we have from it’s VuEntity pointer. This allows us to safely cast to a more specific class type given a generic pointer. This is quite useful as all of the iterators return pointers to the VuEntity rather than the specific subclass. In addition, associating a type with a class allows us to create an instance of the correct class type from a data stream received from the network or from a file. Note that the entity type is assigned at a value higher than the value of VU_LAST_ENTITY_TYPE. It is important that the game programmer adhere to this practice so as not to conflict with internal Vu entity types.

The domain defined is a number between 1 and 31. It is used to properly set the vuxLocalDomain variable domain below. Basically, the vuxLocalDomain is a bitmask which indicates which kind of entities the current program is capable of managing. Each entity notes what domain it belongs in, which allows the program to quickly identify whether or not the entity can be correctly handled or managed. This subject will be dealt with in more detail in the FAQ.

The database size is the size of the hash table used as the Vu database. This number should be a prime number, and should be around 10%-20% larger than the largest expected database size, though performance will not suffer greatly if this value is exceeded.

Vu requires that the application define, initialize and maintain four global variables. Of these, only vuxCurrentTime needs constant update. All of these variables are defined as external because Vu itself has no way of knowing what the proper values of these variables should be. vuxCurrentTime is the global which defines the current game time as used by all entities for position, movement, smoothing, etc. vuxSlaveSmootherSettings is needed for dead reckoning and smoothing in a network environment and is rather meaningless in a single player environment like the one we have in this example (but is still required, and is fairly small and as such is included in this example). vuxLocalDomain was discussed above, while vuxGameName is just a string to uniquely identify network packets from this game when they are broadcast over the net (so that other games also using Vu which happen to receive these packets can drop them).

The entity type table in our toy example only defines the VU_SAMPLE_ENTITY_TYPE identified in the defines section above. This is the data for the VuEntityType field of our VuEntity. This table is used to return a pointer value from the VuxType() global function (below). Note that our example here uses a static table, but also that Vu only accesses this table through the VuxType() function. As such, it is perfectly okay for an application to populate this table with data read from a file instead of the static method used here. The only requirement is that the VuxType() function return a valid pointer which is guaranteed to remain valid from the time Vu is initialized until Vu is shut down.

Very quickly, the elements of this table mean the following:

• class id – the type of the class – must be greater than VU_LAST_ENTITY_TYPE
• collision type – identifies the collision detection method used. If this value is set to 1, Vu will use the default collision detection scheme.
• collision radius – identifies the collision radius (roughly the size) of an object. This size is used to create a box of space used as a collision distance. This box is always aligned with the coordinate system rather than the VuEntity.
• Class Info – this is an array of eight bytes which allows a hierarchical mechanism for classifying objects. This field is neither defined nor used directly by Vu in any way.
• Update Rate – This field is only used if the VU_AUTO_UPDATE flag was defined. It defines the interval between the automatic updates.
• Update Tolerance – This field determines the maximum allowable time between updates. How Vu deals with violation of this tolerance is not defined in the current release.
• Damage Seed – This value is used to initialize the damage_ field of all newly created entities of the defined type.
• Hitpoints – This value is used to initialize the hitpoints_ field of all newly created entities of the defined type.
• Major and minor revision numbers – These numbers can be used to determine if an entity restored is of the same generation as the implementation of that type in code. The suggested convention is that all entities of the same major revision have the same data foot print on disk, while minor generation changes may have different behavior, tolerance or performance characteristics (for example, a later revision of a plane may have a lower service ceiling than a saved image of the same type).
• Create Priority – This field is used to resolve name clashes in the unlikely circumstance that two entities of different types but the same ID are being managed by different sessions on the same network in the same game. The first tie-breaker is the create priority, where the lowest value wins. All developer assigned priorities should have a value higher than the VU_CREATE_PRIORITY_BASE (currently set at 100).
• Management domain – This is a byte variable whose value should be between 0-31. It represents the management domain of the entity as defined above.
• Transferable – the first of four flags; this flag indicates that entities of this type can be managed by sessions other than those that initially created them. Most entities fall into this category. The VuSessionEntity, and perhaps certain player entities fall into this category.
• Local – This flag, when set to true, indicates that the entity is entirely local in nature and should not be sent over the network. Entities which represent graphic effects or player bubbles on the current station might fall into this category.
• Tangible – This flag is not used directly by Vu, but can be used by client code to indicate whether or not an entity should be treated as a graphic entity in any way.
• Collidable – This flag is only used by Vu if VU_AUTO_COLLISION is defined. In that case, all entities with this flag set on are checked against each other for collision each frame. If the define is not set, then this flag can be used by the developer as seems to make sense.

Vu requires that the application define six global functions.

VuxCreateMessage is responsible for translating a message type to a newly allocated instance of the appropriate message. As we are defining no custom message types, returning 0 is the expected behavior. Where a valid pointer is returned, Vu will call the Read() method of that message with a datastream to populate the message instance.

These two messages are called when Vu detects a time difference between the network clock and the local machine’s clock. The network keeps time in milliseconds, and so if the local game time is kept in different units, conversion will need to take place.

This is the VuxType function mentioned above. It takes an id and maps it to a VuEntityType pointer. As mentioned above, this value must be a valid pointer over the lifetime of the execution of Vu, but may otherwise be set using any method.

VuxCreateEntity is used to translate a type and data into a valid newly allocated and populated class instance of the given type. This is used for translating a data stream received from the network or from a file into a valid local entity pointer. Where Vu calls this function, it takes care of adding it to the database, so there is no need for this function to do so.

The main function provided here glues everything together. As the code itself is relatively small and easily understood, this annotation will not delve into much detail.

The only "magic" parts of this sample are in the initialization of the VuMainThread and the database iteration. When the VuMainThread is initialized, it also initializes all internal variables needed by Vu (most notably the vuDatabase pointer used later in the function). Note that despite its name, this object does not start up a Windows 95 thread or any such thing, but is rather a software representation of the Vu context for such a thread. For multithreaded access to Vu, each thread should have its own VuThread object, and each thread should call the VuThread Update() function periodically to allow Vu to do cleanup, message posting and processing, etc. Note also that the database size is passed into the constructor for the VuMainThread. This value is just passed on to the vuDatabase constructor.

The other "magic" part is the iterator which is used to iterate across the database. This iterator is an external context to the database collection which allows multiple pieces of code to simultaneously iterate across the same collection without impacting each other. In fact, because of the way Vu manages its memory, it is even possible for different contexts or threads to remove entities from a collection without impacting each other. The only odd thing about iterators is that the GetFirst/GetNext calls are made on the iterator rather than the collection. But then this is only odd because it is unfamiliar. Once this pattern falls into general use, it becomes as easy to use as stdio.

Finally, cleanup for Vu happens when the destructor for the VuMainThread is called. Because we created our main thread on the stack, this happens last, just before we return from main. This is exactly as it should be, as the Vu cleanup should happen after all other vu components are cleaned up. Vu will also purge is database on shutdown and call the destructor for each of these entities.

Going forward, this document will discuss some of the other features of the Vu system when the components are introduced. For example, we will look at how to create our own entities when we look at the VuEntity class. But first, we will look at the design of the Vu system as a whole and how each of the parts fit together.

This section will discuss the architecture of the Vu2 system. It will briefly discuss each of the components, and describe their relationship to each other. As this is a C++ component design, this section will use object-oriented language and inheritance diagrams to illustrate the concepts.

The basic design of VU is broken into two primary areas: Entity database and message management. The Entity Database includes many sub-components (VuEntity, VuCollection, VuDriver, VuThread, and VuSession) which will each be briefly discussed here and in more detail in the section dedicated to that sub-component. Message management provides a class based representation of events and requests as well as a standardized mechanism of posting and dispatching these messages in a network and a standalone environment.

The Entity Database is the largest component of the design, and is composed of several shallow class tree definitions. These are designed to be used together, but if some features are not needed or used, then some of them (such as smoothing and dead reckoning, and in fact the entire VuDriver class) can be removed without much trouble. The base classes defined are listed below:

• VuEntity – the base class for all game entities managed by Vu. All entities distributed to other machines on the network must inherit from this class.
• VuCollection – this is the repository for VuEntities. Vu provides a set of collection types, including ordered and unordered linked lists, a hash table, and a red-black tree.
• VuDriver – This is the base for classes which provide motion or modeling behavior to entities. It is also the base for smoothing and dead reckoning.
• VuThread – This is a Vu representation of a logical control thread in software. It does not directly implement threads, though it does work well with them. Another way to think of the VuThread is as an interface to the VuMessageQueue.
• VuSession – This sub-component included the VuSesssionEntity and the VuGroupEntity. These represent users and groups of users (game instances) respectively in a network environment.

It is important to note that most of the central functionality required by the game must be written by the game developer, but the interface provided by VU will make it simple for the game to save to / restore from disk, serialize over the network, transfer ownership of entities between machines, etc.

At its simplest level, all that the event module of Vu provides is a message queue and a well defined asynchronous interface to messages from remote machines. Vu also provides a class based interface to events, a large collection of pre-defined event types, and a simple method to add new event types. The base classes defined as a part of the Event Management component are listed below:

• VuMessage – the base class for all requests and events.
• VuMessageQueue – The repository for unprocessed messages. Where multiple message queues are used, messages will be posted to each interested queue (where interest is defined by a VuMessageFilter, discussed later).

Note that the event queue interface will not support multiple indices. Instead, the interface will logically present a single queue to each thread (or code segment) which requires access. Events which are queued will be sent to each applicable queue with a single PostVuMessage call.

The Entity Database provides an interface to game data, organized into game objects. Game objects which are managed by VU are called VuEntities, named after the base class for all such objects managed by VU, the VuEntity class. The Entity Database provides functionality where possible, and interfaces where functionality cannot be easily or adequately provided by VU. In addition, the C++ inheritance and virtual function mechanism makes it relatively easy to override default VU implementation. Even so, virtual functions will be used as sparingly as possible so as to minimize the performance hit for common but trivial class data access.

The functionality and interface feature set provided by the Entity Database follows:

• VuEntity memory management (safe entity allocation and cleanup).
• VuEntity state propagation to all interested machines in a network environment. Several complex issues (such as smoothing, dead reckoning, entity transfer, and network node startup and shutdown) all are covered by this feature.
• Storage of the Entity Database to a file system, and retrieval from same.
• Iteration across subsets of the VuEntity database. Such subsets (and the sort order) are defined by specification of a VuFilter.
• Three space collision detection between managed entities.
• Time (CPU) efficient access to individual elements and collocated groups of elements.

What follows is a discussion of each provided class tree in the Entity Database. The presentation begins with a class hierarchy diagram, followed by a brief discussion of the components and their roles. The class definition and the interface functions are discussed in more detail in the chapter dedicated to that component.

Class diagram notation is relatively simple. Base classes are positioned at the top of the tree in ovals. Subclasses appear underneath, with arrows pointing to the immediate parent class. Classes supplied by VU are given in solid ovals, classes which must be supplied by the game developer are given in dashed ovals. Below is the VuEntity Class tree:

The base class for all entities managed by VU is the VuEntity. In addition, each ‘type’ of object in the game can have its own entity type, represented by an instance of a VuEntityType. Note that there is no intention to directly correlate a C++ class definition with a VuEntityType, though it should be possible to map a VuEntityType to a VuEntity subclass, just not the other way around.

The classes in this diagram are as follows:

• VuEntity – This is the base class for all transferable and storable game objects. It is also possible and desirable to make purely local entities inherit from VuEntity as well, in order to make use of the collection and iteration facilities of Vu. All VuEntities have an Id which uniquely identifies them in the network, and an owner id which identifies which session (computer) is currently responsible for managing (sending updates) on that entity.
• VuGroupEntity – This VuEntity is a representation of a group of users. In most cases, this represents an incarnation of a running game session. A VuGroupEntity has a list of VuSessionEntities which are currently playing in that game. As is true with any other VuEntity, the VuGroupEntity has an owner who is responsible for updating the group’s data, though this session should only be thought of as the server for that group entity only, not the entire game session.
• VuPlayerPoolGroup – This special VuGroupEntity contains those sessions which have not yet joined a game group, but are connected to the network. It can be thought of as a pool of players looking for a game. On the network, there will be one virtual instance of the VuPlayerPoolGroup.
• VuSessionEntity – This class represents a player (or machine) on the network. Each VuSessionEntity belongs to one and only one VuGroupEntity at a time.
• User Classes (VuEntity) – It is expected that the game programmer will create several classes which inherit from VuEntity. All game data which is sent over the network and is specific to a particular type of object will be specified in these user classes. For more information on how to make your own classes, see the section devoted to VuEntity.
• VuEntityType – This class contains a set of data which is common to all incarnations of a particular type. The base class (defined by Vu) has several flags and other values copied into each incarnation of an entity on initialization.
• User Classes (VuEntityType) – If there is additional data specific to each entity in a given game, this can be specified by creating a class which inherits from VuEntityType.

The VuCollection classes provide entity collection, filtering, sorting, and iteration. In addition, it uses a simple database locking and mark and sweep garbage collection mechanism to provide safe access for multiple threads. The class hierarchy itself is given in figure 3.

The class in this diagram fall roughly into three categories, collections, iterators, and filters. In the figure, the dashed lines between iterators and collections indicate the association between the iterator an a filter. As is true with any class, iterators may be used with any subclass of the associated class. For example, a VuListIterator can be used with a VuOrderedList or VuFilteredList as well as a VuLinkedList. Following is a brief discussion of the three categories.

The VuCollection class provides an interface to all collections of VuEntities. There is one special VuCollection, the vuDatabase (a global instance of the VuDatabase class). This collection is the superset of all entities managed by the game. The game notifies Vu of the existence of an entity by inserting the entity into the vuDatabae, and of the entities dismissal by removing it from the vuDatabase. Vu takes care of ensuring that from that time forward, all VuCollections and VuIterators currently active will accurately reflect the state of that object in a thread safe manner. In the case of entity removal, iterators currently pointing at the removed entity will not change, but the memory will not be release until after the iterator is no longer pointing at the entity. Also, iterators and Find() functions will not return entities which have been removed from the vuDatabase.

Briefly, then, here are the classes in the VuCollection heirarchy:

• VuCollection – This is the base class, and it provides common interface functions. Insert and Remove are virtual functions, under the expectation that this are relatively infrequent operations.
• VuLinkedList – This is a simple unordered singly linked list implementation. Newly inserted elements are added to the head of the list. As this collection does not contain a filter, once created, it will contain all of the VuEntities added to the vuDatabase. For this reason, it is expected and suggested that game programmers use the VuFilteredList instead.
• VuFilteredList – This class has a VuFilter (see below) to restrict inserts to a subset of the vuDatabase. Not that this filter is only checked on insert, so it is inadvisable to use filters based on changing data unless the game programmer manually maintains the state. As is the case with the VuLinkedList, inserts and iteration are cheap, while deletes are relatively expensive (order N traversal).
• VuOrderedList – This class is identical to VuFilteredList, except that the list is also ordered as defined by the Compare() function of the associated VuFilter. Iteration is still cheap, but inserts and deletes are both order N.
• VuHashTable – This is a simple hash table implementation. When created, the caller passes in a table size. As is true with all hash tables, this works best with a prime number at least 10% higher than the maximum number of entities in the collection. This hash table uses chaining to resolve collision, so the only cost of exceeding the maximum table size is in access time. Inserts and Deletes are order 1, but iteration is slightly more costly than linked list iteration. VuHashTable collections optionally take a VuKeyFilter, which translates some aspect of the entity to a VU_KEY value for comparison to key values of other entities. This value is used to determine the hash key of the entity, so it should be static over the life of the entity or future searches for that entity (post change) will fail. Lacking a filter, the hash table uses the VU_KEY coercion of the VU_ID. This collection is unordered.
• VuDatabase – The VuDatabase class is a special class which should have only one incarnation: the vuDatabse global variable (created by the VuMainThread). When entities are added to the vuDatabase, they are also added to all other VuCollections (provided that any filters associated with those collections allow the entity pass the filter’s Test() method).
• VuRedBlackTree – This is an implementation of a red-black tree, which is a self balancing binary tree. All operations on this tree (insert, remove, and find) are order log-N, though inserts and removals have a high fixed cost as well. Iteration is relatively inexpensive, but like the HashTable, keys are not unique, and each bin is a linked list. This collection is ordered, by the VU_KEY.
• VuGridTree – This specialized tree is used to maintain a proximity map of entities for collision detection and also proximity checks. It is implemented as a fixed size array of red black trees. It takes a VuBiKeyFilter, where one key is the X-dimension, and the other key is the Y-dimension. The X-dimension picks the array location, while the Y-dimension determines the position in that red-black tree. Position in the Red-Black tree is maintained whenever the entity is moved, so this increases the cost of the SetPosition() function of the VuEntity (those in the VuGridTree, anyway). Insertion and Removal have a medium cost. Iteration cost is the highest of all the collections (but is still relatively small), but the main potential concern is the medium cost for entity movement. That warning notwithstanding, maintenance of the grid tree is much cheaper than an order N-squared traversal of entities for collision detection or proximity checks. It is suggested that users of this library with 3-space collision or proximity test needs try this collection and use specialized lists or cheats if this proves inadequate.

A VuIterator is responsible for maintaining the iteration context of an iteration. Making this context external to the collection itself makes it trivial to have multiple simultaneous iterations on a single collection. Instead of providing a GetFirst/GetNext interface on the collection itself, the GetFirst/GetNext interface is in the iterator. That way, subsequent calls to GetFirst will not affect the current node pointer as is the case with built in iteration. When the programmer wants to iterate across a collection, then, he should first create an iterator of the appropriate type on that collection, and then iterate using the iterator.

There is one base class and six basic iterator types:

• VuIterator – This is the base class for iterator. As the actual iteration interface uses inline functions (in most cases) to improve efficiency, this class only provides setup and maintenance interface functions.
• VuListIterator – This iterator works on any class derived from VuLinkedList.
• VuHashIterator – This iterator works on any VuHashTable.
• VuDatabaseIterator – This iterator is exactly like a VuHashIterator, except that the collection, vuDatabase, is implied. Iterations on the database should use this iterator instead of VuHashIterator to allow for changes to the type of the VuDatabase.
• VuRBIterator – This iterator works with the VuRedBlackTree. It takes an optional VuKeyFilter, which produces a VU_KEY from the entity, or the VU_KEY form of the entity Id if no filter is present.
• VuGridIterator – This iterator takes an entity and a radius and returns all entities from the VuGridTree which are in the specified zone. Note that the zone uses a linear box radius (linear x and y distance, not square root of x-squared plus y-squared). Note also that the region is set when the iterator is constructed, does not follow the initial entity as it moves, but does return entities which move into the region after iterator creation.
• VuFullGridIterator – This is a specialized VuGridTree iterator which iterates across the entire collection. Note that in the case of slow iteration is a multi-threaded environment where movement and iteration are handled in different threads or contexts, it is possible to miss entities or to hit certain entities more than once.
• VuSessionsIterator (not shown) – This special purpose iterator is associated with a VuGroupEntity rather than a standard VuCollection. It returns all of the sessions which currently belong to that group. These sessions are ordered by VU_ID, lowest to highest.

It is possible and even likely that the game programmer will need to create specialized iterators. This can be accomplished by inheriting from the desired type and overloading the appropriate virtual functions. For more information on this, see the section on VuCollection or the FAQ section.

The VuFilter is the VuCollection component which is designed to customize access and behavior of VuCollection and VuIterator classes. A VuFilter defines set membership and relative sort order evaluation. Vu provides a few filter types which are used by Vu and may be used by the game programmer, though their actual utility may be somewhat limited. The VuCollection section will discuss in more detail how to construct specialized filters.

The filter classes supplied with Vu are the following:

• VuFilter – This is an interface class only as it defines several pure virtual functions (most notably Test, RemoveTest, and Compare) which must be defined in the subclass.
• VuKeyFilter – This is another interface class, which introduces the Key function, which returns a VU_KEY given an entity. Subclasses must define this function as well. This class is used by the VuHashTable and VuRedBlackTree collection classes.
• VuBiKeyFilter – The final interface class, introduces several virtual functions needed by the VuGridTree collection. The primary function of this filter is to convert the scalar values for x and y dimensions to VU_KEY values, which is an unsigned long by default.
• VuTransmissionFilter (not shown) – This filter is a special case filter which is responsible for maintaining the auto update collection. It is unlikely that this filter will see reuse, but its implementation (in vu.cpp) is a good one to look at for an example of how to create a specialized filter.
• VuStandardFilter (not shown) – This filter was designed to be reused, but again, actual reuse will probably be low. It allows the user to specify which of the VuEntity flags are set (collision, tangible, etc.), and whether the entity is managed locally, remotely, or either.
• VuOpaqueFilter (not shown) – This rather strange filter blocks all entities in its Test function. It can be used to create collections whose membership is determined by the game programmer rather than by the filter functions. This technique is discussed in more detail in the FAQ.

A couple notes about the use of filters. Filters may be used either with a collection or with an iterator. If used with a collection, it defines set membership. In this case, since each collection is checked on insertion and removal of an entity to the vuDatabase, insertion and removal become more expensive operations. Removal, especially needs to be handled with care, and most notably with the collections with order-N Find operations (such as the linked lists). This is an important concern because removal of an entity that is not present in the collection presents the worst case traversal. To help alleviate this, there is a virtual method in the VuFilter called the RemoveTest. This test returns TRUE by default, and should return TRUE if the entity in question could ever have been in the collection, and FALSE otherwise. For example, if type is immutable, and your game has a custom collection of all F-16s, a VuFilter on this collection could have a RemoveTest which checked the type field, and returned FALSE for all non F-16 entities. This allows a trivial rejection test prior to embarking on the worst case iteration. Setting this RemoveTest return value incorrectly will have disastrous consequences, however, as the entity will remain in the collection, and the pointer will be deleted out from under it, causing an eventual program crash.

The other way to use filters is on iteration. The GetFirst and GetNext functions of iterators take an optional filter, where the filter tests for set membership on iteration. Any entity which does not pass the supplied filter will be skipped. This interface results in slower iteration (more tests), but no maintenance of another list.

The VuDriver hierarchy provides an abstract interface to the entity motion modeling system. Since this tree is completely separate from the VuEntity tree, it is also possible to very easily change the motion model for an object at run time. While it is unlikely that a missile will suddenly start behaving like a plane or a building, it is quite possible that a plane, missile, or mech will start getting its motion data from local modeling rather than network updates.

The VuDriver class is pure virtual abstract class which provides an interface to two types of motion models: master (physics modeling) and slave (driven by network updates).

The primary purpose of the VuDriver is to do entity position consistency management on the network. It can be thought of as an appendage to the VuEntity, and an optional one at that. It should be noted at this point that the VuEntity -VuDriver relationship is one of the few constructs that has architectural implications for the game programmer. The VuDriver is set up to work best as the repository for the physics modeling of the respective VuEntities. This modeling should be done in a subclass of the VuMaster. Taking this approach allows Vu to swap a VuMaster out for a VuSlave on remote machines where no physics modeling is done (because it is already being done on the remote machine). In addition, the VuDriver hierarchy performs dead reckoning (to reduce network update requirements, as well as providing cheap pseudo physics) and smoothing for VuSlave entities. Finally, using the VuDriver architecture as designed makes it relatively simple to perform event record and playback. This is accomplished by storing away VuPositionUpdateEvents as they come through, and then rerunning the game, instanciating each VuEntity with a VuSlave as its driver, and then feeding the event stream to the entities just as if all the entities were receiving the stored events as network updates.

The VuDriver class heirarchy is shown in figure 4:

A brief explanation of the various VuDriver classes follows:

• VuDriver – This is the interface class used by the VuEntity to acquire data from the motion model. The VuEntity class has a pointer to this class and uses the Exec and AutoExec functions to spark modeling. The Exec function performs full modeling, while the AutoExec only performs dead reckoning. Both update the VuEntity position and orientation numbers. In the case of VuSlave, Exec and AutoExec perform the same functions.
• VuDeadReckon – This class performs simple dead reckoning based on the last known position, orientation, and position and orientation delta values. For the master, this, combined with alignment threshold values, makes it possible to determine when to send out a position update. This class is an abstract class. If dead-reckoning is the only method used to move an entity (no smoothing or physics), then the game programmer should create a class that inherits directly from this. However, it is not anticipated that this will ever be done.
• VuSlave – This class merely adds smoothing to the dead reckoning behavior of the VuDeadReckon class. Smoothing parameters are stored in the VuSlaveSmootherSettings class, which must be initialized by the game programmer. This is an instance class, and remotely created entities will have this type of driver by default.
• VuMaster – This is still an abstract class, as Vu can have no idea how the physics of a game should be modeled, but it does hook up dead reckoning data with generated updates.
• Master Classes (VuMaster) – The game programmer is responsible for supplying the actual Master Classes, which inherit from VuMaster, and which perform the physics modeling for entities in the game. Depending on how this physics is done, it is quite possible to have anywhere from a single master class for all entities, to one class for each class of VuEntity subclass. Note that it is also possible to switch physics models on the fly, which might be desired where a formerly intact high performance fighter jet takes a missile hit and suddenly takes on the flight characteristics of an anvil.
• User Classes (VuDriver) – Finally, if the game programmer wishes to use the driver abstraction, but no dead reckoning or smoothing, then classes designed to do physical modeling or tracking should inherit directly from VuDriver.

One final note on the architecture of the VuDriver versus the VuEntity: In many cases, this design will result in parallel class trees, where, for example, there is a MyClassEntity class there will also be a MyClassDriver class. While such duplicity is rarely a desirable design characteristic (because it splits the data for single entity between multiple places), in this case, the payoff of motion modeling independence more than makes up for this slight design inconvenience. Note also that if this simply is not acceptable, then it is possible to ditch the entire VuDriver hierarchy. In this case, the game developer is responsible for manually perform all dead reckoning, smoothing, position and orientation updates, and generating position updates, as well as reconciling remote versus local physics modeling of the entity.

The VuThread sub-component is a fairly small but very important part of the Vu architecture. Each VuThread instance is a Vu software representation of a thread of control in the game. Note that the VuThread class does not itself provide any implementation of Windows 95 threads, but does provide a context which allows multiple threads to put a ‘bookmark’ in Vu which indicates which events that thread has processed, so Vu can know when all threads or software contexts have had an opportunity to handle a particular event. This is especially important with the VuDelete event, as all threads must have an opportunity to cleanup local references to the deleted entity. The best feature of this approach is that provided that thread event processing is done in the thread’s inner loop, it is guaranteed that no references to the deleted entity will be on the stack at the time of removal.

Without further ado, review the VuThread class hierarchy in figure 5:

And the class discussion:

• VuThread – This is the base class for all thread objects. Unlike most of the base classes in Vu, this is not an abstract class and can be instantiated. This class provides a simple implementation of the Update function which simply processes the entire queue of messages for that thread. Note that the VuThread constructor takes a VuMessageFilter pointer. This filter determines which events will ultimately end up in that thread’s event queue. More on this can be found in the discussion of VuMessage and VuMessageQueue.
• VuMainThread – This class should have only a single instance, as it initializes many Vu components (including the vuDatabase) in its constructor. It should also be the first Vu component intialized, and should be the last Vu component cleaned up.
• User Threads (VuThread) – If specialized processing of the event queue is desired, or a convenient repository for thread specific data is desired, then the game programmer is free to create subclasses of the VuThread to fulfill these functions.

Note that the VuMainThread also provides the interface to joining groups. This is done to provide a centralized, accessible interface that would otherwise require yet another set of global variables. Note that the act of joining a group also connects one to the network if this has not yet been done. More on this in the following section.

This sub-component is also rather small, but is similarly important for multi-player and network play. There are two basic types: the session and the group. Very simply, a group represents a collection of sessions, while a session represents a single player (or machine) on the network. Both groups and sessions are subclasses of VuEntity. This is true despite the fact that neither sessions nor groups are tangible objects in anyway, and as such have no real position or orientation. As a result, all such position and orientation data for these entities is meaningless. However, because they are VuEntities, Vu can use the Vu collection and iteration classes without modification. In addition, any state changes on these components can be communicated via the same messages as are used for other entities. This simplified the code quite a bit. The application programmer, however, needs to be aware of the fact that Vu entities such as sessions and groups will reside in the vuDatabase alongside those entities added by the game programmer. Running a flight model on a VuSessionEntity will have unpredictable results, so make certain to check the type returned by a interator, or create a filter or filtered collection for iteration of game entities.

Figure 6 contains the VuSession class tree:

This class tree has the VuEntity class in dashed lines, as that is discussed in more detail elsewhere in this document. Below are the classes of this sub-component:

• VuSessionEntity – This class represents a player or machine on the network. It has a string which serves as the player name (or callsign) and a group id, which indicates the group with which the session is associated (i.e. the game that player is currently playing in).
• VuGroupEntity – This class contains a collection of VuSessionEntities and represents an instance of a game (where players are playing together) or a gathering point or chat room, as is the case with the VuPlayerPoolGroup, below. Groups, like any other entity, can be owned by a single session and the ownership of that group transferred.
• VuPlayerPoolGroup – This special entity is not specifically owned by any session, but is always present. When a player first connects to the network, he connects to the VuPlayerPoolGroup. Games do not generally take place in the VuPlayerPoolGroup, but rather in other groups on the net.

Note that before a session joins a group, all entities currently owned by that session must be transferred to other sessions or removed, and must be purged locally. The exception to this rule is the local VuSessionEntity, and Vu handles the transition required here.

The message management component of Vu has many classes, but the design is rather simple. Basically, each message type is its own class, and the data of the class is the data for the message. Messages fall into three main categories: requests, errors, and events. Events represent a change in the state of a VuEntity, while requests represent a request for data or for another session to take action on an entity it manages. These events can be targeted either at a specific session (machine) or at a group of machines which may or may not include the sender. The VuMessageQueue class is responsible for accepting these messages and then dispatching them in a first in, first out queue.

The VuMessage class tree is quite large, given that there is one class for each message type, but it really is quite simple, given that it is a rather flat heirarchy. Figure 7 has an abbreviated class tree:

The classes of the VuMessage tree are enumerated below:

• VuMessage – This is the abstract class of the VuMessage tree. This is the handle used by the VuMessageQueue, as well as some of the other classes.
• User Messages (VuMessage) – If the game programmer has specialized messages which fit within the VuMessage queuing system (voice packets do not fit in this category, while a broadcast or targeted text message would), then subclassing directly off of the VuMessage will work. It is expected that most programmer specified messages will inherit from VuEvent instead, however. Logically, a VuEvent indicates a state change in an entity, while a VuMessage is simply a vehicle for asynchronous data exchange.
• VuErrorMessage – This message is sent when some error condition is detected which prevents an expected action. Most often this be generated as a response to a VuRequestMessage which could not successfully be serviced. The VuErrorMessage contains in its data the message id of the message which generated the error condition, as well as an error code.
• VuRequestMessage – This is an abstract class whose children represent a request rather than an error or event. There are only three request types supplied by Vu, but if more are needed, then subclass from here.
• VuGetRequest – This request message is used to request a VuFullUpdate event from the target session for the target entity. Both the target session and the target entity can be wildcarded, indicating a general request for all entities from all sessions. Note that multiple sessions are targeted by setting the routing appropriately rather than setting some special value in the target session field, while a request for all entities is specified by setting the entity id field to a special value.
• VuPushRequest – This request message asks a specified entity to assume management of the indicated entity. This is always a targeted request, and a response should always be issued – either a VuTranferEvent (if the request was granted) or a VuErrorMessage.
• VuPullRequest – This request message is a request for the target entity to relinquish management of the entity to the requester. As with the VuPushRequest, a response is guaranteed, and should come as either a VuTransferEvent, or a VuErrorMessage.
• VuEvent – This abstract class represents a state change on an entity. Most messages (both in terms of types and traffic) fall into this category. It is also expected that most game developer designed messages will inherit from this class. In addition to the VuMessage data, it also includes entity position and update time data – allowing early culling of events on entities which are not near the player associated with the receiving session.
• VuCreateEvent – This event is issued whenever an entity is locally generated and inserted into the local vuDatabase. This emphasis on locality is needed to ensure that insertion of an entity into the vuDatabase due to receipt of a VuCreateEvent does not itself generate a duplicate VuCreateEvent. Vu performs almost all of the processing needed to handle a VuCreateEvent, and after the event is dispatched the first time, the entity is guaranteed to reside in the local vuDatabase. The VuCreateEvent has enough data in the event itself to instantiate a new object. This data is stored in a data stream which is then passed into the object constructor.
• VuManageEvent – This event is slightly different than a VuCreateEvent in that it represents the creation of a temporary entity. Upon receipt, the associated entity can be added to local vuDatabase if it is close enough to matter. It is up to the game developer to make this determination.
• VuDeleteEvent – This event indicates that an entity has been removed from the vuDatabase of the managing entity. Remote receivers of this event will automatically remove this entity from all of its VuCollections as well. This is one of the few events which cannot be filtered out by the VuMessageQueue, as Vu must know when all queues have seen the delete event, even if no special processing is done.
• VuUnmanageEvent – This event is the analog of the VuManageEvent, with one small difference. When generated, the VuUnmanageEvent has associated with it a timer. When this timer fires, the controlling session will issue a VuDeleteEvent. Other sessions have until that time to issue a VuPullRequest to assume ownership of the entity and thus prevent its destruction.
• VuReleaseEvent – This event is used to locally remove entities from the vuDatabase and give internal threads a chance to perform cleanup. The only difference between this event and the VuDeleteEvent is that the delete event is sent out over the network, while the release event is local by definition. The release event, then is used to clean up entities that are not managed locally, but which are not needed or desired in the local vuDatabase.
• VuTransferEvent –This event is used to indicate that an entity is now managed by a different session than before. This transfer event can come from either the new or the old owner, but is most often generated as a response to a push or pull request, or as a result of a group or session redistribution (see the section on VuSession for more details on this).
• VuFullUpdateEvent – This event sends complete state for an entity over the network. This state is generated by calling the Save method of the entity, storing the entity state in a buffer, and creating a dummy copy of the entity on the receiving side for extraction of the new data. This update inherits from the VuCreateEvent because it has exactly the same data and construct. In fact if the entity does not exist on the receiving station, this full update event is ‘morphed’ into a VuCreateEvent (by changing it’s type field… nothing fancy).
• VuStateUpdateEvent – This update event contains new user state data of the VuEntity. The actual contents of this field are determined by the game programmer, but Vu provides the facilities to pass this data around.
• VuPositionUpdateEvent – This is most likely the most common message passed around the network. It indicates a change in position for the associated entity.
• VuDamageUpdateEvent – This event indicates new damage and hit point values for the associated VuEntity. These values relate to the default Vu fields for damage and hit points, but can be used as source data for other field updates.
• VuEntityCollisionEvent – This event indicates a collision was detected between two entities. This is one of the few events which relates to two entities. The primary entity, in this case, is the object which detected the collision, while the other entity is the object collided with. This event also includes damage data which can be used directly or as a seed to a subsequent VuDamageEvent.
• VuGroundCollisionEvent – Though Vu provides no ground collision detection (as there is no terrain system in Vu), this event does provide a standard means of communicating collision between an entity and the ground.
• VuSessionEvent – This event has many subtypes, and each of these events refers to a session or a group. Interpretation and handling of the event differs based on the event source and the event type. For example, this event is used to redistribute entities around the network (for load balancing or session crash recovery).
• VuTimerEvent – This is an internal event which fires after a given amount of time has passed. It is possible to associate another event with a timer event, causing a delayed invocation of that event. This mechanism is used with the VuUnmanageEvent, for example.
• User Extensions (other events) – It is quite possible for the game programmer to customize standard VuEvents with extensions, but two aspects much be handled with care: first, the event type field must be distinct from the standard vu types, and must not conflict with each other, and second, the programmer must ensure that the VuxCreateMessage function correctly create the proper message type. Also note that the VuEntity Handle function with the ‘best fit’ will be called by Vu, so if the user creates a subclass of the VuDamageUpdateEvent, then the VuDamageUpdateEvent handler will be called, not the generic VuEvent handler. This best fit is accomplished using a technique known as ‘double-dispatch’ to object oriented nuts. The magic happens in the Process method of the event. See the vuevent.cpp source file to see how this is done. This will be discussed in more detail in the VuEvent section later.
• User Events (VuEvent) – The other way to create custom events is to inherit directly from VuEvent. The main difference between user events and user extensions (above) is that almost all of the data for the user event is defined by the game programmer, and the generic VuEvent handler of the VuEntity will always be called.

Before closing out this discussion of the VuMessage, I should say a few words about routing. When a message is created, one of two fields must be specified: target session or routing. The routing is a bitfield with five settings:

1. VU_LOCAL_TARGET – should be handled by local session
1. VU_REMOTE_TARGET – should be handled by all remote sessions
1. VU_GROUP_TARGET – should be handled by all sessions in the same group as sender
1. VU_SPECIFIED_TARGET – should only be handled by target session (see below)
1. VU_BCGROUP_TARGET – sent to all sessions in a broadcast group (not implemented)

If the target session is set, it implies a routing of VU_SPECIFIED_TARGET, and vice versa. In most cases, events are routed using the VU_GROUP_TARGET routing only, and thus not handled by the source station (example: VuPositionUpdateEvent, as the position data is already by definition set and correct). Some Vu events use the VU_LOCAL_TARGET only (VuTimerEvent and VuReleaseEvent). This is how non-network events are implemented. The VuDeleteEvent are handled both by the sending and all destination stations, thus ensuring cleanup of the entity on all contexts on all machines. Since the route setting is a bitfield, multiple flags can be set. Thus an single event can be sent to the local machine, all machines in the local group, and a specified target.

Where a message is sent to a specified target, Vu will use a reliable messaging protocol, if one is available. For messages sent to multiple targets (group and remote), an unreliable broadcast protocol will be used (if available). The VU_BCGROUP_TARGET will use a multi-cast protocol to send the message to multiple stations, but the exact mechanism for specifying this is not yet defined. For now, setting the routing to VU_BCGROUP_TARGET acts the same as specifying VU_GROUP_TARGET.

The VuMessageQueue component is responsible for maintaining each of the message queues used by the system. Each instance of the VuMessageQueue is responsible for maintaining the dispatching of the messages from that queue, while any event posted to any queue is inserted into each of these instances. This way, each write goes into each queue, while all reads are handled by each queue at their own leisure. In most cases, an instance of a VuMessageQueue will be associated with each VuThread, and hence each actual software thread in the program. All VuMessageQueues, including the one associated with the VuMainThread, may specify a VuMessageFilter which can filter out messages by any criterion available. Note that the VuDeleteEvent and VuRemoveEvent cannot be filtered out, as Vu needs these to be posted and handled in order to guarantee safe cleanup of entities (though the game programmer does not have to do any special processing of these events).

A quick note about message handling: Except for messages which pass none of the message filters in any of the message queues, VuMessages are Activated on Post, and Handled on the first Dispatch call. Subsequent Dispatch calls have no effect. This is done because this would execute the same code multiple times, as each entity by default has no notion of which thread it is associated with when run, and in fact may be handled by multiple threads. Note also that the VuMessageQueue will modify the routing field of the VuEvent as a normal part of its processing of the message, so this field should not be checked or modified after creation.

The VuMessageQueue class tree is shown in Figure 8:

The classes in this sub-component are enumerated below:

• VuMessageQueue – This is the class which implements the message queue. It is not anticipated that game developers will need to create subclasses of this as all needed customization can be accomplished by some combination of VuMessageFilters and VuThread subclasses.
• VuMessageFilter – This class is a pure abstract interface class. It defines the interface used by the VuMessageQueue to determine whether or not a given message is posted to that queue.
• VuNullMessageFilter – This filter blocks all messages (except for VuDeleteEvent and VuRemoveEvent). This is useful for queues where no special event processing is performed.
• VuMessageTypeFilter – This filter blocks all messages which do not pass the built-in message type mask. This mask is built by taking each allowed event type, shifting a bit into the mask by that number of the event type (e.g. the VuDeleteEvent, has a message type of 7, which results in a bitmask value of 1<<7, or 128). Each event type requested is added to the mask by way of a bitwise OR operation, and the resultant mask is stored in an unsigned long integer value, and then tested via a bitwise AND operation with the shifted bitmask value of each tested event. Those which pass the test are added to the message queue, those which do not are not.
• VuStandardMsgFilter – This filter is my best attempt at creating a filter which fulfills the actual requirements of simple Vu applications. This is probably not true, however, as it for the most part ignores user events. For more information on this, read the section on the VuMessage, or see the comments in the vuevent.h header file.
• User Filters (VuMessageFilter) – Users can (and probably will) create their own filters on messages by subclassing from VuMessageFilter. These filters can use any means available to filter out unwanted messages. If a message is not of interest to a thread, then it is better to filter out the message on insert rather than to post and dispatch it in the default manner. Note that if an event is not posted to any queue, its handler is still called, but it is called on post, rather than on first dispatch as is usually the case.

This concludes the brief overview of the Vu architecture. Further discussion of the use and implementation of these components can be found in the sections which follow.

The VuEntity class is the base class for all game objects (entities) handled by the Vu system. In Vu, the base class has a superset of the needed data by most of the game objects ultimately used by most games. While this approach means that there will necessarily be some data which is not important to some entities or some games, it does simplify the handling of the objects quite a bit. The alternative would be a relatively deep object hierarchy for just the Vu portion of the class tree. By keeping location and orientation data for all entities regardless or whether that data is applicable to the object, we ensure that worst case mishandling of entities is to view and modify meaningless data (rather than scribbling over real data with meaningless values).

As this is the first section to examine one of the Vu class definitions, this is as good a time as any to discuss class construction conventions used throughout the Vu system:

Class member organization -- Classes are always laid out using the following template:

So the class interface is broken into three blocks: friend declaration, function interface, then data. Within each section, data is organized from most public to most private in order to present the interface of use first, so that it can more easily be located by users of the class. Data is kept together for two reasons: first, it makes the class look more like a C structure (which is what a class actually is, despite what C++ OOP fanatics tell you), and second, keeping the data together makes the class definition more closely resemble the memory footprint of the object as viewed in a debugger.

Below is the VuEntity class definition, along with annotation for each of the interface functions:

Creating a VuEntity subclass is relatively simple, but there are a few steps which are required. These will be covered in detail in this section, where we will create a sample class, the SampleBuildingEntity class, which represents a building object in our sample game..

For our sample entity class, we will create two entity types, the SAMPLE_TENT_ENTITY_TYPE and the SAMPLE_FACTORY_ENTITY_TYPE. These two entity types differ only by size, but everything else is the same. We start our counting at +2 to account for the VU_SAMPLE_ENTITY_TYPE presented earlier.

The EntityType table is populated with reasonably appropriate data for our two entity types. Note that the data differs only in the class id, collision radius, class info, and hitpoints. The class info is a relatively arbitrary field which can be used to classify entities. Values put in here are rather arbitrary and in fact are not used by default by Vu. They could be used by the game developer to classify an unfamiliar entity as being similar to a known type, so that a new type of F-16 for instance, could at least be rendered as an F-16 of a known type.

Next, we must supply an implementaiton of the VuxType function. Note that as entity types are added, this function will need to be updated.

Our building class is rather simple. In this case we will only add an address and a color (we will assume an enumerated value, but will just store it as an int). In order to make this work, we need to define three constructors (one which takes source data, and one for each of the data stream constructors). We will also need to overload the three save functions so that we can add our local data to the datastream when we store to a file or send to the network. Note that the simple accessors are inlined. The more complex SetAddress function (which performs cleanup and allocation) is not inlined.

Since this is a simple class, our implementation is relatively short. Annotation of the implementation will be given where appropriate.

The VuxCreateEntity function must be defined by the game developer and must translate a type and data stream pointer to an allocated, fully populated entity. The implementation is relatively simple, but any time a new type is added, this function must be updated.

The VuCollection class tree and its associated helper classes (VuIterator and VuFilter) provide storage, sorting, and retrieval functionality for VuEntities. The VuCollection system also contains the VuDatabase class, which is the repository for all active VuEntities in a game. In addition, the VuDatabase (and other components of the VuCollection system) perform enough memory management to ensure that entities can be safely deleted. This is performed by minimal use of explicit memory locks (reference counts), relying instead on an implicit reference system.

As is true with most of the Vu class trees, the VuCollection hierarchy is relatively flat. The deepest tree is the linked list tree, where each subclass adds a small amount of functionality (filtering and ordering). This

section will only cover those classes that provide significant new interfaces. Subclass examples covered will include only the VuFilter, as that is the developer configurable component of VuCollection system. Note that it is possible to implement custom collections or iterators as well. Custom collections are needed for special purposes, such as creating a collection whose membership is determined by developer code rather than by a Filter (target lists, for example). This will be covered in the FAQ section later in the document.

Below is the definition of VuCollection, VuDatabase, and VuRedBlackTree. Although there are many more classes in the VuCollection hierarchy, these three classes almost all of the interface functions provided by this class tree. Annotation of these classes will only discuss newly added functions.

The VuDatabase class is derived from VuHashTable (not shown here). It takes some custom constructor values (such as tableSize and key) which it passes on to the hash table. It also adds a Save and Restore API.

The VuGridTree is a special purpose collection created to maintain and return proximity sets. It consists of an array of VuRedBlackTrees, where one dimension (X by default) determines the array entry, and another dimension (Y by default) is used to sort elements in the VuRedBlackTree within that X row. More magic happens inside the VuGridIterator (covered below), but this interface provides the all important Move function.

Below is the definition of the VuIterator class and its significant subclasses (those which add new interface functions).

The VuListIterator is given here as a sample implementation of an iterator – one which also defines the rest of the VuIterator component interface.

The VuRBIterator (which iterates on a VuRedBlackTree) is presented here because of the VU_KEY version of the GetFirst function, and because of the RemoveCurrent interface function.

The VuGridIterator is presented here because it has a fairly unique constructor (in order to set the initial context) and it specializes the VuRBIterator in interesting ways. In addition, it uses function hiding (instead of overloading) which some compilers will flag with a warning.

Below is the definition of the VuFilter, VuKeyFilter, and VuBiKeyFilter classes. All of these are abstract classes which require subclassing to be functional.

The VuKeyFilter is similar to the VuFilter, except that it has an interface function to extract and return a VU_KEY value from an entity. This is most useful for using non-Id sort keys for the VuRedBlackTree.

The VuBiKeyFilter adds a few functions to the VuKeyFilter from which it is derived. It was designed to translate an entity’s position into two key values for storing in a VuGridTree.

Creating a new VuFilter class is rather simple, but a few things are required. Most importantly, all pure virtual functions of the VuFilter class must be defined. For our sample filter, we will say that we need a filter which will give us all of those VuEntities which we defined (filtering out the Vu defined entities, such as VuGroupEntity and VuSessionEntity), and which are managed by the local machine.

Our SampleFilter class just defines our class. Note that we don’t have any data in this class. The virtual function implementation determine our behavior (especially the Test function). Since we add no new functions or data in this class, we’ll save annotation for the implementation (Step 2).

The implementation is somewhat interesting in that there isn’t much code here. The constructors and destructors don’t do anything. Only Test and RemoveTest have interesting code, and this is what creates our required differentiation.

And that’s it! Now, any instance of this class can be used in a collection or iterator. Note that collections take care of calling the Copy function, so the user of the collection need not do so (in fact, doing so will likely result in a memory leak).

The VuMessage class tree is the most extensive tree in the game, in part because of the simplicity of the design. Basically, each type of message has its own class (in addition to some common abstract classes). This is also one of the class trees most likely to be extended by the game developer, as it is likely that not all transmission needs will be satisfied by the standard Vu messages. Note however, that the VuFullUpdateEvent should cover many specialized needs. For this reason, our sample message subclass implementation will be somewhat contrived.

To reiterate the general design found in the architecture section of this document: Messages fall into three main categories. There is one error message class, three request messages, and the rest are entity state change events. Note that the base class in the tree is called VuMessage, but that the header file is called vuevent.h. This is true for historical reasons only. Hopefully this will not cause too much confusion.

The first batch of #defines define the message types. These are selected so that the type of a message can be converted to a bit field flag by shifting a 1 into an unsigned long by the type and then tested against a bitfield with a bitwise and operation. The maximum reserved Vu event type is 19, which leaves 12 user defined event types in the standard unsigned long. For more event types, this requires secondary or tertiary bitfields for testing. The vuevent header file also defines several predefined bitfield combinations for convenience.

Vu defines several bitfields which represent masks for combinations of events.

Below are the pre-defined Vu error codes. Also defined is the last error type reserved for definition by Vu. Game developers assigning error codes should ensure that their codes are larger than the VU_LAST_ERROR.

Vu also defines timer types. Again, user timers should have a types larger than the VU_LAST_TIMER value.

Routing is used to determine where to send a message. VU_LOCAL_TARGET is sent to the local machine (only), while VU_REMOTE_TARGET is sent to all remote machines. This is a bitfield, so combinations of these can be set simultaneously. In general, the specifics of this is maintained by Vu rather than the developer.

Finally, session event subtypes are also defined in the header file. Just to be a little inconsistent, these are set as an enumerated value rather than by way of #defines.

For the most part, the specifics of these values need not be known (except for the namespace issue), but these values appear frequently in the VuMessage source code, and hence they appear in this document.

The VuMessageQueue is covered first because it is the repository for unprocessed events in the Vu system. In general, it is not expected that the developer will be subclassing from VuMessageQueue. All needed customization can be performed by creating custom VuMessageFilters (see below) and VuThread. Steps required to perform customization of a queue will be covered in the section on VuThreads.

The VuMessageFilter class is used to prevent certain messages from being posted to a particular VuMessageQueue. This is similar to the VuFilter in design and use, except that it operates on messages instead of entities.

The VuNullMessageFilter passes all messages. No messages are filtered out, and all passed in are posted to the queue. This is the filter type which is used by VuMessageQueue if a 0 is passed in as the filter pointer (the default).

The VuMessageTypeFilter takes a bitfield in the constructor which can be tested against the message type to determine whether or not the message should be posted to the queue. Note that the bitfield passed in should include the delete messages if the associated thread/queue uses entities, collections, or iterators.

The VuMessage class tree contains many classes. This discussion will enumerate all classes, and annotate special features or functions.

The VuRequestMessage does not have too much associated with it. It just passes the interface on to the subclasses.

The VuGetRequest message is used to request data from a remote session. The message can either be targeted at a specific entity, in which case that entity returns it’s data, or at a set of stations, in which case each receiver returns its data. If the message is created with a VU_NULL_MESSAGE_ID, then the request should be interpreted as a request for ALL entities managed by that session. With these tools, a request message can ask for anywhere from one entity from a specific session to all entities from all sessions. Error messages will only be generated if the get message is targeted at a specific session which does not manage the requested entity.

VuPushRequest must be targeted at a specific session. This session should be the session which should begin managing the entity. An error message will be returned if the entity cannot be transferred for some reason (such as the target session is unable to manage the entity). Success will be indicated by way of a VuEntityTransfer event generated by the target session.

VuPullRequest is similar to VuPushRequest, except that it is targeted at the session which currently managed the entity and is a request for that manager to relinquish control of the entity to the requestor. Again, the response will be one of VuErrorMessage or VuTransferEvent.

VuEvent is the abstract class for all entity state change events. It contains a few fields which are set on activate. These fields include the position information (x, y, z) as well as the update time. These fields can be used to filter out messages which are too distant from the position of the player to be of interest.

The VuCreateEvent is used to announce the creation of a new entity to other sessions in a group (and possibly to other threads in a program, but this is unusual). The Create event works by writing all of the entity’s data into a buffer using that entity’s Save function (stream version). This stream is then sent over the wire and used as source data for the stream version of the entity’s constructor.

The VuManageEvent is very similar to a VuCreateEvent (it contains the same create data). In fact, it only differs by context. A manage event is used to create an entity which already existed logically, but just was not managed by anyone. This goes with the VuUnmanageEvent which is used to indicate that the entity is again not managed by any session, but is not actually gone.

The VuDeleteEvent is sent by the manager of an entity when that entity is removed from the managing session’s database. The delete event is a critical part of Vu’s memory management scheme, as the destructor of the delete event is where the entity is deleted (well, actually, where Vu performs its last dereference). As the delete event is not destroyed until after all queues (and hence threads) have processed the message, this ensures that all threads have (1) seen the delete event (in order to purge global pointer references) and (2) returned to the top of their call stack (to the inner event loop), which ensures that there are no references to the entity pointer on the stack. Other than these two nifty characteristics, the delete event is really nothing special.

The VuUnmanageEvent is used to indicate that an entity will soon be going away. The entity will be destroyed at the time indicated by the mark in the constructor (at which time a VuDeleteEvent will be called). Any session which wishes to keep this entity active needs to request ownership with a VuPullRequest. If this pull succeeds, then the entity will be Released instead of Deleted by the former owner, and the new session will assume ownership.

The VuReleaseEvent is one of two internal (non-net) messages provided by Vu. This message indicates that an entity which is not managed by the local session has been removed from the local database. This allows cleanup of the entity in the same fashion as is provided by the VuDeleteEvent.

The VuTransferEvent is used to indicate that the specified entity is now managed by a different session. Functions and data are pretty standard.

The VuStateUpdateEvent is used to indicate that the user state of the associated entity has changed. The vu state is also included in this event though it is not currently used.

The VuPositionUpdateEvent is probably in practice the most frequently sent message in the Vu system. It indicates that an entity’s location has changed. Note that the VuDriver class structure provides facilities for minimizing this kind of traffic by providing dead reckoning and smoothing functionality. For more information on this, see the VuDriver section. Note that this event contains position delta, orientation, and orientation delta information. Position information is also present, but is specified in the parent (VuEvent) class.

The VuFullUpdateEvent is kind of a tricky implementation. It inherits from VuCreateEvent for two reasons: (1) the data is complete, and is written using the entity’s Save function (stream version), same as VuCreateEvent; and (2) when an entity receives a full update event on an entity it has not heard about (and needs to add to its local database), Vu ‘morphs’ its type to a VuCreateEvent by changing the eventType_ field. This allows Vu to pretend it received a create event (and to create the entity from the event data) without making an explicit request to the owning session. This cuts down on network traffic and also provides a rather seamless way to handle missed packets.

The VuDamageUpdateEvent is the standard Vu damage state update. It includes data fields for shooter id (for kill recording or scoring) as well as the standard Vu damage fields. The values passed in are intended to reflect damage inflicted, not health remaining.

The VuEntityCollisionEvent is the Vu provided event for communicating that two entity’s have collided. The primary entity is the entity which detected the collision, while the other entity (specified by an id) is the entity collided with. This event can also be used to specify hit location and hit effect.

The VuGroundCollisionEvent is defined by Vu for completeness. As Vu does not perform ground collision, this event will never be generated by Vu.

The VuSessionEvent is a generic event type for various events pertaining to sessions and groups. Session events have a subtype which indicates the nature of the session message. This subtype is enumerated in the #defines section above. All session event subtypes defined are generated and handled automatically by Vu.

The VuTimerEvent is a special internal event which is dispatched the first time DispatchVuMessage is called on the holding queue after the time specified by the mark passed in has been reached or passed. The stored time is compared with vuxCurrentTime to make this determination. Note that this is the only time when Peek and Dispatch could conceivably return different events (wrap the Peek-Dispatch pair with a critical section if this is a problem). It is also possible to automatically post a secondary event when the timer is first dispatched. This event is passed into the timer event constructor. Note that this event is never sent over the network.

In this section, we will only cover the creation of a subclass of VuMessage. Subclasses of VuMessageFilter will be covered in the section on VuThread.

For our sample message, we will create a class called the SampleChatMessage, which is used to send a text message to one or more sessions in a network environment.

This step is relatively simple. We need to create a message type which does not conflict with the Vu message types. This can be done as illustrated below.

Our new message class inherits directly from VuMessage (as it does not fall into any of the other three pre-defined Vu message types). The local constructors take a message text and a target. By specifying the target or the routing, the message can be sent to one player (session) or the entire group.

Our implementation of this class is not all that long, but does fill out a bit because of the three constructors and the complexity of the transmission functions.

Our final step is to implement or update the VuxCreateMessage function, which translates a message type into a newly allocated pointer to a message of the appropriate type. If we don’t know the message type, the proper behavior is to return 0, which is exactly what is done here. Vu will automatically handle population of the message with a subsequent call to Decode with the event data.

This ends our coverage of the VuMessage use and customization.

The VuDriver is an ancillary part of the VuEntity object. It is a separate class whose instances are contained in the VuEntity class. According to the design, it does not make any sense to have a VuDriver without an associated VuEntity. However, this separation does make it much easier to change the behavior of an entity (for example, changing an object’s motion modelling from flying to falling), and it also provides Vu with a way to seamlessly provide dead reckoning and smoothing functionality for network updates in such a way that the game code does not need to adjust to the different conditions (beyond initializing them properly).

This section will cover the various classes in the VuDriver class tree, and then present a sample master sublcass implementation for our SAMPLE_TENT_ENTITY class (defined in the VuEntity section, above).

The VuSlaveSmootherSettings class is the repository for certain global thresholds and smoothing values. Vu makes use of a defined global variable, vuxSlaveSmootherSettings, which must be set and initialized by the game developer. The class itself is described below:

The VuDriver class tree has a few classes, but most of the functions (and hence the interface) is given in the VuDriver class. Subclasses introduce a few additional functions which will be explained when presented. These are most often functions used by the driver hierarchy, either internally or by subclasses.

The VuDeadReckon class contains all dead reckoning code. This is the parent for both the master and the slave because the slave moves by dead reckoning, while the master needs dead reckoning in order to determine whether or not the actual position and the position the slave drivers are using are far enough off to justify generation of a position update.

The VuMaster class is also a pure vitual class, but it defines most of the functionality required by a master driver. The ExecModel is newly introduced and is virtual. Subclasses must define this. In addition, the event handlers by default are stubbed out to do nothing. If any special action is required, the subclasses should overload these.

The VuSlave class uses dead reckoning for basic motion updates, and also implements a smoothing algorithm to correct error without warping. The smoothing parameters are stored in the vuxSlaveSmootherSettings class instance and (unlike the master tolerance values) are not configurable per driver.

In order for the whole driver construct to be useful, motion modeling must per performed in a game developer implemented subclass of VuMaster. Here we will present the specification and implementation of just such a driver. Our sample driver will work with the SAMPLE_TENT_ENTITY first presented in the VuEntity section. For our purposes, we’ll say that tents are buildings that move around from time to time. We’ll also say that when an tent moves, it moves by warping (we won’t change the delta values). Note that, depending on our vuxSlaveSmootherSettings, the tents will appear to move more smoothy on remote machines. As this is a toy example we won’t worry about that. We’ll also simplify our motion by just moving a constant offset every warp, and we’ll warp every hour.

Our tent driver class inherits from VuMaster and defines the AutoExec and ExecModel functions. We also keep track of when our next move should occur in the nextMove_ variable.

The implementation is also fairly simple. Real drivers will likely be more complicated than this as real drivers have to worry about modeling things in such a way that the move realistically or in a fun way or whatever.

Pretty simple. A slightly more complicated example can be found in the Zoomers application, but that’s yet another toy example.

In this bit of code we will assume that the transfer event handle function was defined in the SampleBuildingEntity header file given in the VuEntity section. Here we implement it and ensure that when management of the entity changes to or from the local session, the driver is updated properly.

For this step, we will modify the VuxCreateEntity function given in the VuEntity section.

This step will be taken out of context a bit, but note that drivers must be set whenever local entities are created, and must be freed whenever the drivers are changed (as a result of a transfer event, for example). We will make a dummy function which creates a new tent entity with the values passed in, creates and adds a driver entity.

The VuThread class is a Vu representation of a thread of control in a game. The VuThread object itself does not in any way implement or activate OS threads. These thread objects do not even need to be associated with an actual OS thread, though they were designed to work with them. The heart of the VuThread class is the Update function, which allows Vu to perform cleanup for that control context at that time. This function call should be made from within the inner loop of the thread, and should be called often (once per loop is sufficient).

There is also a special subclass of the VuThread object called the VuMainThread. There should only be one of these objects active in a given game, and calling Update on this thread will perform several special operations if the appropriate flags are set:

• VU_USE_COMMS – If defined, the Update function flushes external events.
• VU_AUTO_UPDATE – If defined, Update sends out periodic VuFullUpdateEvents on managed ents.
• VU_COLLISION_CHECK – If defined, DoCollisionCheck performs collision checks between all of the entities which have their collidable flag set.

The include file which defines the VuThread class is (perhaps inappropriately) called vu.h. This header file also has global variable declarations and some other miscellaneous pieces. This section will only discuss the VuThread classes and interface functions. The other pieces have either been discussed elsewhere or are obvious.

The VuMainThread class is special in that every program should create one and only one of these after general Vu initialization but before any use of the non-initialization Vu interface. The constructor of the VuMainThread creates several vu global variables, including the vuDatabase.

In the Getting Started section, we covered creation and use of the VuMainThread in a single player environment. Here, we will cover the basic steps needed to hook Vu up to a network and interact with other sessions in a multi-player environment. Since all of the code in this case is concentrated in the initialization routines, this "how-to" section will not be broken into steps.

Later, to join an active group (which presumably has an active or planned network game) simply call JoinGroup on the desired group.

In a single-threaded environment, it is possible to customize handling of messages by writing custom VuEntity derived Handle functions and creating custom message classes. Whenever multiple threads are active, it is possible to define which messages are processed by which threads by use of the VuMessageFilter, but in many multi-threaded environments, some extra steps may be required if each thread wishes to handle the same event differently. This is the purpose of the VuThread subclass. For our example, we will create a class called the SampleThread which will just watch for a particular type of message and print out a notice of the receipt of this event. This is just a toy example, but it does illustrate the techniques needed for more serious applications.

Our SampleThread class definition is very simple. It requires no data and we need to overload only the constructor, destructor, and Update functions.

Implementation of our SampleThread is also somewhat trivial. For more sophisiticated needs, the Update function will have more logic.

And that’s it!

The VuSession sub-component is comprised of the VuSessionEntity, VuGroupEntity, VuPlayerPoolGroup and the VuSessionsIterator classes. Other than the iterator, all of the classes inherit from VuEntity, and these are used by the Vu system to track sessions (which represent players and their machines in a network environment) and groups (which represent collections of sessions, which can either be games or holding areas of gamers, such as chat rooms). In this chapter we will discuss the interface functions introduced by the classes of this sub-component.

Below is the VuSessionEntity class definition, along with annotation of new (or modified) functions.

Below is the VuGroupEntity class definition.

The VuPlayerPoolGroup is a specialization of the VuGroupEntity. Like the VuMainThread, each active game executable will create one and only one of them, except that Vu takes care of creating the VuPlayerPoolGroup. This entity is special in that it is local and is not owned by any entity. This works by ensuring that Vu creates the default group in the same way when initializing Vu. The VuPlayerPoolGroup represents the pool of players not currently assigned to any particular game, and it can be used as a chat room, if desired. If the local session joins the default group, it is the VuPlayerPoolGroup that will be joined.

The VuSessionsIterator class is used to iterate over all of the sessions in a group. It is very similar to the other iterators, except that it takes a group in the constructor (to identify the group whose sessions are desired) and the GetFirst/GetNext functions return VuSessionEntity pointers instead of generic VuEntity pointers.

This section will not cover the steps required to make a new subclass, as Vu already provides a good sample implemenation in the VuPlayerPoolGroup class. The game developer must define a new class and implement it. The most important function is the Distribute function – without which there is little reason for creation of a new subclass. The other functions are straightforward.

This chapter will present many of the questions that were asked by early developers using the Vu2 system that require techniques which are not covered in the earlier chapters of this document. The answers provided will include steps and sample source where appropriate. Note that it is quite possible that some techniques which may be applied to the Vu2 system will not be answered here, but that does not necessarily mean that the technique in question is not a valid one. One general caution: As with any library, misuse can result in unpredictable (and often catestrophic) behavior.

This was covered in the chapter on VuThread, but is fundamental enough to be repeated here. The bit of code is really quite simple, and is given below:

As with all messages, posting it to the static message queue ensures that it will be processed and cleaned up. By specifying the vuNullId, the program is requesting all entities, and by using the default routing for the VuGetRequest, we are requesting all entities from all sessions in the local group. This operation should be performed shortly after joining a group.

Note that it is possible for sessions to acquire the entire database from the network without a request message by simply listening to the perioding full updates if the VU_AUTO_UPDATE flag is set. In this case, the database will be current once the longest update cycle has been closed. Unfortunately, there is not an easy way to tell what this time is, though there is a way to tell when we’ve sent all the entities as a response to a get request (see question 2).

By default, Vu does not provide an end of transmission message or any other way to determine when we’ve finished sending all of our messages. The philosophy behind this as a default behavior is that we are working in a fluid system. While a response to a get request will send all currently managed data, it is always possible to dynamically create another, and programs need to handle this case anyway. Also, dynamic handling of response messages allows immediate return from the get request message without a special state where we’ve requested network data but haven’t received any yet.

That said, some systems work better when they have a more complete image of the network database to work from. There is a little extra work required to make this happen, and a sample implementation of this is provided below. One important note to make here is that this system depends on reliable and ordered transmission of response data. Whether this is true or not depends on the implementation of the transport layer.

Here we define two new messages which will allow us to send and process confirmed request messages. We start our namespace addition at 2 to account for the chat message defined in an earlier chapter.

Our implementation will make use of three globals:

waitingOnSessionCount keeps track of the number of sessions which have yet to send all of their data, the doneLoading flag reports when we’re clear to leave the waiting for data state, and the currentConfirmedGet is just a variable to ensure that we don’t cross ourselves with multiple simultaneous confirmed get requests, or by other random SampleEOTMessages which we process for whatever reason.

In order to make this work correctly, we need to define two new classes. The first is the SampleEOTMessage, which is used to mark the end of transmission of the response to a get message. We keep track of the source message id so that the receiver can connect the response to the earlier request (this code resides in the Process method of the SampleEOTMessage class).

The other new class is the SampleConfirmedGetRequest. We create this class primarily to allow the target station(s) to correctly respond to the reqeust by sending their managed entities plus a SampleEOTMessage at the end. This is performed in the Process function. Note that this class has no data. All behavior is encapsulated in the implementation.

Although we have presented sample message subclass implementations earlier in this document earlier, there are a few new twists that are used here. They will be discussed where presented.

The SampleConfirmedGetRequest message is a special version of the get request message. It will specify that all sessions in the current group return all of their managed entities. In addition, this request is processed on the receiving station (see the Process implementation below) and generates a SampleEOTMessage at the end.

Finally, we use our new classes and globals in two places. The first of these is in our join group code. After we successfully join a group, we send out our new SampleConfirmedGetRequest and initialize all of our globals. Other globals (such as the new program state) should be set up here. Note that the confirmedReceipts is set to count - 1 instead of count. This is done because we will not receive an update from ourselves, and we are counted in the SessionCount.

The other place we need to put new code is in the main loop or sub-loop where we check the status of the doneLoading flag to determine if we can transition from our waiting state to our normal state. The details of this transition are program specific, so only a sketch is provided here.

Generally speaking, there are two main methods for saving entities to a file. The first is to iterate across the database, storing the entity type and invoking the Save function for each. Restoring in this case is accomplished by performing the reverse operation: reading the type, and then for each stored entity, create an entity of the appropriate type with the file pointer. In this case, the game developer is responsible for demarking the entities (or terminating the file) and affixing any special header information.

The other method for storing and retrieving the database is to use the Save and Restore functions of the vuDatabase. This is arguably a simpler interface since it is a bit more formalized, but the same steps are required. In addition, the vuDatabase save and restore functions automatically demarkate entity records and also mark the end of file. To use the vuDatabase interface, perform the following steps:

The callback functions are relatively simple. There are read and write callbacks for the database header (written and restored before any entities are saved), and read and write callbacks for each entity, which allows entity header and footer data to be written. Our sample code will utilize printf to tell us where we are doing stuff.

At this point it is worth repeating the warning about multiple instances of the same entity in the database. Vu does not prevent the developer from inserting multiple copies of the same entity into the database more than once, but if this does occur then Vu will exhibit unpredictable and perhaps fatal behavior. Prior to restoring, it is advisable to remove all entities from the local database (except for sessions and groups).

Some of the early developers wanted a way to have private lists (or other collections) whose membership was detemined by logic in the code instead of the provided filter interface. A good example of the need for someting like this is a target list. The most obvious solution would be unregistered lists, but the disadvantage of these is that unregistered collections will not be able to take advantage of any of the thread safety or memory management features of the Vu system. The solution is to custom subclass of the desired collection type with a few modifications. Our sample collection, which we’ll call the SampleTargetList, will be a linked list with specialized insert functions.

The SampleTargetList is a very simple class. The only thing we are adding is an overload of the virtual Insert function, and a new ForcedInsert function to replace it. The class has no data (and needs none).

When Vu uses the interface, it will use the standard Insert function call, which will never insert an entity into the database. The line of code below assumes myTargetList is a pointer to a SampleTargetList, and that myEntity is a pointer to a VuEntity (or subclass). The lines below illustrate insertion and removal from our newly defined list.

Note that iteration across this list can use the standard VuListIterator.

Entity transfer can happen as a result of several built-in mechanisms. The first of these are the VuPushRequest and VuPullRequest messages. VuPushRequest is used to ask a remote session to assume management of a local entity, which VuPullRequest is to ask a remote session to grant management of the referenced entity to the requesting session. In either case, the receiver of the message has the responsibility of changing the ownerId (and generating the corresponding VuEntityTransferEvent), though the VuEntity::Handle functions for VuPushRequest and VuPullRequest perform this function automatically. If the entity cannot be transferred for whatever reason, then the receiver of the request has the responsibility to send an error response. Again, the default VuEntity::Handle implementations ensure that this can happen. Note also that the game developer can overload these handlers to place new restrictions on transfers, but the same rules should be followed.

The other way to tranfer entities is through the VuGroupEntity::Distrubute function call. This call will either re-distribute all of the entities from a single station to others in the same group, or it will redistribute all of the entities in the group to new stations. The first case is used for disaster recovery where a given station has unexpectedly left the game (dropped connection or crashed) while the second case is used for load balancing. In these cases, the default implementation does not use the VuPushRequest or VuPullRequest interface. Instead, each entity which assumes ownership sets the ownerId to the local sesion id, and sends out the VuEntityTransferEvent to inform other stations of the change. Since all stations should be using the same re-distribution algorithm, there should be no contention for this re-distribution, and minimal message traffic. For more details on load balancing, see question 7.

Sometimes it is advantageous to ensure that entities are managed by the same session. This is useful where accurate tracking is required (for example: a fast moving missile and its fast-moving target), or where some of the data required by an entity is only kept on the master station of an associated entity, or in the case where entity aggregation and deaggregation is performed.

Vu provides a SetAssociation interface to the VuEntity which allows the game developer to associate one entity with another. This ensures the following:

• entities will not be transferred if their associated entity is managed locally
• in a VuGroupEntity::Distribute call, all entities with associations will use their associated entity to determine the target station. This should ensure that both entities relocate to the same session.

Altough this is useful, the association does not automatically ensure the following:

• If an entity which has entities associated with it (but which has no association itself), those ‘child’ entities will not automatically be transferred when the ‘parent’ is transferred.
• If a ‘parent’ entity itself has an association, then it may end up managed by a different session than its children after a Distribute function call.

These two characteristics mean that it is up to the game developer to transfer associated groups of entities in the correct order: ‘parent’ first, followed by ‘children’. Also, ‘parents’ should never have any association. In these cases, all entities should associate with what would be the parent of the parent. This is the only way to ensure corrent behavior. Also, under no circumstances should entities associate with each other. This will just prevent any transfer and will probably ensure that the two entities end up managed by different sessions after a Distribution.

The default load balancing system distributes the entities more or less equally among all of the sessions in the current group. While this may work for most systems, it will not work well for systems which use a client-server model (where most or all of the entities are managed on a dedicated server) or a network of systems with widely varying connectivity or CPU capacity. In these cases, it might be nice to give a larger share of the entities to the machines with a higher capacity. To do this, modify the LoadFactor of the high capacity session is higher than those of lower capacity sessions. There are two important things to remember when setting these values:

• Lower numbers are better than higher numbers. High numbers increase the likelyhood of ‘clumping’ of entities together, and with it, poorer distribution.
• The mathematical relationship between two LoadFactors is directly proportional to the number of entities those sessions will receive after a global distribution. For example, if session A has a LoadFactor of 1 and session B has a LoadFactor of 3, session A will end up with about 25% of the entities, and session B will end up with 75% (or 3 times that of session A).

Note that by default, Vu assigns a LoadFactor of 1 to all sessions. Note also that the Distribute call reassigns all entities, so adjusting the LoadFactor based on the number of entities managed will cause skewed results for future load balancing calls unless a custom load balancing method is used.

If it is determined that the load balancing algorithm provided by Vu is just fundamentally unsatisfactory for the game’s needs, the game developer can write his own load balancing algorithm. This is accomplished by doing the following:

For our purposes, we will define the class skeleton (including the #define for our new type) but not the new typetable entries or modifications to the VuxCreateEntity function call. These other steps are still requried, but have been covered elsewhere.

Our SampleGroup class is mostly skeletal, but is actually rather complete. Only the Distribute function is artificially stubbed out. The other functions would need to change if we stored networkable/storable data in this class, but that’s it.

Management domains are a way of allowing plug-compatible products to work together in a networked environment. Special allowance is needed to ensure that entities can be transferred only to other stations which are capable of managing them. For example, a flight simulator which models F-16 characteristics may be able to display Apache helicopters, but still be unable to accurately model their motion (and vice versa). Providing that both of these products use compatible versions of Vu, they can still play in common games as long as their management domains are properly set up.

The first step in ensuring compatability is to ensure that name space mapping does not overlap. The management domain bitmask namespace has 32 bits, which means that only 32 domains can be defined for a particular product line. The VuSessionEntity stores a 32 bit management domain bitmask (called domainMask_) which has one bit set for each domain which that session can manage. Each VuEntity has a VU_BYTE field (called managementDomain_) which identifies which bit in the domainMask must be set for a session to manage that entity. Note that the managementDomain_, as an 8-bit value, can identify 256 bit positions, but that Vu can only use the first 32. Setting a managmentDomain_ to a value higher than 32 will likely cause unexpected results. When assigning domains, remember that values extend from 0-31, and that Vu defines the value 0 to be a global namespace, which means that all products in the line must be capbable of managing entities so designated (Vu defined entities fall into this category). This leaves 31 bits for user defined domains, and the task of ensuring correct definition and use of these is left up to the game developer. The managementDomains for VuEntities should be defined in the VuEntityType table, as this value is copied to the entity structure on initialization.

Once domains have been defined and assigned to entities in the system, the game developer must ensure that all sessions have a correct domainMask which represents which domains they can manage. This must be set up by setting the external variable vuxLocalDomain. Vu will use this value to initialize the domainMask of the vuLocalSessionEntity.

Finally, the game developer must ensure that entities which are explicitly requested via a VuPullRequest can in fact be managed by the local session. Vu will take care of ensuring domain compliance in all other cases. Note that Vu does not provide any special facilities for ensuring that entities can be displayed by systems of another Domain, or even that they have a valid VuEntityType table entry. For evolving systems, the game developer might wish to implement the VuEntityType table as a file based component or even as a shareable entity (or collection) itself. This sort of implementation would allow dynamic creation and handling of new entity types, though display is another problem altogether.

Entity aggregation and deaggregation is the practice of grouping entities which are not near any players on the network into larger, more abstract groups so as to not load that network with updates to small units which nobody really cares about. Deaggregation is the act of breaking one of these abstract units into component units for display when a player moves near to one of these units, while aggregation is the act of removing the component units and reflecting this fact back in the parent unit. Ideally, if a player flew over a unit (causing deaggregation), destroyed a small component of that unit (say, a tank), then flew away (causing aggregation), if that player (or another) were to fly back over that unit, they should be able to see the unit in its reduced strength, and (better yet) see the destroyed tank.

One important note: Vu does not perform any of the above functions. The problems of which units to aggregate, how to fold in data that can be accurately deaggregated again is best solved by the game developer as a design consideration. Chances are good that generic solutions would be too general to be useful. Also, any generic solution provided here would be quite long and would also be too general to be useful. Vu does provide many facilities which make it possible to perform aggregation and deaggregation, and this section will discuss these facilities and ways they might be used.

These two events were created specificially to facilitate aggregation and deaggregation. A VuManageEvent is used to indicate that an entity (which was always there) is now being managed by some session on the network. A VuUnmanageEvent is used to indicate that an entity will soon not be managed by the current manager. If no entity assumes ownership of the entity by the time specified, then it will be deleted. The VuReleaseEvent is used to silently purge an entity from the local session’s database without requiring deletion from the owning session’s database. This is an important tool because it implies that all sessions on the net do not necessarily need to have the same database image at the same time. One important note to make here is that entities which are unmanaged (and deleted) and then subsequently re-managed will not necessarily have the same entity Ids. This can be accomplished, but requires some additional accounting and name space reservation.

As discussed in FAQ #6, entities can ensure that they are managed by the same session by associating a child session with the parent. It is quite possible that deaggregated entities will require specialized access to the parent instance, and entity association can guarantee functional access to this data.

The VuAntiDatabase works behind the scenes, but is an important component in environments where entities exist but are not instantiated in all sessions. At a minimum, Vu adds entities to the local anti-database which have the session’s Id in the creator field of the entity Id, but which are not resident in that session’s vuDatabase. This ensures that Vu will not attempt to create an entity whose Id is already in use, but just not instantiated locally (this is the only thing Vu uses the VuAntiDatabase for). It could also be used to preserve the id’s of de-aggregated entities which are not currently managed by anyone, but Vu does not currently do this, and the game developer would face a bit of work to take advantage of this.

While the VuGridTree is used for collision detection, it can also be used as a relatively fast proximity test. When deciding whether or not to deaggregate an entity, one could check each aggregate against each player periodically, or one could store aggregates in a VuGridTree, and then use the iterator (passing in each player entity) to find all of the aggregates within a given range of that player entity.

This chapter will briefly discuss each of the three applications distributed with the Vu system. It will discuss what they test, and what they accomplish. One of the applications, Netwatch, is actually an implementation of a packet sniffer which may be of some use to game developers using Vu and trying to debug network connectivity or communication problems.

The test directory contains enough code to implement the vutest.exe executable. This test program is a simple exerciser of basic non-networked Vu functionality including the vuDatabase, collections, entities, and database save and restore. It also tests ordered lists and the red-black tree. The latter is printed out in a nice format which indicates the depth of each node to verify that node balancing is done correctly.

The nettest directory contains the zoomers application. This tests most of the Vu functionality, including networking, the grid tree, collision detection, automatic updates, entity transfer and load balancing. Note that it is not possible to run more than one zoomers session concurrently on the same machine as they both attempt to grab the same socket.

The netwatch directory contains a simple passive network sniffer application. It uses the same network initialization code as nettest, so it is not possible to run netwatch concurrently with nettest on the same system. However, netwatch does not register with the network, so Vu and netwatch apps will not see each other. Netwatch can even be configured to scan packets from multiple games running on the same network. For a quick primer on the various configuration settings allowable for netwatch, execute the program with the ‘-?’ option.