docs: Update lua-api

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.<br> `[ 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.