Code documentation

Allegiance Code Documentation

Overview

The key components of Allegiance are:

• The client - Allegiance.exe
• the server - AllSrv.exe and the UI tool AllSrvUI.exe
• the lobby - AllLobby.exe

In a typical configuration, there are many servers and clients which connect to a single lobby. A server can host many games at once and a client can join only one server and one game at a time. The lobby is the central communication place where servers announce themselves (and the games they're hosting) and where clients can find, join or create games on a choosen server.

These keys components share many lines of code with the use of common libraries. The most notable ones are the messsaging API library which is built on Microsoft DirectPlay and the IGC library which handles the game logic.

Stub This article is incomplete This is an article about a topic that should be covered in more detail by the FreeAllegiance Wiki, but is lacking in content. You can help by improving it!

ZLib and Utility libraries

The ZLib library is a set of helper classes. It's used by all projects in the allegiance source. The most notable items of ZLib are:

• the ZString class which deal with strings.
• the TRef<T> template class which deal with object pointers and automatic garbage collection.
• some maths objects (vector, matrix,...)
• the Window class and win32 main entry point

The Utility library deals with more complex stuff than the ZLib library:

• the collision API which use Convex Hull
• the messaging API (network code) which is build on top of DirectPlay
• dynamic linked lists of pointers used widely in the several parts of the source.

IGC library

IGC stands for Internet Game Core. It's the game logic library (API) and it's shared between clients and servers.

IGC is accessed with of a set of hierarchical abstract classes (interfaces) that hold all the game objects (ships, stations, sectors,...) and their current properties (position, speed, ...).The top interface is ImissionIGC which represents a game. ImissionIGC is implemented in the CmissionIGC class (src\Igc\missionigc.cpp). It holds lists of all other objets (ships,stations,...) and provides methods for accessing them. These lists are all implemented with template classes (Slist_utl<> and Slink_utl<> which can be found in the Utility library).

The most notable method of ImissionIGC is the the 'Update' member method. It is called every ticks on the server and it's propagated in the various IGC object lists and update their states according to the game logic.

• 

  Class Diagram

When the game needs to create a new object, instead of instancing the object from scratch, the IGC library usually provides a 'template' for this object. The template holds several attributes that are used are initial values for the corresponding attributes of the new object. There can be many different templates for a given object type, the game must tell which template to use when creating an object. This how there can be different factions with different stations, ships and weapons. For example, the class representing active missiles is CmissileIGC, it uses the ImissileIGC interface and a new missile is initialized from a chosen CmissileTypeIGC (ImissileTypeIGC interface). Check the IGC classes diagram for the list of all IGC interfaces including the template ones.

All these templates are stored in static lists of IGC objects and since they are statics, they're not transmitted between the server and the clients but instead are stored into what we call a core file. So a server only tells a client the core file name the game uses and the client will load it from its local artwork folder instead of receiving it over the network.

Since both server and client share the IGC code, there is the need for them to react differently when a change occurs. For instance, when a ship is destroyed, the client will need to draw the ship explosion while the server will not need to do this but instead it will propagate that event to the other clients (are at least all the clients which need to know about that explosion). So both client and server are 'consumers' of the IGC library.

Consumers of the IGC library must implement the IsiteIGC interface in order to be called upon game state changes. The server implements it in the FedSrvSiteBase class and the client in the BaseClient class. We can view the IsiteIGC interface as a set of event callback functions. Understanding how this works is the main step of understanding the whole IGC library.

Tools

XMunge

XMunge is a build time tool aimed at manipulating DirectX .X files. XMunge uses DirectX Retained Mode which has been abandoned due to low adoption. This tool definitely could use a complete rewrite.

Pigs

Pigs are a set of testing tools. The main purpose is to provide a way to simulate many allegiance clients by not using real game clients but instead automated 'bots' that behave according to various scripts. To do so, the Pigs use the same Clintlib library than the game client in order to fully behave like real clients (at least as seen from the server). This is handy to stress test the server and the IGC and networking API.

mdlc

MDLC is a build time tool aimed at performing some manipulations on MDL model files. For how to use see mdlc.

One important thing about MDLC is that its code use the same engine code (src\engine) than the allegiance client, so it is always in sync regarding what models the client can handle.