Lua Element API Documentation

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


.

.

.