Differences

This shows you the differences between two versions of the page.

--- luafunctionref [2025/01/08 20:12] – bredroll
+++ luafunctionref [2025/05/05 07:05] (current) – [update] bredroll
@@ Line 35: / Line 35: @@
 Once this is complete, the game will call the ''begin()'' function (if it is defined).  For screen scripts, during the ''begin()'' call you will be able to call ''begin_get_ui_region_index()'' and ''begin_get_screen_name()''. You will not generally be able to call any of the other ''update_'' native functions.
-=== input ===
+=== game ===
+Now that the script is loaded and begin has been called, the input and update functions will be called. These are called once per "refresh_interval" (see ''<screen>'' tags in game object XML files).  For the HUD the ''update()'' function is called every game tick (30 times per second).
+When a player is using the HUD, the update rate of other scripts is reduced to once every 30 ticks (1 time per second), and the input functions are not called. The HUD update function is only called when a player is in the HUD view.
+==== input ====
 During the input cycle, the core game makes calls to the ''input'' functions, these are used to send in text, mouse and controller inputs into the script.
-=== update ===
+==== update ====
 Next is the update cycle, most of the heavy lifting goes on in here, these are where you can introspect the current vehicle, carrier details, weapons, map, nearby units, other players, missiles, etc. graphical/text drawing calls are made from here to draw the various icons and UI elements.
+=== Refresh Rate ===
+I have recently discovered there is another factor that influences how often a script ''update()'' function is called.  The further away from the screen your character is, the larger the update interval. If you leave the bridge and walk down to the flight deck, by the time you get there the bridge screens will update at most only once every two seconds.
 ==== Functions ======
@@ Line 49: / Line 60: @@
 Native/C function
+Can be called only during the ''begin()'' call cycle.
+Returns the name value of the currently executing screen. This is the value set in ''<screen>'' in the game object XML file for the carrier (or any other unit you attach a screen to). eg:
+<code>
+<screen name="screen_veh_r"
+   display_name_loc="680"
+   script_file_name="scripts/screen_vehicle_control.lua"
+   body_index="0"
+   seat_index="0"
+   type="3"
+   refresh_interval="1.00000000e+00"
+    help_tag="veh_con_screen_vehicle_control">
+</code>
+If called within a ''begin()'' function in ''screen_vehicle_control.lua'', ''begin_get_screen_name()'' would return "screen_veh_r" for this instance of the screen.
 Usable in:
-  * screen_inventory.lua
+  * screen_*.lua
-  * screen_navigation.lua
 Example call:
@@ Line 63: / Line 91: @@
 Native/C function
+Can be called only during the ''begin()'' call cycle.
+Return the index number for a specific UI icon image.  This is only really used as a shortcut to memoize icon indices in ''library_util.lua'' to create the ''atlas_icons'' table (which is easier and probably faster to work with than calling this function).
 Usable in:
@@ Line 131: / Line 163: @@
 Lua defined function in library_vehicle.lua
+Called early in ''begin()'' to memoize inventory item index values and cargo statistics like weight, abbreviations and costs.
 Usable in:
@@ Line 149: / Line 183: @@
 Lua defined function in interactions.lua
+Call to display the on-screen control hints in the bottom left of the screen.
 Usable in:
@@ Line 1171: / Line 1207: @@
 Native/C function
+Return ''true'' if the game is running in VR mode.
 Usable in:
@@ Line 1228: / Line 1266: @@
 Native/C function
+Return the localized string for the given index word/phrase from the ''e_loc'' enum table. Eg, in English, the following:
+<code>
+update_get_loc(e_loc.upp_paste)
+</code>
+Will return "paste".
 Usable in:
@@ Line 1271: / Line 1315: @@
 Native/C function
+Get the ID of the current player.
 Usable in:
@@ Line 1284: / Line 1330: @@
 Native/C function
+Get the team ID of the current player.
 Usable in:
@@ Line 1298: / Line 1346: @@
 Native/C function
+Get the logic tick. This is the game simulation counter starting at zero the moment the map is crated. It increments by one every simulation frame. The game is tuned such that a second of real time covers 30 game ticks.
+During the span of an ''update'' function call, the value of the current tick will remain the same.
+It can be thought of as a primitive low-res clock.
 Usable in:
@@ Line 1317: / Line 1371: @@
 Native/C function
+Get an object representing a recently destroyed vehicle. Used along with ''update_get_map_destroyed_vehicle_count()''.
+Destroyed vehicles have several methods.
+  * ''destroyed:get_position_xz()''
+    * get a ''vec3'' where ''vec3:x()'' is the x coordinate of the destroyed vehicle and ''vec3:y()'' is the z map coordinate of the vehicle (yes, y/z flip don't worry about it)
+  * ''destroyed:get_team()''
+    * get the team ID of the destroyed vehicle
+  * ''destroyed:get_factor()''
+    * get float in range 0-1 based on the age of destruction, where 1 is most recent and 0 is oldest.
 Usable in:
@@ Line 1330: / Line 1395: @@
 Native/C function
+Get the number of destroyed vehicles visible on the game map.
 Usable in:
@@ Line 1343: / Line 1410: @@
 Native/C function
+Get an object representing a player or AI controlled unit in game, the unit may be docked or active.
+The HUD can obtain 3D position (lat-lon-alt) information about a unit where the screen scripts can only obtain 2D (lat-lon). The HUD can also not see unit waypoints where as screens can fully get/set waypoint data.
+vehicle objects have many methods, the most commonly used are:
+  * ''vehicle:get()''
+    * locking/housekeeping, return ''true'' if this object can be used and is valid.
+  * ''vehicle:get_id()''
+    * get the vehicle ID number.
+  * ''vehicle:get_definition_index()''
+    * get the vehicle type (a value in the ''e_game_object_type'' table)
+  * ''vehicle:get_team()'' (screen only)
+    * get the vehicle team number
+  * ''vehicle:get_team_id()'' (HUD only)
+    * get the vehicle team number
+  * ''vehicle:get_position_xz()'' (screen only)
+    * get the vehicle 2D position as a ''vec2''
+  * ''vehicle:get_position()'' (HUD only)
+    * get the vehicle 3D position as a ''vec3'' where ''pos:y()'' is the altitude in meters.
 Usable in: