User:D-ECHO/Towing

Implement towing capability for your aircraft

The Nasal Towing system is enabled whenever the aircraft used defines the property /sim/hitches.

Glider Aircraft

YASim aircraft support towing via its own code, in order to enable towing for JSBSim aircraft, you need to do the following:

In your JSBSim file, inside the <external_reactions> block, add the aircraft's hitch position(s) as <force>s:

<force name="hitch" frame="BODY" unit="LBS" >
   <location unit="M">
      <x> 3.65</x>
      <y> 0.0 </y>
      <z>-0.12</z>
   </location>
   <direction>
      <x>0.0</x>
      <y>0.0</y>
      <z>0.0</z>
   </direction>
</force>

You may add only one hitch for both aerotow and winch tow or separate forces. If you use two separate force blocks, it's good practice to use descriptive names, e.g. "hitch-aerotow" and "hitch-winch" or "hitch-nose" and "hitch-cog" (COG = Center of Gravity). Next, add keybindings to control the winch or aerotow to your aircraft. You can either define the keys yourself or (recommended) include the common hitch keybinding file Aircraft/Generic/hitch-keybindings.xml into your aircraft:

	<input>
		<keyboard include="Aircraft/Generic/hitch-keyboard.xml" />
	</input>

Afterwards, add these properties to your aircraft's -set.xml:

<sim>
	<hitches>
		<aerotow>
			<force_name_jsbsim type="string">hitch</force_name_jsbsim>
			<tow>
				<break-force type="float">6000</break-force> <!-- weak link, Newton -->
			</tow>
		</aerotow>
		<winch>
			<force_name_jsbsim type="string">hitch</force_name_jsbsim>
			<automatic-release-angle-deg type="float">70.</automatic-release-angle-deg>
			<typical-tow-speed-kph type="float">100</typical-tow-speed-kph>
			<typical-tow-force-N type="float">5000</typical-tow-force-N>
			<tow>
				<break-force type="float">10000</break-force> <!-- weak link, Newton -->
			</tow>
		</winch>
	</hitches>
<sim>

By default, hitch.nas uses the location defined in the JSBSim force in the beginning for the visual tow rope. If you want to use a different location for the visual representation, add the following to the <aerotow> and/or <winch> part:

     <decoupled-force-and-rope-locations type="bool">true</decoupled-force-and-rope-locations>
     <local-pos-x type="float"> 0.0 </local-pos-x> <!-- meter, positive X is towards the nose -->
     <local-pos-y type="float"> 0.0 </local-pos-y> <!-- meter, positive Y is to the left -->
     <local-pos-z type="float"> 0.0 </local-pos-z> <!-- meter, positive Z is up -->

Please note that the <local-pos-_> coordinate system is the one YASim commonly uses, so all coordinates need to be reversed from blender/animation/JSBSim coordinates.

Towing Aircraft

The process to add towing capabilities to your aircraft (tow via MP) is more or less similar to the one for the glider aircraft described above.

YASim aircraft support towing via its own code, in order to enable towing for JSBSim aircraft, you need to do the following:

In your JSBSim file, inside the <external_reactions> block, add the aircraft's hitch position (typically only one) as a <force>:

<force name="hitch" frame="BODY" unit="LBS" >
   <location unit="M">
      <x> 3.65</x>
      <y> 0.0 </y>
      <z>-0.12</z>
   </location>
   <direction>
      <x>0.0</x>
      <y>0.0</y>
      <z>0.0</z>
   </direction>
</force>

Next, add keybindings to control the towing to your aircraft. Since most of this is handled by the towed glider aircraft, you only need to implement opening the hook:

<input>
	<keyboard>
		<key n="111">
			<name>o</name>
			<desc>Open hook</desc>
			<binding>
				<command>property-assign</command>
				<property>/sim/hitches/hook-open</property>
				<value type="bool">true</value>
			</binding>
			<binding>
				<command>nasal</command>
				<script>
					towing.releaseHitch("aerotow");
				</script>
			</binding>
			<mod-up>
				<binding>
					<command>property-assign</command>
					<property>/sim/hitches/hook-open</property>
					<value type="bool">false</value>
				</binding>
			</mod-up>
		</key>
	</keyboard>
</input>

The properties to add to your -set.xml file are also reduced to only these:

<sim>
	<hitches>
		<aerotow>
                	<force_name_jsbsim type="string">hitch</force_name_jsbsim>
                	<force-is-calculated-by-other type="bool">true</force-is-calculated-by-other>
                	<mp-auto-connect-period type="float">0.5</mp-auto-connect-period>
		</aerotow>
	</hitches>
</sim>