Source: Dual Universe Pre-Alpha Tutorial: Lua Scripting | November 2017 (youtu.be/sbvJPuo9npE)
This is not the final version of Dual Universe. Everything can change.
Das ist keine vollständige Sammlung, sondern lediglich ein Ausschnitt aus dem Pre-Alpha Tutorial. Alles kann sich noch ändern. Dieses Material wurde offiziell von NQ released und unterliegt somit nicht der NDA.
Scripting (LUA)
- Introduction
- Concepts
- Element API
Introduction
In Dual Universe, you can script interactions between Elements using LUA. The principle is the following: you can plug Elements into a Control Unit 'CONTROL' slots, and each of the plugged Element will present itself as a LUA object capable to emit events and execute functions. The name of the slot is simply the name of the LUA object. The Control Unit has dedicated *Edit LUA* window where you can then associate a piece of LUA code to any event emitted by one of your plugged Element. This code will be executed when the event occurs. Inside the LUA script, you can use the funktions offered by the plugged Elements to generate any behavior you like. These functions are simply methods of the LUA object that represents the slot where your Element is plugged into.
Concepts
To script Elements in LUA, here are the necessary steps:
- Identify the Control Unit that you want to host your LUA scripting. You LUA code will run when you activate this Control Unit.
- Plug all the Elements that you want to script together inside the Control Unit, using CONTROL links. You can simply click the Control Unit and then the desired plugged Element, this will pick the first free CONTROL plug in your Control Unit. The may want to selectively pick a particular plug, in that case you need to right-click on the Control Unit first and select the desired plug in the menu.
- Once all the Elements are plugged, open the *Edit LUA* window from the context menu of the Control Unit. This will open the *Control Unit Editor*.
- The Control Unit Editor is composed of three columns. The first column lists all the slots available, with the corresponding Element plugged inside them. Each Slot correspond to one of the CONTROL plug of the Control Unit.
Note that there are some predefined slots:
-
- System the System DPU, to acces things like keystrokes, updates, timers. See the doc below.
- Unit: this is the Control Unit itself
- Liberary: contains useful functions that are implemented in C++ for performance reasons
The rest of the slots are the slots you used to plug your Elements. You can rename them to help you remember who is what.
- Select one slot, for expample the System slot.
- In the middle column (which is initially empty). you can define event handlers to react to events associated to the slot you have selected.
- Add an event, for example *actionStart*, and select the *forward* action in the dropdown menu that appers when you try to edit the event argument.
- When you click on an event handler, the third column will display the associated LUA code that must be run when this event occurs.
- The LUA code can use any of the functions of any slot, using the syntax: slot.function(...)
- The documentation below details all the functions and events available for all type of Element in the game
Physics Scripting, how is your ship flying?
Piloting a ship is a complex topic, a bit like... rocket science actually! We tried to simplify it to a few core concepts. The ship will move because it has some engines attached to it,and engines are capable to exert a force on the body of the ship. To be more precise, there are two things an engine can generate.
- Forces: they actually push your ship and make it move in a given direction
- Torques: they make your ship rotate on itself
- ...
...
Element API
Generic Element
All elements share the same generic methods described below
show()
show the element widget in the in-game widget stack
hide()
hide the element widget in the in-game widget stack
getIntergrity()
the element integrity between 0 and 100
| Argument/Return | Type | Description |
| return | 0..100 | 0 = element fully destroyed. 100 = element flly functional |
getHitPoints()
the element cuccent hit points (0 = destroyed)
| Argument/Return | Type | Description |
| return |
- | the hitpoints. 0 = element fully destroyed |
getMaxHitPoints()
the element maximal hit points when it's fully functional
| Argument/Return |
Type | Description |
| return | - | the max hitpoints of the element |
getId()
a construct-unique id for the element
| Argument/Return | Type | Description |
| return | - | the element id |
getMass()
.
.
.
getSignalOut(plug)
return the value of a signal in the specified OUT plug of the element Standard plug names are composed with the following syntax -> direction-type-index where 'direction' can be IN or OUT, 'type' is one of the following -> ITEM, FUEL, ELECTRICITY, SIGNAL, HEAT, FLUID, CONTROL, and 'index' is a number between 0 and the total number of plugs of the given type in the given direction. Some plugs have special names like 'on' or 'off' for the Manual Swith Unit, just check in-game for the plug names if you have a doubt.
| Argument/Return | Type | Description |
| plug | - | the plug name, of the form OUT-SIGNAL-index |
| return | 0/1 | the plug signal state |
Container Unit
Stores items
getItemsMass()
reutns the container content mass (the sum of the mass of all the items it contains)
| Argument/Return |
Type | Description |
| return | kg | the total container content mass, excluding the container own self mass |
getSelfMass()
returns the container self mass
| Argument/Return | Type | Description |
| return | kg | the container self mass. as if it where empty |
Control Unit
Controll Units come in various forms, cockpits, programming boards, Emergency Control Units, etc. A Control Unit stores a set of LUA scripts that can be used to control the Elements that are plugged on its CONTROL plugs. Kinematics Control Units like cockpit or commander seats are also capable of controlling the ship´s engines via the updateICC method.
.
.
.
Door Unit
A door that can be opened or closed
activate()
open the door
deactivate()
close the door
toggle()
toggle the state of the door
getState()
returns the state of activation of the door
| Argument/Return | Type | Description |
| return | - | 1 when the door is opened. 0 otherwise |
Engine Unit
An engine is capable to produce a force and/or a torque to move your construct
setThrust(thrust)
set the engine thrust between 0 and maxThrust
| Argument/Return | Type | Description |
| thrust | Newton | the engine thrust |
getMaxThrust()
returns the maximal thrust the engine can deliver
| Argument/Return | Type | Descripton |
| return | Newton | the current max thrust |
getThrust()
returns the current thrust level of the engine
| Argument/Return | Type | Description |
| return | Newton | the thrust the engine is currently delivering |
getTorqueAxis()
returns the engine torgque axis
| Argument/Return | Type | Description |
| return | vec3 | the engine thrust direction in world coordinates |
getDistanceToObstacle()
.
.
.
Force Field Unit
A forcefield to create an uncrossable energy barrier
activate()
activate the field
deactivate()
deactivate the field
toggle()
toggle the state
getState()
returns the state of activation of the field
| Argument/Return | Type | Description |
| return | - | 1 when the field is active. 0 otherwise |
LandingGear Unit
A landing gear that can be opened or closed
activate()
open the landing gear
deactivate()
close the landing gear
toggle()
toggle the state of the gear
getState()
returns the state of activation of the landing gear
| Argument/Return | Type | Description |
| return | - | 1 when the landing gear is opened. 0 otherwise |
Light Unit
Emit a source of light
activate()
switches the light on
deactivate()
switches the light off
toggle()
toggle the state of the light
getState()
returns the State of activation of the light
| Argument/Return | Type | Description |
| return | - | 1 when the light is on. 0 otherwise |
Screen Unit
Screen Unit are capable to display any html code or text message, you can use them to create visually interactive feedback for your running LUA script by connecting one or more of them to your Control Unit.
setText(x,y,fontSize,text)
displays the given text at the given coordinates in the screen
| Argument/Return | Type | Description |
| x | 0..100 | horizontal position, as a percentage of the screen width |
| y | 0..100 | vertical position, as a percentage of the screen height |
| fontSize | 0..100 | text font size, as percantage of the screen width |
| text | string | the text to display |
| return | - | an integer id that can be used later to update/remove the added element |
setCenteredText(text)
displays the given text centered in the screen with a font to maximize its visibility
| Argument/Return | Type | Description |
| text | string | the text to display |
setRawHTML(html)
set the whole screen html content (overrides anything already set)
| Argument/Return | Type | Description |
| text | html | the html content to display |
setContent(x,y,html)
displays the given html content at the given coordinates the screen
| Argument/Return | Type | Description |
| x | 0..100 | horizontal position, as a percentage of the screen width |
| y | 0..100 | vertical position, as a percentage of the screen height |
| html | html | the html content to display, which can contain SVG elements to make drawings |
| return | an interger id that can be used later to update/remove the added element |
setSVG(svg)
displays SVG code (anything that fits within a <svg> section)
| Arguments/Return | Type | Description |
| html | html | the SVG conent to display, which fits inside a 1920x1080 canvas |
| return | - | an integer id that can be used later to update/remove the added element |
resetContent(id,html)
update the element with the given id (returned by setContent) with a new html content
| Argument/Return | Type | Description |
| id | - | an integer id that is used to identify the element in the screen. Methods such as setContenct return the id that you can store to use later here. |
| html | html | the html content to display, which can contain SVG elements to make drawings |
deleteContent(id)
delete the element with the given id (returned by setContent)
| Argument/Return | Type | Description |
| id | - | an integer id that is used to identify the element in the screen. Methods such as setContent return the id that you can store to use later here. |
showContent(id,state)
update the visibility of the element with the given id (returned by setContent)
| Argument/Return | Type | Description |
| id | - | an integer id that is used to identify the element in the screen. Methods such as setContent return the id that you can store to use later here. |
| state | 0/1 | 0 = invisible, 1 = visible |
moveContent(id,x,y)
move the element with the given id (returned by setContent) to a new position in the screen
| Argument/Return | Type | Description |
| x | 0..100 | horizontal position, as a percantage of the screen width |
| y | 0..100 | vertical position, as a percantage of the screen height |
| id | - | an integer id that is used to identify the lement in the screen. Methods such as SetContent retun the id that you can store to use later here. |
clear()
clear the screen
Cycle its Outbput signal over a set of n plugs, incrementing the activate plug by one step at each impulse received on its inPlug.
getCounterState()
returns the rank of the currently active out plug
| Argument/Return | Type | Description |
.
.
.
Counter Unit
.
.
.
Core Unit
.
,
,
deleteSticker(index)
delete the referenced sticker.
| Argument/Return | Type | Description |
| index | int | index of the sticker to delete |
| return | int | 1 in case of success. 0 otherwise |
moveSticker(index,x,y,z)
move the refernced sticker.
| Argument/Return | Type | Description |
.
.
.
rotateSticker(index,angle_x,angle_y,angle_z)
rotate the referenced sticker.
| Argument/Return | Type | Description |
| angle_x | deg | rotation along the x axis |
| angle_y | deg | rotation along the y axis |
| angle_z | deg | rotation along the z axis |
| index | int | index of the sticker to rotate |
| return | int | 1 in case of success, 0 otherwise |
Detection Zone Unit
Detect the intrusion of any player inside the effect zone
getState()
returns the current state of occupation of the zone
.
.
.
Gyro Unit
A generel kinematic unit to obtain information about the ship orientation and velocity
g()
local gravity intensity
| Argument/Return | Type | Description |
| return | m/s2 | the gravitation acceleration where the construct is located |
getWorldGravity()
local gravity vector in world coordinates
| Argument/Return | Type | Description |
.
.
.
Laser Detector Unit
.
.
.
Laser Emittor Unit
.
.
.
Manuel Button
Emits a signal when pressed, and as long as it is pressed
getState()
returns the state of activation of the button
| Argument/Return | Type | Description |
| return | - | 1 when the button is pressed. 0 otherwise |
pressed() event
the button has been pressed
released() event
the button has been released
Manual Switch Unit
A manual switch that can be in an on/off state
activate()
activate the switch on
deactivate()
deactivate the switch off
.
.
.
Pressure Tile Unit
.
.
.
Telemeter Unit
Measures the distance to obstacle in front of it
getDistance()
returns the distance to the first obstacle in front of the telemeter
| Argument/Return | Type | Decsription |
| return | meter | the distance to the obstacle, up to getMaxDistance, or -1 if there is no obstacle (or the obstacle is further away than the max distance) |
getMaxDistance()
returns the max distance from which an obstacle can be detected (default is 20m)
| Argument/Return | Type | Description |
| return | meter | the max distance to detectable obstacles |
Library
Contains a list of useful math and helper methods that would be slow to implement in LUA, and which are given here as fast C++ implementation
systemResolution3(vec_cl,vec_c2,vec_c3,vec_c0)
solve the 3D linear system M*x=c0 where M is defined by its column vectors c1,c2,c3
.
.
.
