DEVBLOG: LUA IMPROVEMENTS AND CHANGES, PART 1

[NQ-Deckard]

 

We have been adding a lot of features to the Lua API following the additions of shields and core combat stress in addition to the docking and boarding changes. We have taken a lot of your feedback and suggestions into consideration and have made a few changes to improve some of the consistency and implementation of Lua.

These changes are minor; we can't rework the whole Lua API without breaking most of your scripts. 

With this in mind and to finalize the implementation of the Lua API associated with docking and future changes to other mechanics, we have decided to adjust a few parts that may be major for Lua creators, both for the addition of new features and the improvement and consistency of the API as a whole.

In this first part of a three-part devblog, we’ll cover the recent Lua changes and additions, including some related to docking and the deprecation of quaternions. 

 

You can read up on the other parts here: Part 2 & Part 3
 

CHANGES AND ADDITIONS
First, we have decided to rework the way the repositories associated with constructs and elements are managed.

Previously, some functions returning position or orientation information referred to the center or even a corner of the construct, others to the position of the core unit in the construct.

Going forward we have standardized everything. Once these changes go live, all functions will be based on the reference frame of the construct whose origin is the center of the build zone. Further, in order to guarantee the functionality of the flight systems and to safeguard the gyro unit, we have integrated in a clearer way of representing orientation.

An orientation unit is an element that is used to define the orientation of your construct. There are two orientation units in the game, the core unit and the gyro unit. As a construct cannot exist without a unique core unit, the core unit is always the default orientation unit. By pressing F on a gyro unit, you can switch to using the gyro unit as the current orientation unit.

You can see that the marker and arrow displayed when you enter the build mode will indicate the orientation given by the active orientation unit. 
You can activate a gyro unit by pressing F on it and so use its orientation.
 

See examples below:

For these changes, we have added:

• <int> core.getOrientationUnitId() : Returns the UID of the currently active orientation unit (the core unit or the gyro unit).

We have also modified the following functions:

• <vec3> core.getConstructOrientationForward() : Returns the forward direction vector of the active orientation unit in construct local coordinates.
• <vec3> core.getConstructOrientationUp() : Returns the up direction vector of the active orientation unit in construct local coordinates.
• <vec3> core.getConstructOrientationRight() : Returns the right direction vector of the active orientation unit in construct local coordinates.
• <vec3> core.getConstructWorldOrientationForward() : Returns the forward direction vector of the active orientation unit in world coordinates.
• <vec3> core.getConstructWorldOrientationUp() : Returns the up direction vector of the active orientation unit in world coordinates.
• <vec3> core.getConstructWorldOrientationRight() : Returns the right direction vector of the active orientation unit in world coordinates.
• <vec3> core.getConstructWorldPos() : Returns the position of the center of the construct in world coordinates (instead of orientation units position).
   

REMOVAL OF QUATERNIONS

 

Quaternions are the quotient of two directed lines in a three-dimensional space or the quotient of two vectors.  In looking at how players were using Lua and reading their feedback, , we realized that very few players were familiar with this mathematical notion of representing rotation. 

 

Therefore, we decided to deprecate quaternions from the Lua API and instead expose the direction vectors of objects.
 

 

While this leads to the addition and change of some functions, deprecated functions will remain backwards compatible and will display a deprecated message in the Lua console.

 

• <quat> core.getElementRotationById(<int> uid) : DEPRECATED
• <vec3> core.getElementPositionById(<int> uid) : Returns the position of the element, identified by its UID in construct local coordinates (instead of the construct corner).
• <vec3> unit.getMasterPlayerRelativePosition() : DEPRECATED
• <quat> unit.getMasterPlayerRelativeOrientation() : DEPRECATED

And we have added the following functions:

• <vec3> core.getElementForwardById(<int> uid) : Returns the forward direction vector of the element identified by its UID in construct local coordinates.
• <vec3> core.getElementUpById(<int> uid) : Returns the up direction vector of the element identified by its UID in construct local coordinates.
• <vec3> core.getElementRightById(<int> uid) : Returns the right direction vector of the element identified by its UID in construct local coordinates.
• <vec3> unit.getMasterPlayerPosition() : Returns the position of the player currently running the control unit in construct local coordinates (relative to the construct center instead of the control unit).
• <vec3> unit.getMasterPlayerWorldPosition() : Returns the position of the player currently running the control unit in world coordinates.
• <vec3> unit.getMasterPlayerForward() : Returns the forward direction vector of the player currently running the control unit in construct local coordinates.
• <vec3> unit.getMasterPlayerUp() : Returns the up direction vector of the player currently running the control unit in construct local coordinates.
• <vec3> unit.getMasterPlayerRight() : Returns the right direction vector of the player currently running the control unit in construct local coordinates.
• <vec3> unit.getMasterPlayerWorldForward() : Returns the forward direction vector of the player currently running the control unit in world coordinates.
• <vec3> unit.getMasterPlayerWorldUp() : Returns the up direction vector of the player currently running the control unit in world coordinates.
• <vec3> unit.getMasterPlayerWorldRight() : Returns the right direction vector of the player currently running the control unit in world coordinates.

 

DOCKING-RELATED LUA API ADDITIONS

With the new docking mechanic, we wanted to empower players to manage the parent-child relationship between constructs. 

Some of the additions were added in  the Ares (0.26.12) update;  however, we still had more changes and additions planned and these will be included with the Lua changes release

We have added and modified the following functions:

• <vec3> core.getVelocity(): Returns the construct's linear velocity, relative to its parent, in construct local coordinates.
• <vec3> core.getWorldVelocity(): Returns the construct's linear velocity, relative to its parent, in world coordinates.
• <vec3> core.getAbsoluteVelocity(): Returns the construct's absolute linear velocity in construct local coordinates.
• <vec3> core.getWorldAbsoluteVelocity(): Returns the construct's absolute linear velocity in world coordinates.
• <vec3> core.getParentPosition(): Returns the position of the construct's parent when docked in construct local coordinates.
• <vec3> core.getParentWorldPosition(): Returns the position of the construct's parent when docked in world coordinates.
• <vec3> core.getParentForward(): Returns the construct's parent forward direction vector in construct local coordinates.
• <vec3> core.getParentUp(): Returns the construct's parent up direction vector in construct local coordinates.
• <vec3> core.getParentRight(): Returns the construct's parent right direction vector in construct local coordinates.
• <vec3> core.getParentWorldForward(): Returns the construct's parent forward direction vector in world coordinates.
• <vec3> core.getParentWorldUp(): Returns the construct's parent up direction vector in world coordinates.
• <vec3> core.getParentWorldRight(): Returns the construct's parent right direction vector in world coordinates.

 

Questions? Comments? 

We’re sure some of the Lua-enthusiasts in our community will have questions and comments about this blog. Post them here so our resident Lua expert, Ligo, can discuss them with you.

 

Watch for Part 2 next week. It’s got great information about radar changes, the library database, an in-game atlas, and an event handling system.