API QuickRef

This section shows a summary of the API calls and example use of each API call.

---

API Summary List

--  Global Vars
•   SIM_PERIOD
•   IN_REPLAY   

--  Datarefs
•   create_dataref      ("string",  "type") 
•   create_dataref      ("string",  "type",     callback_f())
•   find_dataref        ("string")

--  Commands
•   wrap_command        ("string",  bhandler,   ahandler)
•   augment_command     ("string",  handler)
•   create_command      ("string",  "description",      ccb_handler(phase, duration))
•   filter_command      ("string",  xcmd_filter())
•   command:once()
•   command:start()
•   command:stop()

--  Timers
•   run_at_interval     (func(),    interval_s)
•   run_after_time      (func(),    delay_s)
•   run_timer           (func(),    delay_s,        interval_s)
•   stop_timer          (func)
•   is_timer_scheduled  (func)
•   get_timer_remaining (func)

--  Calbacks and Events
•   aircraft_load()
•   aircraft_unload()
•   flight_start()
•   flight_crash()
•   before_physics()
•   after_physics()
•   after_replay()

--  Directives
•   XLuaReloadOnFlightChange()

---

Datarefs

Create a Custom (Read Only) Dataref

cdr_your_var_name   =   create_dataref( "your/dataref/string/name",      "type")    -- type = "number"  OR "string"

Create a Custom Write Dataref

--  Write Callback Handler Definition
function    cdr_myCustomDataref_handler()   
    -- dostuff
end 

--  Create Write Dataref
cdr_myCustomDataref     =   create_dataref( "custom/dr/name",   "type",     cdr_myCustomDataref_handler)    -- "type" = "number" or "string"

Accessing X-Plane Datarefs

--  Non Array Datarefs --
xdr_xpDataref           =   find_dataref( "sim/xplane/dataref")

--  Array type datarefs --
xdr_bus_volts           =   find_dataref("sim/cockpit2/electrical/bus_volts")

print(xdr_bus_volts[0])
print(xdr_bus_volts[1])
print(xdr_bus_volts[3]) 

OR

xdr_bus_volts_0         =   find_dataref("sim/cockpit2/electrical/bus_volts[0]")
xdr_bus_volts_1         =   find_dataref("sim/cockpit2/electrical/bus_volts[1]")

---

Commands

• Command Callback Format

function    ccb_commandcallback_handler(phase,  duration)

--  Using the 'phase' parameter
    if      phase   ==  0   then    --  command begin.  this block will run 1 time only at command invocation 

    elseif  phase   ==  1   then    --  command holding.  This block runs continuously during command execution  

    elseif  phase   ==  2   then    --  command stop.   This block runs 1 time only on command stop (button up)

--  Using the 'duration' parameter
    if duration > 3 then
        print("command has been executing for 3 seconds at least")
    end

end --  of commandcallback

• Augment X-Plane Command

function    xccb_xpcommand_bhandler(phase,  duration)   dostuff     end     --'before' xplane handler function
function    xccb_xpcommand_ahandler(phase,  duration)   dostuff     end     --'after' xplane handler function

xcmd_xpcommand  =   wrap_command("sim/xplane/command",  xccb_xpcommand_bhandler,    xccb_xpcommand_ahandler)

-- NOTE:  before/after handler functions take no arguments. 

• Replace X-Plane Command

function    xccb_xp_command_handler(phase,  duration)   dostuff     end     --  Command Callback function Def

xcmd_xpcommand  =   replace_command("sim/xplane/command",   xccb_xp_command_handler)

• Filter X-Plane Command

function    xccb_xp_command_fhandler()   -- NO arguments for the filter handler
    if  xp_ok_to_run    then
        return true             -- return true to allow XP to execute its command code
    else
        return false
    end
end     --  Command Callback function Def

xcmd_xpcommand  =   filter_command("sim/xplane/command",    xccb_xp_command_fhandler)   

• Create Custom Command

function    ccb_myCommand_handler(phase,    duration)       
    --  dostuff
end

ccmd_myCommand  =   create_command("custom/command/name",       ccb_myCommand_handler)

• Command Execution Methods

ccr_command_name:once()     --  runs command exactly one time
ccr_command_name:start()    --  starts a command
ccr_command_name:stop()     --  stops a command

---

Timers

run_at_interval(func_name,  interval)  

run_after_time(func_name,   delay)          

run_timer(func_name,    delay,  interval)   

stop_timer(func_name)   

is_timer_scheduled(func_name)

get_timer_remaining( func_name )

---

Directives

XLuaReloadOnFlightChange()   -- place once, anywhere in your Lua code to reload scripts on flight change.

---

Major Callbacks

function    aircraft_load()
    --  runs one time.  set overrides, set acf prefs
end 

function    aircraft_unload()
    --  runs once.  clean up after yourself, save prefs, etc.
end

function    flight_start()
    --  runs once.  initialize state as required
end

function    flight_crash()
    runs once on crash.  do whatever you can think of
end

function    before_physics()
    --  runs continuous when NOT in pause.  Does NOT run when paused.
end

function    after_physics()
    --  runs continuous when NOT in pause.  Does NOT run when paused.
end

function    after_replay()
    -- 
end 

Global Variables

SIM_PERIOD  -- Duration of the current frame, in seconds (always a fraction). (1/SIM_PERIOD yields FPS).  Non-zero, even during pause.

IN_REPLAY   -- Evaluates to 0 if replay is off, 1 if replay mode is on.