Persistence.md

XLuaUtils persistence utility

This document contains information about XLuaUtils' persistence utility.

Back to Readme.md

 

Table of Contents

1. Caveats/Known Issues
2. Files
3. Populating Persistence_datarefs.cfg
4. Menu/Functionality
5. Configuration via Preferences.cfg

 

1. Caveats/Known Issues

The persistence system comes with the following caveats:

• Datarefs that are present in X-Plane 11 may not be present in X-Plane 12. As missing datarefs are discarded during persistence module initialization, they will not be saved later on.
• Engine-related datarefs are hard to initialize, so it's best to disregard in-flight situations as initialization with running engines will most likely not work. The persistence module was made primarily ground-based state saving between X-Plane sessions.
• Custom datarefs created by third party aircraft must be writable in order to be used by the persistence module. If a third-party aircraft uses XLua or SASL to drive its systems, it may be that its custom datarefs are not initialized with a handler which would make them writable (if a custom dataref can be edited with DataRefTool, it is writable).
  For XLua, "xluautils/Config Files/Persistence/OliXSim L-18 1.1" provides a workaround in form of a modified "init.lua" file for XLua 1.0, in which the "create_dataref" function will initialize any custom dataref as writable.
  There is no such thing for SASL driven aircraft, so users may be out of luck in the worst case.
• Despite all the care taken in finding the correct datarefs and putting them into a sensible order, it may be that some third party aircraft simply do not react too well toward third party tools trying to write to their datarefs.
  In general, the simpler the add-on, the higher the chance of success for a 100% correct initialization.
• FMS and GPS flight plans and configurations are not supported unless they are stored within datarefs.
• There is no way to restore dataref values from the start of the X-Plane session prior to persistence file reading, so the only solution to a messed up persistence save file is deleting "persistence_save.txt", disabling persistence auto-loading and restarting X-Plane or changing to another aircraft and back and start over.

 

Back to table of contents

 

2. Files

Relevant files to this module are stored in "xluautils" and are "preferences.cfg", storing configuration data, "persistence_datarefs.cfg", a manually populated list of datarefs and "persistence_save.txt", the save file containing the dataref values.

 

Back to table of contents

 

3. Populating Persistence_Datarefs.cfg

An empty "Persistence_datarefs.cfg" is generated at XLuaUtils initialization (see chapter 5.1 if none is present.

• "Persistence_datarefs.cfg" is a regular text file and can be opened with any text editor like Notepad (apps like MS Word are not recommended though).
• The header section of "persistence_datarefs.cfg" contains information on how to find datarefs used by the current aircraft.
• The best techniques for finding datarefs used by the aircraft are using DataRefTool to filter datarefs that recently changed due to user input, analysing cockpit related .obj files in the "objects" folder of the aircraft and finding relevant datarefs in the "...cockpit.obj" file in the aircraft's root folder by searching for a switch's tool tip.
• Custom datarefs created by third party add-ons are supported.
• Invalid datarefs that can not be found in X-Plane are discarded during the initial parsing of "persistence_datarefs.cfg" and will not be used, so there is minimal risk of crashing X-Plane.
• Only the name of the dataref is required, even if it is an array.
• Commands are not supported. This should be kept in mind when analyzing "...cockpit.obj" files.
• There is no limit to the number of datarefs in "persistence_datarefs.cfg".
• Comments are denoted with a hash sign ("#") at the beginning of a line.
• Dataref order may matter if the aircraft's systems logic dictates one.

Example "persistence_datarefs.cfg" files for some add-on aircraft can be found in "xluautils/Config Files/Persistence". These may be used as a starting point or template. Contributions are welcome.

 

Back to table of contents

 

4. Menu/Functionality

The "Persistence" sub-menu is available when a "persistence.cfg" file was found during XLuaUtils' initialization.

• "Save Cockpit State Now"
  Saves the tracked datarefs' values to "xluautils/persistence_save.txt"
• "Load Cockpit State Now"
  Loads the tracked datarefs' values from "xluautils/persistence_save.txt"
• "[On/Off] Cockpit State Autosave"
  Toggles the timed autosave feature on/off.
  The first autosave is performed after a certain delay to avoid conflicts with other XLuaUtils file access functions.
  After the first autosave, a timer is started that will save the persistence state in a specific interval.
  See below for adjustment of the initial autosave delay and autosave interval.
• "[On/Off] Cockpit State Autoload"
  Toggles the autoload feature on/off.
  Autoloading of persistence data from "persistence_save.txt" is started during X-Plane's "flight_start" event during aircraft initialization.
  To avoid conflicts with custom systems logic from other scripts or plugins, autoload is performed after a certain delay, which may be configured in "preferences.cfg" (see below).
• "[On/Off] Save On Exit"
  Triggers a persistence save operation during X-Plane's "aircraft_unload" event, e.g. when shutting down X-Plane or changing aircraft.
• "Increment Autosave Interval (+ n s)"
  Increments the autosave interval by a certain amount of time which may be adjusted in "preferences.cfg" (see below).
• "Autosave Interval: n s"
  This only displays the current autosave interval and does not constitute an interactive element.
• "Decrement Autosave Interval (- n s)"
  Decrements the autosave interval by a certain amount of time which can be adjusted in "preferences.cfg" (see below).
• "Reload Config & Dataref File (Drefs: n)"
  Reads persistence module related data from "preferences.cfg", parses "persistence_datarefs.cfg" and then reads the current values of all tracked datarefs. The menu entry will display the amount of currently tracked datarefs.

 

Back to table of contents

 

5. Configuration via Preferences.cfg

These are the persistence module parameters which are stored in lines prefixed with "PERSISTENCE" in "preferences.cfg":

• Autoload:string,0:number
  Autoload disabled/enabled (0/1; default: 0)

• AutoloadDelay:string,5:number
  Autoload delay (in seconds; default: 5)

• Autosave:string,0:number
  Autosave disabled/enabled (0/1; default: 0)

• AutosaveInterval:string,30:number
  Autosave interval (in seconds; default: 30)

• AutosaveIntervalDelta:string,15:number
  Increment/decrement for the autosave interval adjustment (in seconds; default: 15)

• AutosaveDelay:string,10:number
  Delay before first autosave (in seconds; default: 10)

• SaveOnExit:string,0:number
  Save on aircraft unload disabled/enabled (0/1; default: 0)

When altering these parameters, only adjust the numbers and nothing else.
Changes to "preferences.cfg" can be applied immediately with the "Reload Config & Dataref File" function from the "Persistence" menu or the "Reload XLuaUtils Preferences" from the "XLuaUtils" menu.

 

Back to table of contents