NQ-Wanderer Posted June 21, 2022 Share Posted June 21, 2022 "Hello Noveans, this is NQ-Ligo. Whether you’re piloting with Lua, hauling cargo on a scripted VTOL platform, controlling a factory with screens and programming boards, or simply enjoying an in-game arcade machine, Lua can impact almost every aspect of your experience in Dual Universe. After many years of accumulating Lua updates and additions, it’s time to revamp the Lua API of Dual Universe entirely. Our objective is to enhance and future-proof the tools available to those who create the fantastic scripts enjoyed by everyone in-game. WHY REVAMP LUA API? We must rework the Lua API to prepare it for future extensions by organizing it better, making it easier to use, and enhancing the tools available to our Lua creators. From a global point of view, the vision we have for Lua has evolved, and though we’re preparing a detailed changelog on our forum, here are some highlights: Restructuring of the entire Lua API. Preparing for an object-oriented approach to be ready for future evolutions. Reduce JSON use in the API to favor the use of real Lua tables. Rely much more on event-driven code to reduce player loops and server requests. Reduce the complexity of the scripts, thereby reducing their size. Add some nice-to-have features. Garner more interest in certain elements like the telemeter. WHAT’S CHANGING WITH THIS LUA API REVAMP? With the many changes coming to the API, we wanted to give you some of the highlights, while as we said above we’ll be giving you the specifics in another communication. For now, I want to discuss some of the most significant changes with you all in this devblog: NEW NAMING CONVENTION We needed to apply a clean naming convention with this revamp to make Lua easier to use. This will become even more necessary as we expand the Lua API in the future. As a result, multiple functions have been renamed, but most importantly, events will receive a name change. Any event will have a prefix ‘on’ from now on, for example: unit.onStart() unit.onStop() system.onUpdate() system.onFlush() unit.onTimer([string] tag) TWO NEW PERMANENT SLOTS ADDED As part of the API restructuring, we have decided to add two new permanent slots: `player` - This will represent the player using the script. Usually referred to as the "Master Player" in the current Control Unit or System API. `construct` - This will represent the construct on which the controller running the script is placed. Most of the construct-related functions were in the Core Unit API. Each of these slots will have the associated functions and events and will receive some additions. Let's take the example of `construct`. You will find functions and events coming from the Core Unit API and some additions. To give you an idea, here is just a snippet of the `construct` API: [string] getName() : Returns the name of the construct. [int] getId() : Returns the construct unique ID. NEW [table] getOwner() : Returns the owner entity of the construct. NEW [table] getCreator() : Returns the creator entity of the construct. NEW [0 or 1] isWarping() : Checks if the construct is currently warping. NEW [int] getWarpState() : Returns the current warp state (Idle = 1, Engage = 2, Align = 3 …). NEW [0 or 1] isInPvPZone() : Checks if the construct is in the PvP zone. NEW [float] getDistanceToSafeZone() : Returns the distance between the construct and the nearest safe zone. [string] getPvPTimer() : Returns the current construct PvP timer state. [float] getMass() : Returns the mass of the construct. [float] getInertialMass() : Returns the inertial mass of the construct, calculated as 1/3 of the trace of the inertial tensor. NEW [matrix] getInertialTensor() : Returns the inertial tensor of the construct. NEW [vec3] getCenterOfMass() : Returns the position of the center of mass of the construct, in local construct coordinates. NEW [vec3] getWorldCenterOfMass() : Returns the position of the center of mass of the construct, in world coordinates. [float] getCrossSection() : Returns the construct's cross sectional surface in the current direction of movement. [vec3] getSize() : Returns the size of the building zone of the construct. NEW [vec3] getBoundingBoxSize() : Returns the size of the bounding box of the construct. NEW [vec3] getBoundingBoxCenter() : Returns the position of the center of the bounding box of the construct in local construct coordinates. [float] getMaxSpeed() : Returns the max speed along the current moving direction. [float] getMaxAngularSpeed() : Returns the max angular speed. [table] getMaxSpeedPerAxis() : Returns the max speed per axis. [table] getMaxThrustAlongAxis( [string] taglist, [vec3] CRefAxis) : Returns the construct max kinematics parameters in both atmo and space range, in newtons. NEW [float] getCurrentBrake() : Returns the current braking force generated by construct brakes. NEW [float] getMaxBrake() : Returns the maximum braking force that can currently be generated by the construct brakes. The above are just a few examples. You can find more functions in the CODEX. MORE ITEM API FOR CONTAINERS AND INDUSTRY With the addition of the mining unit API, we also added item API to the game. We have since had a great interest in this type of function from our community, allowing players to get more detailed information from item IDs. As a result, we have decided to integrate it into multiple APIs for items or containers. For example: NEW [int] element.getItemId() : Returns the element item ID. NEW [int] weapon.getAmmo() : Returns the item ID of the currently equipped ammo. NEW [int] engine.getFuelId() : Returns the item ID of the fuel currently used by the engine. NEW [event] industry.onStarted( [int] id, [float] quantity) : Emitted when the Industry Unit has started a new production process. NEW [event] industry.onCompleted( [int] id, [float] quantity) : Emitted when the Industry Unit has completed a run. NEW [int] core.getElementItemIdById(uid): Returns the item ID of the Element, identified by its local UID. NEW [table] container.getContent() (old getItemsList): Returns a table describing the contents of the container, as a pair itemId and quantity per slot. CHANGING CONTAINER API Reading the contents of a container is one of our most widely used features, but there has always been a problem. Its current implementation allows players to make ten requests as quickly as they would like, followed by a wait time of five minutes. This has caused spikes in server requests on our end and has been impractical for players. We will change this behavior to allow you to make a content request with a fixed minimum delay of 30 seconds between two requests made with the `updateContent()` method. As before, receiving content from the server triggers the `onContentUpdate()` event allowing you to get the contents with the `getContent()` function. We have also made the updateContent function return the time left before the next request to give our players better tracking of the process. CLICK WITH LUA We’re adding a simple but often requested function; a mouse click for Lua! Left-click, named ‘leftMouse’, has been added as a Lua action, triggering the onActionStart, onActionStop and onActionLoop events. For design and security reasons, Lua will only detect left mouse clicks when not in use by the game. So if you click on a widget or in your inventory UI, Lua won't detect it. We’re excited to see what our talented coders in-game will make of this tool! MAKE THE LIGHTS FLASH In the past, we added the possibility of making light-elements glow with color components set to higher than 255. However, this caused graphical issues, and we had to remove the feature. We are reintroducing this feature with Mercury but limiting it to a maximum factor of 5. And at the same time, we are changing the color format from 0-255 to 0-1 and 0-5 for HDR colors for consistency. We will convert the color property of all existing light elements deployed in the game. ---------------------------------------------------------------------------------------------------------------------------------------------------------------- Many other changes and additions will be included with this revamp. There are so many that it would not be practical to cover them all in a general devblog, but we hope this small selection will inspire your creative spirit! WILL ALL MY SCRIPTS BE BROKEN? Although we consider this revamp necessary, we still want to give you time to transition and adapt your systems and allow your scripts’ users to continue using them during this transition. To simplify the transition, we will deprecate all of the current API from Mercury, which means that the current functions and events will remain functional for a time but will not be referenced in the CODEX anymore, nor visible on the UI for events. You will then receive a warning when using a deprecated function or event for the first time. Please note: This depreciation will be time-limited. The goal is to remove all of the old API by the game’s launch. Along with other factors, we will need to release a new-API version of the default flight configuration before removing the depreciation. We will continue to assess whether removing the old API before launch is possible, and we’ll keep you apprised. HOW CAN I CHECK THE UPCOMING API CHANGES? Given the extent of the changes, we have chosen not to list them all in this devblog. The list of changes is very long, so our goal is to try and post a detailed forum thread with all changes and we have published a mock API on the official Github to allow you to prepare yourself as well as possible. CONCLUSION We hope you are excited, as players and creators, by the few changes mentioned here, especially about the new opportunities for all to enjoy that our passionate Lua community will create in Dual Universe. Our goal with the revamp is to push the door to future possibilities, evolutions, and additions for Lua. We'll be looking to go even further in the future and provide you with more tools to create content for other players. As always, we appreciate your feedback and opinions, so please feel free to come and share your thoughts and ideas on this forum thread! We look forward to seeing you there. Yours truly, NQ Ligo" Jeronimo, Davian_Thadd, Shaman and 10 others 13 Link to comment Share on other sites More sharing options...
Recommended Posts