Howto:Transmit properties over MP

This article is a stub. You can help the wiki by expanding it.

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.

This wiki article will teach you how to transmit properties over a network.

Certain properties (eg. rudder deflection, flaps setting and gear position) are transmitted by default over the multiplayer network. However there are still lots of (mostly aircraft specific) properties that are not. Due to this limitation, certain animations (eg. opening of a door or landing lights) won't be visible for a pilot's virtual-colleagues.

The number of properties that can be sent over MP is limited. If you have properties that do not need to be sent frequently (e.g. only when a certain event happens) these can be sent more efficiently using mp_broadcast.nas in $FG_ROOT/Nasal, please see Howto:Using mp_broadcast.nas, or using the time-sharing (TDM) or bit-packed components (SwitchEncoder/Decoder) for booleans in Aircraft/Generic/DualControl/dual-control-tools.nas.

The method described here will send the properties in question in every multiplayer packet. This is appropriate for parts that need continuous animation but wasteful for many other uses. On the other hand, the method described here is easy to use so if you only have a small number of properties to share it may still be preferable.

-set.xml

<multiplay>
  <generic>
    <bool n="0" alias="/controls/lighting/landing-light-l"/>
    <bool n="1" alias="/controls/lighting/landing-light-r"/>
    <int n="0" alias="/consumables/fuel/total-fuel-lbs"/>
    <float n="0" alias="/controls/flight/flaps"/>
    <short n="0" alias="/instrumentation/airspeed-indicator/indicated-speed-kt" />
    <string n="0" alias="/sim/model/livery/texture"/>
  </generic>
</multiplay>

There are three types of properties that could be used:

• bool[0..90]: on/off, true false
• float[0..39]: decimal numbers (0.12, 5.01 ...).
• int[0..19]: whole/natural numbers (... -1, 0, 1, 2 ...), range +/- 2,147,483,647
• short[0..79]: whole/natural numbers (... -1, 0, 1, 2 ...), range +/- 32767
• string[0..19]: alphanumeric values (PH-TST, EH01 ...).

Notes:

1. Each type is separately numbered; you can have an int n="0" beside a float n="0"
2. Always use bools to represent on/off values. These are the most efficient with all 90 bools taking only 24bytes of MP packet.
3. Prefer to use shorts instead of ints and floats because they use half the space (4bytes) of an int or float (8bytes)
4. Avoid using strings wherever possible as a string will take 4bytes + length of string.

The value behind alias= is the (local) path to the property that has to be transmitted. Make sure that the local property has the same type as the generic MP enabled one (note that bools are automatically converted to integers so you can map an MP enabled int to a local bool). It is important to remember to not explicitly define the property type in an alias property.

In the 3d model XML file

If the MP enabled properties are to be used in animations it is preferable to create aliases for them on the remote systems so that the animations can be written using the logical properties rather than the "sim/multiplay/generic/..." ones. The example below creates the "fdm/jsbsim/propulsion/engine[x]/pitch-angle-rad" properties in the AI/MP aircraft property subtree as aliases for the MP properties. In that way the relevant animations can use the more meaningful property name "fdm/jsbsim/propulsion/engine[x]/pitch-angle-rad" instead of "sim/multiplay/generic/float[x]".

NOTE: it is nicer to other players to avoid having any timers inside the model XML as this can have a performance impact when there are a lot of MP aircraft.

<nasal>
  <load>
   ##############################################################################
   # The on-load Nasal is not executed when this file is loaded as the user
   # aircraft.
   ##############################################################################
   var rplayer = cmdarg();
   # Set up property aliases for animations.
   rplayer.getNode("fdm/jsbsim/propulsion/engine[0]/pitch-angle-rad", 1).
     alias(rplayer.getNode("sim/multiplay/generic/float[0]"));
   rplayer.getNode("fdm/jsbsim/propulsion/engine[1]/pitch-angle-rad", 1).
     alias(rplayer.getNode("sim/multiplay/generic/float[1]"));
   rplayer.getNode("fdm/jsbsim/propulsion/engine[2]/pitch-angle-rad", 1).
     alias(rplayer.getNode("sim/multiplay/generic/float[2]"));
   ##############################################################################
  </load>
</nasal>

Alternatively this can be done without using nasal. Again in the model xml file:

<params>
  <lighting>
    <landing-light-l>
      <property>sim/multiplay/generic/bool[0]</property>
    </landing-light-l>
  </lighting>
</params>

Then in the animation use:

<property alias="../../params/lighting/landing-light-l/property"/>

Related content

• Aircraft-set.xml
• Aircraft properties reference
• Multiplayer protocol
• Howto:Using mp broadcast.nas
• Livery_over_MP