Howto:Add submodels

B-29s dropping their load.

Submodels are the means in FlightGear whereby we can represent anything which is dropped, fired, or launched from an aircraft or indeed any model... the possibilies are endless. Some examples which can be found in FlightGear: guns, flares, bombs, droptanks, smoke, contrails. These last to date from a time before particles were implemented in FlightGear. While they still exist in older models, they are probably nowadays best done with particles.

In general, AI Models are instantiated at startup. Submodels, which use only AIBallistic objects, are pre-loaded at startup, but only instantiated when required.

This howto will explain how to add submodels to your model

Step 1: creating the submodel

First, you need to create a file with the extension .xml containg at least one <submodel> tag. Here is an example taken from the b29:

<submodel>
  <name>M-17.001-submodel</name>
  <model>/Aircraft/b29/Models/M17.xml</model>
  <trigger>/sim/weapons/loadout[1]/bomb[0]/dropped</trigger>
  <repeat>false</repeat>
  <count>1</count>
  <speed>0</speed>
  <wind>false</wind>
  <aero-stabilised>true</aero-stabilised>
  <eda>1.42</eda>
  <cd>0.75</cd>
  <weight>500</weight>
  <x-offset>-49.3968</x-offset>
  <y-offset>1.968</y-offset>
  <z-offset>-1.8368</z-offset>
  <pitch-offset>0</pitch-offset>
  <yaw-offset>0</yaw-offset>
  <life>900</life>
  <delay>0</delay>
  <impact>true</impact>
  <impact-reports>sim/ai/aircraft/impact/bomb</impact-reports>
</submodel>

Notes:

1. Put the <PropertyList> tag before and </PropertyList> tag after the following document of course, as all our xml's carry this at the start and end! This file can be put anywhere you like in the property tree, but ~/Aircraft/"your model"/Models is usual.
2. All measurements are in Imperial Measure: Feet, Inches, Pounds. This is because the original author(s) were American. Please do not ask for this to be changed. There is simply too much work involved in doing so.
3. Yet another co-ordinate system is introduced; see below.
4. The trigger is a boolean property, which you define, which when "true" causes the submodel to be released/launched.
5. A submodel will create an AIBallistic object which will follow a ballistic path. By default one submodel will be released when the corresponding trigger is "true". The initial conditions (IC) define the object's starting point (relative to the user model's current position), and its initial speed and direction (relative to that of the user model aircraft). If you want to release many similar objects with the same IC, then you may use the <repeat>, <delay> and <count> properties to define this.
6. There is a long list of allowable tags. The allowed properties are:

     <name>         The name of the submodel.
     <model>        The path to the visual model. Any model in any location is allowed. All the normal
                    animations are available.
     <trigger>      The property which will act as the trigger. 
     <speed>        Initial speed, in feet/sec, relative to user aircraft.
     <repeat>       Set "true" if you want multiple releases of this submodel. Defaults
                    to false
     <delay>        Time, in seconds, between repeated releases.
     <count>        Number of submodels available for multiple release.
     <x-offset>     Submodel's initial fore/aft position relative to user aircraft.  
                    Fore is positive. (ft)
     <y-offset>     Submodel's initial left/right position relative to user aircraft.  
                    Right is positive. (ft)
     <z-offset>     Submodel's initial up/down position relative to user aircraft.  
                    Up is positive. (ft)
     <yaw-offset>   Submodel's initial azimuth, in degrees, relative to user aircraft's
                    nose.  Right is positive.
     <pitch-offset> Submodel's initial elevation, in degrees, relative to user aircraft's
                    pitch.  Up is positive.
     <buoyancy>     Submodel's upward acceleration (fps) due to buoyancy in air. 32 is 
                    neutral (contrails),  > 32 exhaust gas, smoke. 
     <wind>	     If true, the Submodel is affected by local wind. Defaults to false. This
                    tag was added to cater for smoke, contrails and the like. The effect of 
                    wind on ballistic objects is not well modelled. For bombs, bulllets etc. 
                    this is best left at the default setting.
     <cd>           The Coeffient of Drag. Varies with submodel shape - 0.295 for a bullet, 
                    0.045 for an airfoil. Enter an appropriate value. Defaults to 0.295.
     <eda>          Effective drag area (sq ft). Usually the cross-sectional area of the 
                    submodel normal to the airflow.
     <weight>       The weight of the submodel (lbs). Defaults to 0.25	
     <aero-stabilised> If true, the submodel aligns with the local airflow. Defaults to true.
     <external-force> If true the submodel is subjected to an external force.
     <force-path>   A string describing the property where the magnitude, azimuth and elevation
                    of the external force is to be found. The following child properties are
                    instantiated:
                       ~/force-lb
                       ~/force-azimuth-deg
                       ~/force-elevation-deg
                    You need to manipulate these properties with some Nasal to apply an external
                    force to the submodel.
     <force-stabilised> If true, the submodel aligns with the external force. Defaults to false.
                    If both this and <aero-stabilised> are true this takes priority.
     <no-roll>      If true, the submodel does not bank in turns. Defaults to false.
     <collision>    If true, the position of collisions (or hits) with other non-ballistic 
                    AI models are reported. Defaults to false.
     <impact>       If this is true the position of impact on the terrain is reported. Defaults to
                    false.
     <expiry>       If true, the postion of the Submodel when its life expires is reported. Defaults
                    to false. Collision, Impact, and Expiry are handled in that order.
     <impact-reports> A string descibing the location of Collision, Impact, or Expiry position.
                    Defaults to "/ai/models/model-impact".
     <fuse-range>   Range (ft) added to Collision and Impact calculations. Defaults to 0.0.
     <contents>     A string describing the property where the contents (lbs) of a Submodel are located.
                    Used with droptanks. Set to zero on release. Defaults to "none".
     <speed-prop>   A string describing the property where the initial speed of the Submodel is located.
                    Defaults to "none".
     <submodel-path> A string describing the path to the .xml file where the next submodel Initial 
                    Conditions are located. This submodel will be instantiated when any of Collision
                    Impact or Expiry are true. Submodels can be linked to any depth using this tag.
                    Defaults to "".
     <random>       If true, initial Azimuth is varied by +- 10 degrees, cd by 10%, and Life by the
                    value Randomness. Defaults to false.
     <randomness>   Varies the randomness of Life between 0.0(0%) and 1.0(100%). Defaults to 0.5 (50%).
     <slaved>       If true the Submodel is slaved to its parent model on release. For a subsequent release 
                    the property "controls/slave-to-ac" must be set to false.

Step 2: adding the submodel to your model

This is very simple. First, add these lines to your model ~-set.xml file within the <sim></sim> tag:

  <submodels>
    <serviceable type="bool">true</serviceable>
    <path>Aircraft/seahawk/Models/seahawk-submodels3.xml</path>
  </submodels>

Where <path> is the path to the file you created at Step 1 above. If you want to add submodels to an AI Object, add the same lines within the <scenario></scenario> tag in the scenario file which instantiates the AI Object.

Step 3: controlling the submodel

There is no built-in way of setting/toggling the trigger property so you will need to add some mechanism to do this. A suitable key binding might be:

 <key n="10">
   <name>Ctrl-J</name>
   <desc>Jettison Port and Stbd Pylon Stores.</desc>
   <binding>
     <command>property-assign</command>
     <property>controls/armament/station[0]/jettison-all</property>
     <value type="bool">1</value>
   </binding>
   <binding>
     <command>property-assign</command>
     <property>controls/armament/station[1]/jettison-all</property>
     <value type="bool">1</value>
   </binding>
 </key>

Step 4: terminating the submodel

There are 3 ways to terminate your submodel:

1. Do nothing: the submodel will die when its life expires or its altitude <= -1000, whichever occurs first.
2. Instantiate a subsquent submodel: <submodel-path> contains the path to the file containing the submodel to be instantiated. Activated if one or more of <collision>, <impact>, or <expiry> are set to true.
3. Instantiate a static model: for this you will need a Nasal fuction:

 var droptank_node = props.globals.getNode("sim/ai/aircraft/impact/droptank",1);
                                  
 var droptanks = func(n) {
   var droptank = droptank_node.getValue();
   var node = props.globals.getNode(n.getValue(), 1);
   geo.put_model("Aircraft/seahawk/Models/droptank-hot.xml",
               node.getNode("impact/latitude-deg").getValue(),
               node.getNode("impact/longitude-deg").getValue(),
               node.getNode("impact/elevation-m").getValue()+ 0.25, #+0.25 to ensure the droptank isn't buried
               node.getNode("impact/heading-deg").getValue(),
               0,
               0
               );
 }
 
 setlistener("sim/ai/aircraft/impact/droptank", droptanks);

The path sim/ai/aircraft/impact/droptank is the one you specified in the tag <submodel-path>. Options 2 and 3 are NOT mutually exclusive. Thus you can both instantiate a static model AND instantiate a subsequent submodel. As above, this is activated if one or more of <collision>, <impact>, or <expiry> are set to true.

Technical stuff

1. Slaved Objects. Slaved objects follow exactly the movements of their parent object. They can be released, when they then become normal Ballistic objects. They are designed for use as underwing stores, such as droptanks, as they give a realistic appearance on release. On the other hand, there is a small framerate cost. Where the stores are carried in a bombbay, this technique is not required. Here, an acceptable appearance can be achieved by adding models of the stores in the bombbay which are hidden on instantiation of the submodel.
2. Formations. Wingmen are not AI Aircraft. In the interest of framerate they are in fact a sub-class of slaved objects, with added sinusoidal noise and some simple AI rules. They cannot be released to act independently. The formation can be changed by the use of a Nasal script. There is no collision detection or avoidance, so you must avoid flying the wingmen into each other during a formation change. Thare is a significant framerate cost involved. The wingmen can be as simple or complicated as you wish. The ones currently implemented tend to be fully detailed, and can be "ridden". This is uneccesary, but gives a fun viewpoint of the formation. In due course I will produce a Howto for Wingmen.
3. Multiplayer. Submodels, indeed all AI objects are not visible over MP. This is in part deliberate (to prevent people trying to shoot at airliners), and in part technical (due to lag on the network the submodels would be nowhere near their actual position). On the other hand, it would be nice to include wingmen and perhaps droptanks in the overall scene. At the moment I cannot come up with a design which works at acceptable framerate cost.