Lua Element API Documentation

  • 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


    .

    .

    .