Code documentation: Difference between revisions
m (→XMunge) |
m (had a go at fixing grammer.) |
||
| Line 1: | Line 1: | ||
== Overview == | == Overview == | ||
The key components of Allegiance are: | The key components of Allegiance are: | ||
| Line 10: | Line 6: | ||
*the lobby - '''AllLobby.exe''' | *the lobby - '''AllLobby.exe''' | ||
In a typical configuration | In a typical configuration there are many [[Who pays for Allegiance?#Allegiance Game Servers|game servers]] and clients (players) which connect to a single [[Who pays for Allegiance?#Allegiance Main Servers|lobbyserver]]. 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 chosen server. A server can host many games at once but 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 | |||
These keys components share many lines of code with the use of common libraries. | 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|IGC library]] which handles the game logic. | The most notable ones are the [[messsaging API library]] which is built on Microsoft DirectPlay and the [[#IGC library|IGC library]] which handles the game logic. | ||
<i>(The picture below is difficult to understand, especially <u>why</u> it is there, and what the layout means. Perhaps an explanation about it should be added here? - juckto)</i> | |||
[[Image:AllegOverview.png]] | [[Image:AllegOverview.png]] | ||
{{stub}} | {{stub}} | ||
== ZLib and Utility libraries == | == ZLib and Utility libraries == | ||
The '''ZLib''' library is a set of helper classes. It's used by all projects in the allegiance source. | 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 most notable items of ZLib are: | ||
*the ''ZString'' class which deal with strings. | *the ''ZString'' class which deal with strings. | ||
| Line 32: | Line 30: | ||
*the messaging API (network code) which is build on top of [http://en.wikipedia.org/wiki/DirectPlay DirectPlay] | *the messaging API (network code) which is build on top of [http://en.wikipedia.org/wiki/DirectPlay DirectPlay] | ||
*dynamic linked lists of pointers used widely in the several parts of the source. | *dynamic linked lists of pointers used widely in the several parts of the source. | ||
== IGC library == | == IGC library == | ||
IGC stands for '''Internet Game Core'''. It's the game logic library (API) and it's shared between clients and servers. | |||
=== IGC Interfaces & Objects === | === IGC Interfaces & Objects === | ||
IGC is accessed with of a set of hierarchical abstract classes (interfaces) that hold all the game objects (ships, stations, sectors, | IGC is accessed with of a set of hierarchical abstract classes (interfaces) that hold all the game objects (ships, stations, sectors, etc) and their current properties (position, speed, etc). 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, etc) 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 [[#ZLib and Utility libraries|Utility]] library). | ||
''ImissionIGC'' is implemented in the ''CmissionIGC'' class (src\Igc\missionigc.cpp). It holds lists of all other objets (ships,stations, | |||
The most notable method of ''ImissionIGC'' is the the ''''Update'''' member method. | The most notable method of ''ImissionIGC'' is the the ''''Update'''' member method. | ||
| Line 47: | Line 45: | ||
Image:IGCInterfaces.png|Class Diagram | Image:IGCInterfaces.png|Class Diagram | ||
</gallery></div> | </gallery></div> | ||
When the game needs to create a new object | When the game needs to create a new object the IGC library usually provides a 'template' for this object, instead of the game creating it from scratch. The template holds several attributes that are used as initial values for the corresponding attributes of the new object. There can be many different templates for a given object type and the game must tell (<i>tell who? -juck</i>) which template to use when creating an object. This is how there can be different [[factions]] with different stations, ships and weapons. | ||
For example | |||
: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 because they are constant they're not transmitted between the server and the clients. Instead the data is stored into what we call a [[core]] file. So when a client joins a game on a server the server tells the client the core file name the game is using and the client will load it from its local artwork folder. This process avoids having to send large files over the network. If the file doesn't match then the client will get an error message "files out of sync". | |||
=== IGC Callbacks === | === IGC Callbacks === | ||
Since both server and client share the IGC code, | Since both server and client share the IGC code many of the game state changes can be handled on the client side alone, without the need for sending information over the internet. | ||
:For example: when a ship is destroyed the client will need to draw the ship explosion but the server does not. However the server does need to propagate that event to the other clients (or at least to the clients which need to know about that explosion). | |||
Both client and server are said to be '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. | 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. | ||
''IsiteIGC'' is not the only callback set, there are others: | ''IsiteIGC'' is not the only callback set, there are others: | ||
the ''ThingSite'' interface which deals with objects having a model (mainly all IGC objects derived from ''TmodelIGC<T>'') | *the ''ThingSite'' interface which deals with objects having a model (mainly all IGC objects derived from ''TmodelIGC<T>'') | ||
the ''ClusterSite'' intertace which deals with sectors. | *the ''ClusterSite'' intertace which deals with sectors. | ||
These allows to add callbacks on a per object scope instead of using only the global ones of ''IsiteIGC''. | These allows to add callbacks on a per object scope instead of using only the global ones of ''IsiteIGC''. | ||
=== Client/Server communication & updates === | === Client/Server communication & updates === | ||
Since both client and server share the same IGC code but react differently to it | Since both client and server share the same IGC code but react differently to it, only a subset of the game logic updates are done within the IGC library. The main entry for this is CmissionIGC::Update(...) which is called every tick on all clients and server (but each client has only a subset of the a game IGC objects whereas the server has everything). | ||
The remaining game logic updates are all handled by the server. This includes collisions, damages, object creations and some object deletions (some object deletions are processed inside IGC library and so are performed on all sides during the ''Update(...)'' without requiring network exchanges). | The remaining game logic updates are all handled by the server. This includes collisions, damages, object creations and some object deletions (some object deletions are processed inside IGC library and so are performed on all sides during the ''Update(...)'' without requiring network exchanges). | ||
Even if IGC is the game logic layer, a lot of game logic code isnt in it. So | |||
Even if IGC is the game logic layer, a lot of game logic code isnt in it. So keep in mind when you are making changes to the game logic: they require careful inspection and knowledge in order to be performed correctly - it's not all in the IGC library. | |||
== WinTrek - Allegiance Client == | == WinTrek - Allegiance Client == | ||
'''Allegiance.exe''' is the game client. It is build from many subprojects, the top one been src\WinTrek. | '''Allegiance.exe''' is the game client. It is build from many subprojects, the top one been src\WinTrek. | ||
The client (refered as '''WinTrek''' there after) consists of several layers on top or next of each others. | *The client (refered as '''WinTrek''' there after) consists of several layers on top or next of each others. | ||
The lower one is ClintLib which is the minimalist game client without any UI at all. It deals with everything needed to connect to lobby/servers and handles the game logic. | *The lower one is ClintLib which is the minimalist game client without any UI at all. It deals with everything needed to connect to lobby/servers and handles the game logic. | ||
WinTrek is the code that links ClintLib with 3 engines (gfx, effects and sound) and a training module in order to produce Allegiance.exe. | *WinTrek is the code that links ClintLib with 3 engines (gfx, effects and sound) and a training module in order to produce Allegiance.exe. | ||
These various components are explained here after. | These various components are explained here after. | ||
=== ClintLib === | === ClintLib === | ||
The '''ClintLib''' name is presumed to be a shortcut for "Client Library". It's a library project that use [[#IGC library|IGC library]] and produces an interface less, minimalist game client that can fully communicate with game servers and the lobby. | The '''ClintLib''' name is presumed to be a shortcut for "Client Library". It's a library project that use [[#IGC library|IGC library]] and produces an interface-less, minimalist game client that can fully communicate with game servers and the lobby. | ||
The main class of ClintLib is ''BaseClient'' from which any working allegiance game client | The main class of ClintLib is ''BaseClient'' from which any working allegiance game client needs to inherit from (<i>inherit <u>what</u> from? -juck</i>). As of today, only 2 known executables are built on it: Allegiance.exe and the [[#Pigs|Pigs]] test system. | ||
ClintLib is totally independent of the "engines" layers. Its purpose is to isolate everything that is about game logic and network communication. It's definitely the starting foundation on which one could write a brand new client with a new gfx engine for instance. | ClintLib is totally independent of the "engines" layers. Its purpose is to isolate everything that is about game logic and network communication. It's definitely the starting foundation on which one could write a brand new client with a new gfx engine for instance. | ||
===Graphic engine=== | ===Graphic engine=== | ||
This is the graphical engine. It deals with .. TBC {{stub}} | This is the graphical engine. It deals with .. TBC {{stub}} | ||
===Effect engine=== | ===Effect engine=== | ||
The effect engine is built on top of the graphic engine... TBC {{stub}} | The effect engine is built on top of the graphic engine... TBC {{stub}} | ||
===Sound engine=== | ===Sound engine=== | ||
{{stub}} | {{stub}} | ||
===Training=== | ===Training=== | ||
{{stub}} | {{stub}} | ||
| Line 101: | Line 113: | ||
===Pigs=== | ===Pigs=== | ||
Pigs are a set of testing tools. | Pigs are a set of testing tools. Their main purpose is to provide a way to simulate many allegiance clients by using automated 'bots' that behave according to various scripts. This allows a single developer to simulate a game with many players during testing. | ||
To do so, the Pigs use the same [[#Clintlib|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 | To do so, the Pigs use the same [[#Clintlib|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, IGC, and networking APIs. | ||
===mdlc=== | ===mdlc=== | ||
MDLC is a ''build time'' tool aimed at performing some manipulations on MDL model files. | MDLC is a ''build time'' tool aimed at performing some manipulations on MDL model files. | ||
For how to use see [[MDLC|mdlc]]. | For instructions on how to use it see [[MDLC|mdlc]]. | ||
One important thing about MDLC is that its code use the same [[#Graphic_engine|engine]] code (src\engine) than the allegiance client, so it is always in sync regarding what models the client can handle. | One important thing about MDLC is that its code use the same [[#Graphic_engine|engine]] code (src\engine) than the allegiance client, so it is always in sync regarding what models the client can handle. | ||
[[Category:Development]] | |||
Revision as of 02:14, 18 May 2008
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 game servers and clients (players) which connect to a single lobbyserver. 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 chosen server. A server can host many games at once but a client can join only one server and one game at a time.
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.
(The picture below is difficult to understand, especially why it is there, and what the layout means. Perhaps an explanation about it should be added here? - juckto)
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 Interfaces & Objects
IGC is accessed with of a set of hierarchical abstract classes (interfaces) that hold all the game objects (ships, stations, sectors, etc) and their current properties (position, speed, etc). 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, etc) 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 the IGC library usually provides a 'template' for this object, instead of the game creating it from scratch. The template holds several attributes that are used as initial values for the corresponding attributes of the new object. There can be many different templates for a given object type and the game must tell (tell who? -juck) which template to use when creating an object. This is 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 because they are constant they're not transmitted between the server and the clients. Instead the data is stored into what we call a core file. So when a client joins a game on a server the server tells the client the core file name the game is using and the client will load it from its local artwork folder. This process avoids having to send large files over the network. If the file doesn't match then the client will get an error message "files out of sync".
IGC Callbacks
Since both server and client share the IGC code many of the game state changes can be handled on the client side alone, without the need for sending information over the internet.
- For example: when a ship is destroyed the client will need to draw the ship explosion but the server does not. However the server does need to propagate that event to the other clients (or at least to the clients which need to know about that explosion).
Both client and server are said to be '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. IsiteIGC is not the only callback set, there are others:
- the ThingSite interface which deals with objects having a model (mainly all IGC objects derived from TmodelIGC<T>)
- the ClusterSite intertace which deals with sectors.
These allows to add callbacks on a per object scope instead of using only the global ones of IsiteIGC.
Client/Server communication & updates
Since both client and server share the same IGC code but react differently to it, only a subset of the game logic updates are done within the IGC library. The main entry for this is CmissionIGC::Update(...) which is called every tick on all clients and server (but each client has only a subset of the a game IGC objects whereas the server has everything).
The remaining game logic updates are all handled by the server. This includes collisions, damages, object creations and some object deletions (some object deletions are processed inside IGC library and so are performed on all sides during the Update(...) without requiring network exchanges).
Even if IGC is the game logic layer, a lot of game logic code isnt in it. So keep in mind when you are making changes to the game logic: they require careful inspection and knowledge in order to be performed correctly - it's not all in the IGC library.
WinTrek - Allegiance Client
Allegiance.exe is the game client. It is build from many subprojects, the top one been src\WinTrek.
- The client (refered as WinTrek there after) consists of several layers on top or next of each others.
- The lower one is ClintLib which is the minimalist game client without any UI at all. It deals with everything needed to connect to lobby/servers and handles the game logic.
- WinTrek is the code that links ClintLib with 3 engines (gfx, effects and sound) and a training module in order to produce Allegiance.exe.
These various components are explained here after.
ClintLib
The ClintLib name is presumed to be a shortcut for "Client Library". It's a library project that use IGC library and produces an interface-less, minimalist game client that can fully communicate with game servers and the lobby. The main class of ClintLib is BaseClient from which any working allegiance game client needs to inherit from (inherit what from? -juck). As of today, only 2 known executables are built on it: Allegiance.exe and the Pigs test system. ClintLib is totally independent of the "engines" layers. Its purpose is to isolate everything that is about game logic and network communication. It's definitely the starting foundation on which one could write a brand new client with a new gfx engine for instance.
Graphic engine
This is the graphical engine. It deals with .. TBC
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!
Effect engine
The effect engine is built on top of the graphic engine... TBC
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!
Sound engine
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!
Training
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!
FedSrv - Allegiance Game Server
AGC Library
AllSrvUI
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!
Lobby - Allegiance Lobby Server
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!
Tools
XMunge
XMunge is a build time tool aimed at manipulating DirectX .X files. XMunge uses Direct3D 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. Their main purpose is to provide a way to simulate many allegiance clients by using automated 'bots' that behave according to various scripts. This allows a single developer to simulate a game with many players during testing.
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, IGC, and networking APIs.
mdlc
MDLC is a build time tool aimed at performing some manipulations on MDL model files. For instructions on how to use it 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.
