Difference between revisions of "KellyFuel/Creator Instructions"

From
Jump to: navigation, search
(Fuel Taint)
(Chat Commands)
Line 3: Line 3:
 
== Chat Commands ==
 
== Chat Commands ==
  
This section describes the basic commands sent by the pump and the expected replies from the aircraft.  All communication is on your configured channel.  Aircraft creators may optionally choose to open the chat listener for fuel only then the fuel cap on their aircraft is removed to limit the number of open channels.
+
This section describes the basic commands sent by the pump and the expected replies from the aircraft.  All communication is on your configured channel.  Aircraft creators may optionally choose to open the chat listener for fuel only then the fuel cap on their aircraft is removed to limit the number of open channels.  The pump uses <tt>llRegionSayTo</tt> to send commands to a specific aircraft.  It is recommended that the aircraft also reply using <tt>llRegionSayTo</tt> to the object from which it received the request.
  
 
=== Aircraft Tank Query ===
 
=== Aircraft Tank Query ===

Revision as of 01:06, 27 August 2022

This section is intended for aircraft creators who wish to use KellyFuel in their build. KellyFuel operates over a channel to send and receive commands to your helicopter. You can configure a private channel to use for this purpose. KellyFuel identifies the aircraft being refueled by checking the creator name and the object name against a database. Since users often rename the aircraft, partial matching is used on the object name looking for specific key parts of the name. As a creator, you can edit the object name matching criteria for your aircraft on the SA website.

1 Chat Commands

This section describes the basic commands sent by the pump and the expected replies from the aircraft. All communication is on your configured channel. Aircraft creators may optionally choose to open the chat listener for fuel only then the fuel cap on their aircraft is removed to limit the number of open channels. The pump uses llRegionSayTo to send commands to a specific aircraft. It is recommended that the aircraft also reply using llRegionSayTo to the object from which it received the request.

1.1 Aircraft Tank Query

Pump: @refuel check
Aircraft: @ack 2 check cur-level max-level tank-name

This command is used to query which tanks on an aircraft are ready for fueling. In the aircraft response, "2" is the protocol-number, cur-level is the current number of gallons in a tank, max-level is the maximum number of gallons in the tank, and tank-name is the name of the tank. If the aircraft has only one tank, the name "main" should be used for the tank. If the aircraft has multiple tanks, an "@ack" command should be sent for each tank.

1.2 Fuel Level Query

Pump: @refuel look name
Aircraft: @ack look cur-level max-level tank-name taint-status

This command is used to "look" into a tank. It is similar to the "check" command except that it includes a specific tank name in the query. The response elements are the same as the "check" command but includes and additional taint-status value. The taint status should be 0 if fuel in that tank is clean, and 1 if it is tainted. See the discussion on the "add" command for information on fuel tainting.

1.3 Fill Tank to Full

Pump: @refuel full
Aircraft: @ack full

This command requests that all tanks be completely filled. This command is sent when a user chooses "Auto Fill" from the menu bypassing the normal RP elements.

1.4 Add Fuel to Tank

Pump: @refuel add tank-name amount type
Aircraft: @ack add amount actual

This command incrementally adds fuel to a tank. The query specifies the name of the tank, the number of gallons to add, and a fuel type. Note the fuel type may be omitted by pumps prior to Version 3.0. The fuel type can be one of:

  • 100ll - Aviation fuel used by piston aircraft
  • jeta - Fuel for most jet and turbo-prop aircraft
  • fueloil - Fuel used by certain vintage/steampunk aircraft

The aircraft response should include the amount requested to be added, and the actual amount added to the tank. If the amount requested to be added is more than the remaining capacity of the tank, the actual value should be the remaining capacity. If the tank is full, 0 should be returned for actual. It is important to return accurate values as detecting when actual is less than requested is how the pump detected when fueling is complete.

Example: The left fuel tank (named "left") in your Cessna 172 holds a maximum of 21.5 gallons, and currently contains 18 gallons of fuel. The following would be the expected exchange between the pumps and the aircraft:

Pump: @refuel add left 10 100ll Aircraft: @ack add 10 3.5

The pump command requests to add 10 gallons of 100ll fuel to the left tank. The reply from the aircraft acknowledge 10 gallons was requested, but only 3.5 gallons could be added to the tank (the remaining capacity of the tank).

1.4.1 Fuel Taint

The fuel-type parameter of the add query can optionally be used to implement handling of misfueling in your aircraft. If your aircraft has a piston (jet) engine and you receive an add query with a fuel type other 100ll (jeta), then you can mark an internal flag in your aircraft to indicate the fuel is tainted. You are free to implement any symptoms of misfueling you choose including failure to start, or failure of engine after a time interval (in RL, engine failure from misfueling often occurs after takeoff once all the clean fuel in the fuel lines have been consumed). You are also free to implement a method of clearing the taint flag (e.g., by draining the tank).