Multiplayer protocol

From FlightGear wiki
Jump to: navigation, search
Caution  Developer information:

Some, and possibly most, of the details below are likely to be affected, or even deprecated, by the ongoing work on implementing and improving HLA support in FlightGear. For recent updates, please refer to HLA Timeline.
Please see: High-Level Architecture for further information
To avoid conflicting efforts, you are advised not to start working on anything directly related to this without first coordinating your ideas with FlightGear core developers using the FlightGear developers mailing list. talk page..

The multiplayer protocol is the way FlightGear communicates between instances and the multiplayer servers.

The multiplayer protocol uses XDR encoded messages that are sent via UDP. All messages are composed of XDR (eXternal Data Representation) encoded data as per RFC 1832.

XDR basically means that all data is in network byte order and aligned to the nearest multiple of 4 bytes. Strings are encoded as a zero-terminated array of characters, aligned to the nearest multiple of 4 bytes, and floating point numbers (32 or 64 bit) must be encoded as per the IEEE standard.

For the record, strings are limited to 128 characters (512 bytes) and packets are limited to 1200 bytes; these limits are hardocded in fgfs.[1]

As of mid 2016, there are plans being discussed to revamp the MP system [2].

Future Development

Cquote1.png note that Stuarts HLA efforts might render the MP protocol obsolete sooner or later - I think that's finally on the horion.
— Thorsten (Dec 13th, 2015). Military simulation (from Su-15 Screenshots).
(powered by Instant-Cquotes)
Cquote2.png
  • One thing I'd like to have is, in the debugging output of fgfs, the complete list of properties sent per packet. This would allow me to discover any properties that are transmitted without my knowledge or consent [3]

Data types

Warning  if an aircraft defines all possible properties in the protocol, it tries to send 14988 bytes per packet, almost 12.5 times the allowed limit! Your idea of sending properties in a round-robin fashion is good IMHO but good MP debugging tools are necessary for aircraft developers.[4]

The data is XDR encoded as the following types:

Caution  Due to a bug, all bytes in the STRING field are sent as 4-byte ints (not in the header or the position message). So STR has length (LEN * 4) bytes and padding ((4 - LEN%4) * 4) bytes, if LEN%4 is not 0.
Type Size Remarks
int 4 bytes Send unconditionally
float 4 bytes Send unconditionally
bool 4 bytes Send unconditionally
string (LEN + STR + PAD) bytes

LEN: 4 bytes, length of the decoded string
STR: (LEN * 4) bytes, encoded string
PAD: (n * 4) bytes, padding

Messages

Messages header

The header is always 32 bytes long and contains the following fields in exactly that order:

Field Size Remarks
Magic 4 bytes Always 0x46474653 ("FGFS")
Version 4 bytes Protocol version, currently 0x00010001 (1.1)
MsgId 4 bytes Defines what data is appended to the header. Can be 0x00000001 for chat messages (deprecated) or 0x00000007 for position data - all other values are outdated and ignored.
MsgLen 4 bytes Length of the data.
Caution  This is not in bytes, see the description of the STRING data type.
ReplyAddress 4 bytes Deprecated and ignored
ReplyPort 4 bytes Deprecated and ignored
Callsign 8 bytes Zero terminated array of characters representing the user callsign

Chat messages

The data for chat messages is a zero terminated array of characters. The MsgLen field in the header represents its length. The maximum length is defined to be 256 bytes.

Position messages

The data of position message is more complicated and is composed of a two parts. The first part contain information needed to place an aircraft model in the right position and orientation. The second part contain property values used for animating the model, provided the user on the receiving end would have that aircraft installed.

First part

  • Positions are in with respect to the Earth centered frame.
  • Orientations are with respect to the X, Y and Z axis of the Earth centered frame, stored in the angle axis representation where the angle is coded into the axis length.
  • Velocities are along the X, Y and Z directions of the Earth centered frame.
  • Angular accelerations are in two parts of the three dimensional angular velocity vector with respect to the Earth centered frame measured in the Earth centered frame.
  • Linear accelerations are in two parts of the three dimensional linear acceleration vector with respect to the Earth centered frame measured in the Earth centered frame.

The first part contain these fields in exactly that order:

Field Size Remarks
ModelName 96 bytes Zero terminated array of characters representing the aircraft model (/sim/model/path) used by the user
time 8 bytes Representing the time when this message was generated double
lag 8 bytes Time offset for network lag double
PosX 8 bytes XDR encoded double value, X-ccordinate of users position
PosY 8 bytes XDR encoded double value, Y-ccordinate of users position
PosZ 8 bytes XDR encoded double value, z-ccordinate of users position
OriX 4 bytes XDR encoded float value, X-orientation of the user
OriY 4 bytes XDR encoded float value, Y-orientation of the user
OriZ 4 bytes XDR encoded float value, Z-orientation of the user
VelX 4 bytes XDR encoded float value, velocity of the user in X direction
VelY 4 bytes XDR encoded float value, velocity of the user in Y direction
VelZ 4 bytes XDR encoded float value, velocity of the user in Z direction
AV1 4 bytes XDR encoded float value, 1. part of the three dimensional angular velocity vector
AV2 4 bytes XDR encoded float value, 2. part of the three dimensional angular velocity vector
AV3 4 bytes XDR encoded float value, 3. part of the three dimensional angular velocity vector
LA1 4 bytes XDR encoded float value, 1. part of the three dimensional linear accelaration vector
LA2 4 bytes XDR encoded float value, 2. part of the three dimensional linear accelaration vector
LA3 4 bytes XDR encoded float value, 3. part of the three dimensional linear accelaration vector
AA1 4 bytes XDR encoded float value, 1. part of the three dimensional angular accelaration vector
AA2 4 bytes XDR encoded float value, 2. part of the three dimensional angular accelaration vector
AA3 4 bytes XDR encoded float value, 3. part of the three dimensional angular accelaration vector
pad up to 8 bytes For padding the data to a multiple of 8 bytes

Second part

Note  This table is is current for FlightGear 3.2.0. For the list in the development version, see flightgear/src/MultiPlayer/multiplaymgr.cxx (line 70).

The fields of the second part are property values encoded in the form ID|Value.

The following properties are transmitted, but not necessarily all present or in this order:

ID Property Type
100 surface-positions/left-aileron-pos-norm float
101 surface-positions/right-aileron-pos-norm float
102 surface-positions/elevator-pos-norm float
103 surface-positions/rudder-pos-norm float
104 surface-positions/flap-pos-norm float
105 surface-positions/speedbrake-pos-norm float
106 gear/tailhook/position-norm float
107 gear/launchbar/position-norm float
108 gear/launchbar/state string
109 gear/launchbar/holdback-position-norm float
110 canopy/position-norm float
111 surface-positions/wing-pos-norm float
112 surface-positions/wing-fold-pos-norm float
200 gear/gear[0]/compression-norm float
201 gear/gear[0]/position-norm float
210 gear/gear[1]/compression-norm float
211 gear/gear[1]/position-norm float
220 gear/gear[2]/compression-norm float
221 gear/gear[2]/position-norm float
230 gear/gear[3]/compression-norm float
231 gear/gear[3]/position-norm float
240 gear/gear[4]/compression-norm float
241 gear/gear[4]/position-norm float
300 engines/engine[0]/n1 float
301 engines/engine[0]/n2 float
302 engines/engine[0]/rpm float
310 engines/engine[1]/n1 float
311 engines/engine[1]/n2 float
312 engines/engine[1]/rpm float
320 engines/engine[2]/n1 float
321 engines/engine[2]/n2 float
322 engines/engine[2]/rpm float
330 engines/engine[3]/n1 float
331 engines/engine[3]/n2 float
332 engines/engine[3]/rpm float
340 engines/engine[4]/n1 float
341 engines/engine[4]/n2 float
342 engines/engine[4]/rpm float
350 engines/engine[5]/n1 float
351 engines/engine[5]/n2 float
352 engines/engine[5]/rpm float
360 engines/engine[6]/n1 float
361 engines/engine[6]/n2 float
362 engines/engine[6]/rpm float
370 engines/engine[7]/n1 float
371 engines/engine[7]/n2 float
372 engines/engine[7]/rpm float
380 engines/engine[8]/n1 float
381 engines/engine[8]/n2 float
382 engines/engine[8]/rpm float
390 engines/engine[9]/n1 float
391 engines/engine[9]/n2 float
392 engines/engine[9]/rpm float
800 rotors/main/rpm float
801 rotors/tail/rpm float
810 rotors/main/blade[0]/position-deg float
811 rotors/main/blade[1]/position-deg float
812 rotors/main/blade[2]/position-deg float
813 rotors/main/blade[3]/position-deg float
820 rotors/main/blade[0]/flap-deg float
821 rotors/main/blade[1]/flap-deg float
822 rotors/main/blade[2]/flap-deg float
823 rotors/main/blade[3]/flap-deg float
830 rotors/tail/blade[0]/position-deg float
831 rotors/tail/blade[1]/position-deg float
900 sim/hitches/aerotow/tow/length float
901 sim/hitches/aerotow/tow/elastic-constant float
902 sim/hitches/aerotow/tow/weight-per-m-kg-m float
903 sim/hitches/aerotow/tow/dist float
904 sim/hitches/aerotow/tow/connected-to-property-node bool
905 sim/hitches/aerotow/tow/connected-to-ai-or-mp-callsign string
906 sim/hitches/aerotow/tow/brake-force float
907 sim/hitches/aerotow/tow/end-force-x float
908 sim/hitches/aerotow/tow/end-force-y float
909 sim/hitches/aerotow/tow/end-force-z float
930 sim/hitches/aerotow/is-slave bool
931 sim/hitches/aerotow/speed-in-tow-direction float
932 sim/hitches/aerotow/open bool
933 sim/hitches/aerotow/local-pos-x float
934 sim/hitches/aerotow/local-pos-y float
935 sim/hitches/aerotow/local-pos-z float
1001 controls/flight/slats float
1002 controls/flight/speedbrake float
1003 controls/flight/spoilers float
1004 controls/gear/gear-down float
1005 controls/lighting/nav-lights float
1006 controls/armament/station[0]/jettison-all bool
1100 sim/model/variant int
1101 sim/model/livery/file string
1200 environment/wildfire/data string
1201 environment/contrail int
1300 tanker int
1400 scenery/events string
1500 instrumentation/transponder/transmitted-id int
1501 instrumentation/transponder/altitude int
1502 instrumentation/transponder/ident bool
1503 instrumentation/transponder/inputs/mode int
10001 sim/multiplay/transmission-freq-hz string
10002 sim/multiplay/chat string
10100 sim/multiplay/generic/string[0] string
10101 sim/multiplay/generic/string[1] string
10102 sim/multiplay/generic/string[2] string
10103 sim/multiplay/generic/string[3] string
10104 sim/multiplay/generic/string[4] string
10105 sim/multiplay/generic/string[5] string
10106 sim/multiplay/generic/string[6] string
10107 sim/multiplay/generic/string[7] string
10108 sim/multiplay/generic/string[8] string
10109 sim/multiplay/generic/string[9] string
10110 sim/multiplay/generic/string[10] string
10111 sim/multiplay/generic/string[11] string
10112 sim/multiplay/generic/string[12] string
10113 sim/multiplay/generic/string[13] string
10114 sim/multiplay/generic/string[14] string
10115 sim/multiplay/generic/string[15] string
10116 sim/multiplay/generic/string[16] string
10117 sim/multiplay/generic/string[17] string
10118 sim/multiplay/generic/string[18] string
10119 sim/multiplay/generic/string[19] string
10200 sim/multiplay/generic/float[0] float
10201 sim/multiplay/generic/float[1] float
10202 sim/multiplay/generic/float[2] float
10203 sim/multiplay/generic/float[3] float
10204 sim/multiplay/generic/float[4] float
10205 sim/multiplay/generic/float[5] float
10206 sim/multiplay/generic/float[6] float
10207 sim/multiplay/generic/float[7] float
10208 sim/multiplay/generic/float[8] float
10209 sim/multiplay/generic/float[9] float
10210 sim/multiplay/generic/float[10] float
10211 sim/multiplay/generic/float[11] float
10212 sim/multiplay/generic/float[12] float
10213 sim/multiplay/generic/float[13] float
10214 sim/multiplay/generic/float[14] float
10215 sim/multiplay/generic/float[15] float
10216 sim/multiplay/generic/float[16] float
10217 sim/multiplay/generic/float[17] float
10218 sim/multiplay/generic/float[18] float
10219 sim/multiplay/generic/float[19] float
10300 sim/multiplay/generic/int[0] int
10301 sim/multiplay/generic/int[1] int
10302 sim/multiplay/generic/int[2] int
10303 sim/multiplay/generic/int[3] int
10304 sim/multiplay/generic/int[4] int
10305 sim/multiplay/generic/int[5] int
10306 sim/multiplay/generic/int[6] int
10307 sim/multiplay/generic/int[7] int
10308 sim/multiplay/generic/int[8] int
10309 sim/multiplay/generic/int[9] int
10310 sim/multiplay/generic/int[10] int
10311 sim/multiplay/generic/int[11] int
10312 sim/multiplay/generic/int[12] int
10313 sim/multiplay/generic/int[13] int
10314 sim/multiplay/generic/int[14] int
10315 sim/multiplay/generic/int[15] int
10316 sim/multiplay/generic/int[16] int
10317 sim/multiplay/generic/int[17] int
10318 sim/multiplay/generic/int[18] int
10319 sim/multiplay/generic/int[19] int

Related content

Wiki articles

Forum topics

Source code

XDR handling

Message types

Multiplayer system

External links

  • Ludovic Brenta  (May 3rd, 2016).  Re: [Flightgear-devel] dual-control-tools and the limit on packet size .
  • Richard Harrison  (Jun 1st, 2016).  [Flightgear-devel] RFC: Proposal for changes to the multiplayer system. .
  • Ludovic Brenta  (Oct 20th, 2016).  Re: [Flightgear-devel] C172 MP alert on console .
  • Ludovic Brenta  (Oct 21st, 2016).  Re: [Flightgear-devel] C172 MP alert on console .