XLuaUtils for X-Plane 11/12

XLuaUtils is a collection of scripts and utilities for X-Plane's XLua plugin, implemented as a companion script. XLuaUtils extends XLua's capabilities for demonstrating interaction with X-Plane's C API by means of LuaJIT's Foreign Function Interface (FFI).
It can be installed and used in any X-Plane 11/12 aircraft

It also implements wrappers for some paths, logging, notifications, dataref interaction and debug information, which can help aircraft developers during development of XLua scripts.

The persistence and noise-cancelling headset modules, as well as some miscellaneous utilities are aimed at end users who seek to get more out of an aircraft.

 

Table of Contents

1. Requirements
2. Installation
3. Uninstallation
4. Developer Reference
5. End-User Utilities
   5.1 Initialization/Main Menu
   5.2 Persistence
   5.3 Noise-Cancelling Headset
   5.4 Miscellaneous Utilities
   5.5 Automixture Controls
   5.6 Attach Objects
   5.7 Engine Damage
   5.8 Oxygen System
   5.9 Stick Trim
6. License

 

1 - Requirements

• X-Plane (11 or 12)
• XLua (1.0 or higher; only works locally on a single aircraft)

 

Back to table of contents

 

2 - Installation

2.1 Aircraft without an XLua plugin

• Copy the "xlua" folder from, e.g. "[Main X-Plane folder]/Aircraft/Laminar Research/Cessna 172SP/plugins" into the "plugins" folder of the aircraft that you wish to use XLuaUtils with.
• Delete all subfolders from the "[Aircraft's main folder]/plugins/xlua/scripts" folder.
• Copy the "xluautils" folder into "[Aircraft's main folder]/plugins/xlua/scripts"

2.2 Aircraft with an XLua plugin

• Copy the "xluautils" folder into "[Aircraft's main folder]/plugins/xlua/scripts"

2.3 Post-Installation

XLuaUtils is working correctly if X-Plane's main menu bar contains a menu with the aircraft's name and an "XLuaUtils" submenu (see chapter 5.1).

If you have no intention of using XLuaUtils for development purposes, consult section 5 of this readme to learn about the end-user oriented tools. A quick read of section 4 is recommended regardless, because some information there may come in handy at some point.

 

Back to table of contents

 

3 - Uninstallation

Delete the "xluautils" folder from "[Aircraft's main folder]/plugins/xlua/scripts/"

 

Back to table of contents

 

4 - Developer Reference

XLuaUtils provides a range of useful functions for XLua developers to help debug code or implement utilities.
See the Documentation/Developer_Reference.md document for more information.

 

Back to table of contents

 

5 - End-User Utilities

5.1 Initialization/Main Menu

After a successful installation, the main X-Plane menu bar contains a menu with the aircraft's name with a "XLuaUtils" submenu.

• "Initialize XLuaUtils" will generate a preferences.cfg file containing the initial values of any submodule making use of XLuaUtils' preferences system (see Documentation/Developer_Reference.md, section 4).
  Note that some XLuaUtils elements or submodules do not initially save their state and will require changing their settings before they will do so.
  "Reload XLuaUtils Preferences" will replace "Initialize XLuaUtils" as a menu entry if a "preferences.cfg" file was created during initialization or if the file has been detected at startup. Clicking will read the current values from "preferences.cfg".
  Use this function to reload preferences values that have been altered via manual edit of the file.

• The "Debug" submenu is always visible and contains controls for debug-level logging (see Documentation/Developer_Reference.md, section 3) and the debug window (Documentation/Developer_Reference.md, section 7).

 

5.2 Persistence

XLuaUtils' persistence module parses a list of datarefs at startup, whose values are either manually or automatically written to a persistence state file. This state file is then parsed at X-Plane session initialization and the values are written back to these datarefs. The module only works for the aircraft running XLuaUtils (i.e. the currently active user aircraft).

See Documentation/Persistence.md for more information.

 

Back to table of contents

 

5.3 Noise-Cancelling Headset

XLua Util's noise-cancelling headset module provides a customizable one-size-fits all solution to loud engines. It decreases engine, environment, exterior, fan, ground, interior, prop, warning and weather volume levels, while retaining the sound level of the co-pilot, master slider, radio and ui. The headset will only affect volume levels when inside a sound space (properly set up fmod soundsets) or in an interior view (fallback mode).

See Documentation/NCHeadset.md for more information.

 

Back to table of contents

 

5.4 Miscellaneous Utilities

Various smaller utilities.

See Documentation/Misc_Utils.md for more information.

 

Back to table of contents

 

5.5 Automixture Controls

As of version 12.00, X-Plane does not support complex automatic mixture controllers as found, for example on Pratt & Whitney R-1830 type engines of Douglas DC-3s and C-47s. These automatic controllers, in their "Auto Lean" and "Auto Rich" modes, automatically set the fuel mixture based on altitude to attain a specific air-fuel-ratio, easing crew workload and ensure maximum power or fuel saving.

XLuaUtils has an automixture utility modeled after the R-1830's mixture controller with the following modes:

• Manual: Manual mixture control
• Idle Cutoff: Turns off the engine(s)
• Auto Lean: Lean mixture (default air-fuel-ratio: 16.5) for fuel economy during cruise
• Auto Rich: Rich mixture (default air-fuel-ratio: 12.5) for maximum power for takeoff
• Full Rich: Maximum fuel consumption, but the excess fuel provides cylinder head cooling for situations with maximum power demands

While X-Plane (12) offers a FADEC-based automixture control for reciprocating engines, the controller only offers a "maximum power" target, i.e. "Auto Rich" mode. Therefore, I felt it was necessary to code a custom solution.

To offer seamless integration into aircraft models, the utility comes with a built-in capability to modify object files, primarily in order to implement detents for mixture levers. This offers a possibility for realistic in-cockpit operations without having to resort to an external menu.

See Documentation/Automixture.md for more information.

 

Back to table of contents

 

5.6 Attach Objects

The object attachment utility can be used to display objects loaded from object files outside the aircraft.
These objects can be set to display within a certain dataref value range and will either move with the aircraft (e.g. external loads) or stick to the ground (e.g. ground equipment).
Object definition is provided from a simple text-based input file and objects can be reloaded at any time.

See Documentation/Attach_Objects.md for more information.

 

Back to table of contents

 

5.7 Engine Damage

The engine damage utility will add consequences to exceeding operational limitations.
These limitations depend on engine type (e.g. torque and CHT for props, ITT and EGT for jets, etc.) and are either derived from the aircraft's ACF file or by user-specific thresholds.

See Documentation/Engine_Damage.md for more information.

 

Back to table of contents

 

5.8 Oxygen System

Provides a supplemental oxygen system (or an override for a present oxygen system) without having to edit an aircraft's PlaneMaker model.
Has an automation mode and provides warnings about pilot hypoxia.

See Documentation/Oxygen_System.md for more information.

 

Back to table of contents

 

5.9 Stick Trim

Allows trimming ailerons, elevators and optionally rudders (or cyclic and pedals in helicopters) with stick/yoke and rudder input.

See Documentation/Stick_Trim.md for more information.

 

Back to table of contents

 

6 - License

XLuaUtils is licensed under the European Union Public License v1.2 (see EUPL-1.2-license.txt). Compatible licenses (e.g. GPLv3) are listed in the section "Appendix" in the license file.

Back to table of contents