- Element API
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.
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
All elements share the same generic methods described below
show the element widget in the in-game widget stack
hide the element widget in the in-game widget stack
the element integrity between 0 and 100
the element cuccent hit points (0 = destroyed)
the element maximal hit points when it's fully functional
a construct-unique id for the element
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.
reutns the container content mass (the sum of the mass of all the items it contains)
returns the container self mass
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.
A door that can be opened or closed
open the door
close the door
toggle the state of the door
returns the state of activation of the door
An engine is capable to produce a force and/or a torque to move your construct
set the engine thrust between 0 and maxThrust
returns the maximal thrust the engine can deliver
returns the current thrust level of the engine
returns the engine torgque axis
Force Field Unit
A forcefield to create an uncrossable energy barrier
activate the field
deactivate the field
toggle the state
returns the state of activation of the field
A landing gear that can be opened or closed
open the landing gear
close the landing gear
toggle the state of the gear
returns the state of activation of the landing gear
Emit a source of light
switches the light on
switches the light off
toggle the state of the light
returns the State of activation of the light
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.
displays the given text at the given coordinates in the screen
displays the given text centered in the screen with a font to maximize its visibility
set the whole screen html content (overrides anything already set)
displays the given html content at the given coordinates the screen
displays SVG code (anything that fits within a <svg> section)
update the element with the given id (returned by setContent) with a new html content
delete the element with the given id (returned by setContent)
update the visibility of the element with the given id (returned by setContent)
move the element with the given id (returned by setContent) to a new position in the screen
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.
returns the rank of the currently active out plug
delete the referenced sticker.
move the refernced sticker.
rotate the referenced sticker.
Detection Zone Unit
Detect the intrusion of any player inside the effect zone
returns the current state of occupation of the zone
A generel kinematic unit to obtain information about the ship orientation and velocity
local gravity intensity
local gravity vector in world coordinates
Laser Detector Unit
Laser Emittor Unit
Emits a signal when pressed, and as long as it is pressed
returns the state of activation of the button
the button has been pressed
the button has been released
Manual Switch Unit
A manual switch that can be in an on/off state
activate the switch on
deactivate the switch off
Pressure Tile Unit
Measures the distance to obstacle in front of it
returns the distance to the first obstacle in front of the telemeter
returns the max distance from which an obstacle can be detected (default is 20m)
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
solve the 3D linear system M*x=c0 where M is defined by its column vectors c1,c2,c3