diff --git a/docs/docs/lua-api.md b/docs/docs/lua-api.md index a02dab2..51957cf 100755 --- a/docs/docs/lua-api.md +++ b/docs/docs/lua-api.md @@ -1,34 +1,112 @@ ## General Template Script looks like this: ``` ----- +--- +-- return: none +-- +function init_proc() + +end + +--- -- arguments: in_value: "State Key" value --- value_idx: multi-value index +-- value_idx: multi-value index (0 - based) --- -- return: first(number): final value --- second(boolean): value is updated or not --- +-- second(boolean): value is valid or not +--- function value_proc(in_value, value_idx) local value = in_value return value, true end + +--- +-- arguments: in_value: number +-- value_idx: multi-value index (0 - based) +--- +-- return: string +--- +-- function value_str_proc(in_value, value_idx) +-- local str = string.format("%.2f", in_value) +-- +-- return str +-- end ``` -The `value_proc` function will be called for every available value index (up to 8). +The pipeline looks like this: +**"State value"** -> **value_proc** -> **value_str_proc** + +The script file runs in a **sandboxed environment**, that includes a few standard libs: +** +``` +math +string +table +``` +** + +With some functions from the `base` library: +** +``` +assert +error +ipairs +pairs +next +select +tonumber +tostring +type +pcall +xpcall +``` +** + +Each script can contain the following callback functions: + +| Key                                                 | Description | +| :--- | --- | +|`init_proc()` | called once at a new Vehicle or when Script Options has been changed.| +|`value_proc(state_value, value_idx)` | called at every update, for each available value index (up to 8).| +|`value_str_proc(value, precision)` | called at every update, number -> string.| !!! warning If the script fails, it will be silently kicked, and the value will be `N/A`. Check the `Logs/WTRTI.log` file for error messages. + ## Functions -#### getStateValue(state_key_str) +#### getStateValue(state_key_str [, default_value]) Returns the state value, otherwise a `nil` if the key not found. -> **Note:** Press **F2** in the main window to display the State window. +or +Returns `default_value` if specified. +> **Note:** Press **F2** in the main window to display the "State" window. + +__Usage:__ + +``` +local rpm = getStateValue("RPM 1") +if rpm then + -- code +end +``` +**or** + +`local rpm = getStateValue("RPM 1", 0)` + + +#### setStateValue(state_key_str, value) +Allows you to emplace the value into the "State" list. + +Returns `true` if the state value has been emplaced, `false` if not. + +> **Note:** Only non-existent keys are allowed to be emplaced. +> **Note:** The key lifetime is only one frame (update). __Usage:__ -`local rpm = getStateValue("RPM 1")` +`setStateValue("new_key", 3.14)` #### getVehicleData(veh_key_str) Returns values from FM database. @@ -50,7 +128,7 @@ __Usage:__ | `crit_takeoff_flaps_spd` | number, returns Critical Takeoff Flaps Speed, km/h. | | `crit_landing_flaps_spd` | number, returns Critical Landing Flaps Speed, km/h. | | `crit_flaps_spd` | array of numbers, returns Critical Flaps Speed, km/h.
`[ pos1, spd1, pos2, spd2, ... ]` | -| `crit_gear_spd` | number, returns Critical Gear Speed, km/h. | +| `crit_gear_spd` | number, returns Critical Landing Gear Speed, km/h. | | `combat_flaps_pos` | number [0, 1], Combat flaps position. | | `takeoff_flaps_pos` | number [0, 1], Takeoff flaps position. | | `num_engines` | number, Number of Engines. | @@ -68,3 +146,87 @@ Returns the current update time in seconds. #### getTime() Returns the current time in seconds from the start of the application. + +## Script Options +Allows you to specify additional options for the custom indicator that will be displayed on the Script tab (GUI). +In the script, declare a global table `__OPTIONS`, example: + +``` +__OPTIONS = { + { + key = "option_key", -- key to get/set value in the script + name = "Sample Option", -- name in GUI + type = "boolean", -- type of the option + value = true -- default value + }, + { + key = "combo_option__key", + name = "Sample Combo", + type = "combo", + options = { "red", "blue", "green" } + value = 2, -- default selected option (green) + }, +} +``` + +**Note:** When you set the options in GUI and click on the OK/Apply button the `init_proc` function will be called. +**Note:** On the script "Hot-Reload" (F9), these options will be reseted to defaults. + + +### Types +| Type | Value | +| :--- | --- | +| boolean | true, false | +| integer | any natural number | +| float | real number | +| string | string | +| radio | integer, index of the `options`, begins from 0 | +| combo | integer, index of the `options`, begins from 0 | +| hotkey | none | + +### Groups +You can make a group of the options, simply add a name key to the table right before the options. + +``` +__OPTIONS = { + name = "Group1" + { + key = "option_key", + name = "Sample Option", + type = "boolean", + value = true + }, + { + name = "Group2" -- group inside of the Group1 + { + key = "option_key_2", + name = "Sample Option 2", + type = "boolean", + value = true + }, + { + key = "option_key_3", + name = "Sample Option 3", + type = "boolean", + value = false + } + } +} +``` +Maximum level of group depth is 2. + +#### getOptionValue(key_str [, default_value]) +Returns the option value. +__Usage:__ +`local opt1 = getOptionValue("option_key")` + +or with default value: + +`local opt1 = getOptionValue("option_key", "Default String")` + +#### setOptionValue(key_str, value) +Allows to set a value for the option. +__Usage:__ +`setOptionValue("option_key", "New String")` + +**Note:** Only initial type of the value is allowed to set.