fgms 0.11.8
The
FlightGear MultiPlayer Server
project
page_developers_guide.cxx
Go to the documentation of this file.
1  /**
2  * \page developers_guide Developers Guide
3  *
4  *
5  *
6  * \section the_code Source Code
7  * * The source for the project is versioned using git
8  * * The repository is hosted at gitlab.com
9  * - https://gitlab.com/fgms/fgms-0-x
10  *
11  * To checkout the source code run
12  * \code
13  * git clone https://gitlab.com/fgms/fgms-0-x.git
14  * \endcode
15  *
16  *
17  *
18  * \section code_layout Code Layout
19  * * <b>src/</b>
20  * - <b>server/</b> - the source code for \ref fgms
21  * - <b>flightgear/</b> - see \ref flightgear_inc below
22  * - <b>plib/</b> - see \ref plib below
23  * - <b>simgear/</b> - see \ref simgear below
24  * * <b>contrib/</b>
25  * - <b>fgracker/</b> - the \ref tracker_server
26  * - <b>mpstatus/</b> - a www page and perl script to query mp statuses
27  * - <b>plib/</b> - see \ref plib below
28  * - <b>tools/</b> - contains check_fgms.sh, a script to check fgms status
29  * * <b>docs/</b> - stuff to do with documentation in this page
30  *
31  * \section other_libs Other Libs
32  * The fgms repository contains all the libs required to install. However some parts were
33  * copied, borrowed etc from other sources:
34  *
35  * \subsection simgear simgear
36  * - Low level maths, geospatial calculations, etc
37  * - fgms used the constants, logging and some structures
38  * - simgear and flightear source are very closely related
39  * - Info: http://wiki.flightgear.org/SimGear
40  * - Code: https://gitorious.org/fg/simgear
41  * - parts of simgear have been copied into <b>src/simgear</b>
42  *
43  * \subsection plib plib
44  * - PLIB - A Suite of Portable Game Libraries
45  * - fgms used the network sockets (see netSocket.hxx and netSocket.cxx)
46  * - Info: http://plib.sourceforge.net
47  * - parts of plib have been copied into <b>src/plib/</b>
48  *
49  * \subsection flightgear_inc flightgear
50  * - fgms uses parts of the mpmessages and \ref xdr code. (see mpmessages.hxx and tiny_xdr.hxx)
51  * - Info: \ref FlightGear page
52  * - parts of flightgear have been copied into <b>src/flightgear/</b>
53  *
54  *
55  * \section mp_overview MultiPlayer Overview
56  * This is an overview about how the communicatinons works between \ref fgfs instances via an \ref fgms.
57  * * The table below shows communications with three players over a network
58  * * Messages are sent a few times a second
59  *
60  * <table>
61  * <tr><th>fgms - me</th><th>packet</th><th>fgms</th><th>packet</th><th>fgms - others</th></tr>
62  * <tr><td>me</td><td>> send ></td><td>> relay ></td><td>> recv ></td><td>other 1</td></tr>
63  * <tr><td> </td><td> </td><td> </td><td>> recv ></td><td>other 2</td></tr>
64  * <tr><td>me</td><td>< recv <</td><td>< relay <</td><td>< send <</td><td>other 1</td></tr>
65  * <tr><td></td><td> </td><td>> relay ></td><td>> recv ></td><td>other 2</td></tr>
66  * </table>
67  *
68  * \section date_interchange Data Interchange
69  * - <b>Send</b>
70  * - packets are assembled on an \ref fgfs instance, values such as callsign, position, speed etc
71  * - the values are packaged into an \ref xdr encoded binary blob
72  * - the packet is transmitted via udp out to an mp server
73  * - eg --multiplayer=out,15,mpserver14.flightgear.org,5000
74  *
75  * - <b>MpServer</b>
76  * - an \ref fgms server will recieve this as a "LOCAL" connection, ie a direct connection (FG_SERVER::HandlePacket)
77  * - fgms will then relay the packet to other local players, and to the relay servers (FG_SERVER::SendToRelays)
78  * - <b>Reciever</b>
79  * - a \ref fgms client the other ends will recive the packet
80  * - decode the data encoded in \ref xdr
81  * - then update the sim with this data
82  * - <b>And < vice > versa</b>
83  *
84  *
85  *
86  *
87  * \section mp_messages Data Packets
88  * - The data encoded into a sequence of bytes using \ref xdr.
89  * - Every packet starts with 'Header' bytes which define whats in the rest of the packet.
90  * <table>
91  * <tr><th colspan="2">An Mp Message Packet</th></tr>
92  * <tr><td>Header</td><td>Other data</td></tr>
93  * </table>
94  *
95  * \subsection p_header Header
96  * - The T_MsgHdr is the c struct used to define the header.
97  * <table>
98  * <tr><th>Name</th><th>Comment</th></tr>
99  * <tr><td>Magic</td><td>The "magic" that must start each packet, see ::MSG_MAGIC</td></tr>
100  * <tr><td>ProtoVer</td><td>The protocol version which must match - see ::PROTO_VER </td></tr>
101  * <tr><td>MsgId</td><td>the MsgId is the "type" of message that is sent</td></tr>
102  * <tr><td>MsgLen</td><td>The length of this message</td></tr>
103  * <tr><td>ReplyAddr</td><td>--not-used--</td></tr>
104  * <tr><td>ReplyPort</td><td>--not-used--</td></tr>
105  * <tr><td>Callsign</td><td>Length is ::MAX_CALLSIGN_LEN abc123</td></tr>
106  * </table>
107  * - T_MsgHdr::MsgId - the MsgId is one of:
108  * - ::POS_DATA_ID - a position message and the most trafficked
109  * - ::RESET_DATA_ID - to reset ?
110  * - ::CHAT_MSG_ID - for mp chat BUT
111  * \warning ::CHAT_MSG_ID is not used in current implementation. Instead chat is packaged into properties.
112  *
113  * \subsection p_position Position Message
114  * - T_PositionMsg is the c struct used to define a position
115  * <table>
116  * <tr><th>Name</th><th>Comment</th></tr>
117  * <tr><td>Model</td><td>Length is ::MAX_MODEL_NAME_LEN eg /model/foo/aero.xml</td></tr>
118  * <tr><td>time</td><td>epoch time</td></tr>
119  * <tr><td>lag</td><td>lag ??</td></tr>
120  * <tr><td>position</td><td>double[3]</td></tr>
121  * <tr><td>orientation</td><td>float[3]</td></tr>
122  * <tr><td>linearVel</td><td>float[3]</td></tr>
123  * <tr><td>angularVel</td><td>float[3]</td></tr>
124  * <tr><td>linearAccel</td><td>float[3]</td></tr>
125  * <tr><td>angularAccel</td><td>float[3]</td></tr>
126  * </table>
127  *
128  * \section xdr XDR
129  * * External Data Representation
130  * - Info: http://en.wikipedia.org/wiki/External_Data_Representation
131  * - Spec: http://www.ietf.org/rfc/rfc1832.txt
132  *
133  * <i>XDR is a standard data serialization format. It allows data to be transferred between different kinds of computer systems. Converting from the local representation to XDR is called encoding. Converting from XDR to the local representation is called decoding. XDR is implemented as a software library of functions which is portable between different operating systems and is also independent of the transport layer.</i>
134  *
135  * fgms uses a small subset of xdr necessary for multiplayer. This is defined in tiny_xdr.hxx
136  *
137  * \section contribute Contribute
138  * You are more than welcome to contribute to the project.
139  * * If you have a patch, or a bug then contact one of the \ref developers or the \ref fg_mailing_list
140  * * Looks at the \ref bugs
141  *
142  *
143  *
144  * \section Documentation
145  * The documentation is created using doxygen and is generated from source.
146  * * Here for some formating info
147  * - http://www.stack.nl/~dimitri/doxygen/manual/commands.html
148  * * Private variables/function are documented
149  * * Pages, ie stuff not related to source such as this page are in <b>/doc/pages/</b>
150  * * The doxygen tag file is located at <b>fgms.tag</b>
151  * * Doxygen 1.8+ is required for building the documents.
152  */