Differences

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

--- luafunctionref [2025/01/08 17:56] – bredroll
+++ luafunctionref [2025/05/05 07:05] (current) – [update] bredroll
@@ Line 1: / Line 1: @@
-====== CC2 Lua Functions ======
+====== CC2 Lua ======
 This is a (not exhaustive) reference for functions available to be called in the lua scripts used for screen rendering/interaction.
+CC2 has various lua scripts that directly drive what information you see on screens, in the control seat and ship cameras. They are the way players choose to refit units, set waypoints, see and identify threats.  There are broadly 3 kinds of files:
+  * screen
+    * draw the user interface for each bridge station
+  * hud
+    * draw the heads-up-display when in direct control of a unit
+  * library
+    * shared code usable in screens or hud scripting.
+===== Script Environment =====
+==== Loading ====
+Each screen on the carrier gets its own Lua interpreter instance. Setting globals at runtime in the script will not have any effect on other screens running the same script. The same is true of the HUD except there is only ever one instance if vehicle_hud.lua running on your PC.
+Scripts have the following load order:
+  * library_enum.lua
+  * library_util.lua
+  * library_vehicle.lua
+  * library_ui.lua
+  * library_custom_X.lua
+  * screen/hud
+==== Execution ====
+The whole of each file is evaluated in the same lua interpreter. If you set a global outside of a function in library_enum.lua then you will be able to see the value in library_util.lua and later.
+=== begin ===
+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.
+=== 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 ====
+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 7: / 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 21: / 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 89: / 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 107: / 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 1129: / Line 1207: @@
 Native/C function
+Return ''true'' if the game is running in VR mode.
 Usable in:
@@ Line 1186: / 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 1229: / Line 1315: @@
 Native/C function
+Get the ID of the current player.
 Usable in:
@@ Line 1242: / Line 1330: @@
 Native/C function
+Get the team ID of the current player.
 Usable in:
@@ Line 1256: / 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 1275: / 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 1288: / Line 1395: @@
 Native/C function
+Get the number of destroyed vehicles visible on the game map.
 Usable in:
@@ Line 1301: / 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: