Dual Universe Lua Scripting

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 a 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 functions 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. You 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 access things like keystrokes, updates, timers. See the doc below.
  • Unit: this is the Control Unit itself
  • Library: 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 example 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 appears 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: slotname.function(...)
• The documentation below details all the functions and events available for all the type of Element in the game

The Lua community in Dual Universe is very active and have produced some outstanding work. See page on Community Links

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

To simplify the control problem, we made a first move by defining engines that can do "torque" only, called the "Adjustors", vs engines that can do "force" only, basically the other engines. Hovercraft engines are the only engines capable to produce force and torque at the same time.

You can control the thrust of each individual engine in your ship by plugging them in the Control Unit and using the setThrust method. However, this can become tedious as the number of engines grow, and it is quite difficult to calculate exactly what thrust to apply to which engine if you want to control the overall global cumulative effect. So, we introduce a cool notion to simplify the process of controlling your engines: grouping.

Grouping engines is done via a tagging mechanism, that you can access by right-clicking an engine and setting its associated tags. By default, all engines are tagged with "all" and some other tags indicating their typical role in the ship control. The default tagging is the following:

• Adjustors: all, torque
• Hovercraft: all, vertical, torque
• Vertical Boosters: all, vertical
• Air brake or Retro Engines: all, brake
• All the others: all, horizontal

These are the default, and you can freely modify them and add you custom groups.

Once you have a group of engines, you have a facility within your Control Unit to address them as a whole, just as if they were one single engine, and assign them a given linear and angular acceleration. The system will then calculate the corresponding force and torque that are needed to produce these accelerations, and figure out a thrust assignment for all the engines in the group, so that the end result will be equal or as close as possible to the requested command. This is the "setEngineCommand" method, available in the Control Unit slot (called "unit").

Using this facility, the auto configurator that generates a Lua script for you the first time you enter into a cockpit will typically produce Lua code of this form:

• control.setEngineCommand("vertical,torque", acceleration, angularAcceleration)
• control.setEngineCommand("horizontal", forwardAcceleration, nullvector)
• control.setEngineCommand("brake", brake, nullvector)

The linear acceleration in the horizontal or vertical direction, as well as the angular acceleration, are the result of a computation that is done in the Navigator Lua code, which you may freely modify (it's the ControlCommand.lua file, which is loaded whenever you start a Control Unit), and which defines how controlling of your ship by pressing keys will affect the desired acceleration requested.

All these calculation and the final call to the setEngineCommand method are done in the "flush" event of the System slot. Flush is called several times per frame to calculate the physics simulation. You should never put anything else but physics-related calculation in flush. Anything else this is gameplay related, like connecting buttons or displaying things on screens, should be done in the "update" event, which is called at each frame rendering.

System events and methods

The System DPU, available in the "system" slot is a crucial part of your Lua programming. This virtual element (it is always plugged and always there) will send various events that you can catch to orchestrate your Lua scripting.

There are three fundamental ways to get events are regular intervals from System:

• update: this event is triggered at each frame (its frequency will depend on the framerate)
• flush: this event is triggered at each step of the physics calculation, usually more than once per frame. Be careful to limit its use to setting engine thrusts, for example with the setEngineCommand method.
• tick(n): this event is repeatedly triggered whenever the timer 'n' is reaching its duration. You can create a timer with index "n" and with a given duration using the setTimer(n, duration) method in System. The duration is expressed in seconds, and the event will tick at quasi-regular intervals, independently of the framerate if the duration is larger that the typical frame duration.

The other important event type that System is managing are keystroke events. We call these "actions" to make it independent on the particular key binding that will be associated to it. System then defines three types of events associated to an action:

• actionStart(action): this event is triggered when the action starts (key pressed down)
• actionStop(action): this event is triggered when the action stops (key released)
• actionLoop(action): this event is triggered at each frame as long as the key is pressed (think of it as a filter on the "update" event)

Actions are referred to by their name, and the Control Unit Editor will pop a list of available actions to choose from whenever you click on the argument of an action event.

Lua code associated to an event filter

Inside the code window that is associated to an event filter on a given slot, you can type in any Lua code you like. There are limits in memory and CPU usage however, as well as in the total size of the code (currently 10Ko compressed).

Note that the Lua interpreter that runs the Lua code is specific to each Control Unit, so there is not automatic sharing of the memory between two running Control Units. You may however exchange variable between different event handlers, simply define them without the "local" keyword and they will become global variables.

The Lua code will typically refer to some of the slots in the Control Unit to call methods associated to the elements that are plugged in these slots. Suppose you have a "screen" slot where you have plugged a Screen Unit, you may write code of the form: screen.setCenteredText("Hello World") To know what methods and what events are available for all the different Elements in the game, simply refer to the documentation below.

How to expose some values outside of Lua editor

You can edit Lua variable values without opening the Lua editor. This can be handy to expose some configuration variables. They only have to be declared with the "export" keyword:

• rotationSpeed = 2 --export local rotationSpeed = 2 --export: rotation speed in rad/s

Then, you can right click on your ControlUnit and select the "Edit Lua Parameters" action to modify those exported values.

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

getData()

Get element data as JSON

Argument/Return	Type	Description
return	string	Data as JSON.

getDataId()

Get element data ID

Argument/Return	Type	Description
return	string	Data ID. "" if invalid.

getWidgetType()

Get widget type compatible with the element data

Argument/Return	Type	Description
return	string	Widget type. "" if invalid.

getIntegrity()

The element integrity between 0 and 100

Argument/Return	Type	Description
return	0..100	0 = element fully destroyed, 100 = element fully functional

getHitPoints()

The element current hit points (0 = destroyed)

Argument/Return	Type	Description
return	-	The hit points, where 0 = element fully destroyed

getMaxHitPoints()

The element's maximal hit points when it's fully functional

Argument/Return	Type	Description
return	-	The max hit points of the element

getId()

A construct unique ID for the element

Argument/Return	Type	Description
return	-	The element ID

getMass()

The mass of the element

Argument/Return	Type	Description
return	kg	The mass of the element (includes the included items' mass when the element is a container)

getElementClass()

The class of the element

Argument/Return	Type	Description
return	string	The class name of the element

setSignalIn(plug, state)

Set the value of a signal in the specified IN 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 switch unit, just check in-game for the plug names if you have a doubt.

Argument/Return	Type	Description
plug	-	The plug name, in the form of IN-SIGNAL-index
state	0/1	The plug signal state

getSignalIn(plug)

Return the value of a signal in the specified IN 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 switch unit, just check in-game for the plug names if you have a doubt.

Argument/Return	Type	Description
plug	-	The plug name, in the form of IN-SIGNAL-index
return	0/1	The plug signal state

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 switch 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()

Returns the container content mass (the sum of the mass of all the items it contains)

Argument/Return	Type	Description
return	kg	The total mass of the container's content, excluding the container's own mass itself

getSelfMass()

Returns the container self mass

Argument/Return	Type	Description
return	kg	The container self mass, as if it where empty

Control unit

Control 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 command seats are also capable of controlling the ship's engines via the update ICC method.

exit()

Stops the control unit's Lua code and exits. Warning: calling this might cause your ship to fall from the sky, use it with care. It is typically used in the coding of emergency control unit scripts to stop control once the ECU thinks that the ship has safely landed.

setTimer(timerTagId, period)

Set up a timer with a given tag ID in a given period. This will start to trigger the 'tick' event with the corresponding ID as an argument, to help you identify what is ticking, and when.

Argument/Return	Type	Description
timerTagId	string	The ID of the timer, as a string, which will be used in the 'tick' event to identify this particular timer
period	second	The period of the timer, in seconds. The time resolution is limited by the framerate here, so you cannot set arbitrarily fast timers.

stopTimer(timerTagId)

Stop the timer with the given ID

Argument/Return	Type	Description
timerId	string	The ID of the timer to stop, as a string

getAtmosphereDensity()

Returns the local atmosphere density, between 0 and 1

Argument/Return	Type	Description
return	0..1	The atmosphere density (0 = in space)

getClosestPlanetInfluence()

Returns the closest planet influence, between 0 and 1

Argument/Return	Type	Description
return	0..1	The closest planet influence. 0 = in space, 1 = on the ground

getMasterPlayerRelativePosition()

Return the relative position (in world coordinates) of the player currently running the control unit

Argument/Return	Type	Description
return	vec3	Relative position in world coordinates

getMasterPlayerId()

Return the ID of the player currently running the control unit

Argument/Return	Type	Description
return	int	ID of the player running the control unit

setEngineCommand(taglist, acceleration, angularAcceleration, keepForceCollinearity, keepTorqueCollinearity, priority1SubTags, priority2SubTags, priority3SubTags, toleranceRatioToStopCommand)

Automatically assign the engines within the taglist to result in the given acceleration and angular acceleration provided. Can only be called within the system.flush event. If engines designated by the tags are not capable of producing the desired command, setEngineCommand will try to do its best to approximate it.

Argument/Return	Type	Description
taglist	csv	Comma (for union) or space (for intersection) separated list of tags. You can set tags directly on the engines in the right-click menu.
acceleration	m/s2	The desired acceleration expressed in world coordinates
angularAcceleration	rad/s2	The desired angular acceleration expressed in world coordinates
keepForceCollinearity	bool	Forces the resulting acceleration vector to be collinear to the acceleration parameter
keepTorqueCollinearity	bool	Forces the resulting angular acceleration vector to be collinear to the angular acceleration parameter
priority1SubTag	priority1SubTag	Comma (for union) or space (for intersection) separated list of tags of included engines to use as priority 1
priority2SubTag	priority2SubTag	Comma (for union) or space (for intersection) separated list of tags of included engines to use as priority 2
priority3SubTag	priority3SubTag	Comma (for union) or space (for intersection) separated list of tags of included engines to use as priority 3
toleranceRatioToSkipOtherPriorities	0,1	When going through with priorities, if we reach a command that is achieved within this tolerance, we will stop there.

setEngineThrust(taglist, thrust)

Force the thrust value for all the engines within the tag list

Argument/Return	Type	Description
taglist	csv	Comma separated list of tags. You can set tags directly on the engines in the right-click menu.
thrust	N	The desired thrust in newtons (note that for boosters, any non zero value here will set them to 100%)

setAxisCommandValue(axis, commandValue)

Set the value of throttle in the cockpit, which will be displayed in the cockpit widget when flying

Argument/Return	Type	Description
axis	0, 1, 2	Longitudinal = 0, lateral = 1, vertical = 2
commandValue	-1..1	In 'by throttle', the value of the throttle position: -1 = full reverse, 1 = full forward. Or In 'By Target Speed', the value of the target speed in km/h

getAxisCommandValue(axis)

Get the value of throttle in the cockpit

Argument/Return	Type	Description
axis	0, 1, 2	Longitudinal = 0, lateral = 1, vertical = 2
return	-1..1 or float	In travel mode, return the value of the throttle position: -1 = full reverse, 1 = full forward or in cruise mode, return the value of the target speed

setupAxisCommandProperties(axis, commandType)

Set the properties of an axis command These properties will be used to display the command in UI

Argument/Return	Type	Description
axis	0, 1, 2	Longitudinal = 0, lateral = 1, vertical = 2
commandType	0, 1	By throttle = 0, by target speed = 1, hidden = 2
targetSpeedRanges	list	This is to specify the cruise control target speed ranges (for now, only for the longitudinal axis)

getControlMasterModeId()

Get the current master mode in use. The mode is set by clicking the UI button or using the associated keybinding

Argument/Return	Type	Description
return	int	The current master mode (for now, only 2 are available, 0 and 1)

cancelCurrentControlMasterMode()

Cancel the current master mode in used

isAnyLandingGearExtended()

Check landing gear status

Argument/Return	Type	Description
return	0 or 1	1 if any landing gear is extended

extendLandingGears()

Extend/activate/drop the landing gears

retractLandingGears()

Retract/deactivate the landing gears

isMouseControlActivated()

Check if a mouse control scheme is selected

Argument/Return	Type	Description
return	0 or 1	1 if a mouse control scheme is selected

isMouseDirectControlActivated()

Check if the mouse control direct scheme is selected

Argument/Return	Type	Description
return	0 or 1	1 if a mouse control direct scheme is selected

isMouseVirtualJoystickActivated()

Check if the mouse control virtual joystick scheme is selected

Argument/Return	Type	Description
return	0 or 1	1 if a mouse control virtual joystick scheme is selected

isAnyHeadlightSwitchedOn()

Check lights status

Argument/Return	Type	Description
return	0 or 1	1 if any headlight is switched on

switchOnHeadlights()

switchOn the lights

switchOffHeadlights()

switchOff the lights

isRemoteControlled()

Check if the construct is remote controlled

Argument/Return	Type	Description
return	0 or 1	1 if the construct is remote controlled

activateGroundEngineAltitudeStabilization(targetAltitude)

The ground engines will stabilize to this altitude within their limits The stabilization will be done by adjusting thrust to never go over the target altitude This includes VerticalBooster and HoverEngine

getSurfaceEngineAltitudeStabilization()

return the ground engines stabilization altitude

Argument/Return	Type	Description
return	float	the stab altitude (m) or 0 if none is set

deactivateGroundEngineAltitudeStabilization()

The ground engines will behave like regular engine This includes VerticalBooster and HoverEngine

computeGroundEngineAltitudeStabilizationCapabilities()

Returns ground engine stabilization altitude capabilities (lower and upper ranges)

Argument/Return	Type	Description
return	vec2	Stabilization altitude capabilities for the least powerful engine and the most powerful engine

getThrottle()

return the current throttle value

Argument/Return	Type	Description
return	float	the throttle value between -100 and 100

tick(timerId)   event

Emitted when the timer with id 'timerId' is ticking

Argument/Return	Type	Description
timerId	-	The ID (int) of the timer that just ticked (see setTimer to set a timer with a given ID)

Databank unit

Stores key/value pairs in a persistent way.

clear()

Clear the data bank

getNbKeys()

Returns the number of keys that are stored inside the data bank

Argument/Return	Type	Description
return	int	The number of keys

getKeys()

Returns all the keys in the data bank

Argument/Return	Type	Description
return	json	The key list, as JSON sequence

hasKey(key)

Returns 1 if the key is present in the data bank, 0 otherwise

Argument/Return	Type	Description
return	bool	1 if the key exists and 0 otherwise

setStringValue(key,val)

Stores a string value at the given key

Argument/Return	Type	Description
key	string	The key used to store the value
val	string	The value, as a string

getStringValue(key)

Returns value stored in the given key as a string

Argument/Return	Type	Description
key	string	The key used to retrieve the value
return	string	The value as a string

setIntValue(key,val)

Stores an integer value at the given key

Argument/Return	Type	Description
key	string	The key used to store the value
val	int	The value, as an integer

getIntValue(key)

Returns value stored in the given key as an integer

Argument/Return	Type	Description
key	string	The key used to retrieve the value
return	int	The value as an integer

setFloatValue(key,val)

Stores a floating number value at the given key

Argument/Return	Type	Description
key	string	The key used to store the value
val	float	The value, as a floating number

getFloatValue(key)

Returns value stored in the given key as a floating number

Argument/Return	Type	Description
key	string	The key used to retrieve the value
return	float	The value as a floating number

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 activation state 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.

activate()

Start the engine at full power (works only when run inside a cockpit or under remote control)

deactivate()

Stops the engine (works only when run inside a cockpit or under remote control)

toggle()

Toggle the state of the engine

getState()

Returns the state of activation of the anti-g generator

Argument/Return	Type	Description
return	-	1 when the anti-g generator is started, 0 otherwise

setThrust(thrust)

Set the engine thrust between 0 and maxThrust

Argument/Return	Type	Description
thrust	Newton	The engine thrust

getMaxThrustBase()

Returns the maximal thrust the engine can deliver in principle, under optimal conditions. Note that the actual maxThrust will most of the time be less than maxThrustBase.

Argument/Return	Type	Description
return	Newton	The base max thrust

getCurrentMaxThrust()

Returns the maximal thrust the engine can deliver at the moment, which might depend on various conditions like atmospheric density, obstruction, orientation, etc. The actual thrust will be anything below this maxThrust, which defines the current max capability of the engine.

Argument/Return	Type	Description
return	Newton	The current max thrust

getCurrentMinThrust()

Returns the minimal thrust the engine can deliver at the moment (can be more than zero), which will depend on various conditions like atmospheric density, obstruction, orientation, etc. Most of the time, this will be 0 but it can be greater than 0, particularly for ailerons, in which case the actual thrust will be at least equal to minThrust.

Argument/Return	Type	Description
return	Newton	The current min thrust

getMaxThrustEfficiency()

Returns the ratio between the current MaxThrust and the base MaxThrust

Argument/Return	Type	Description
return	-	Usually 1 but can be lower for certain engines

getThrust()

Returns the current thrust level of the engine

Argument/Return	Type	Description
return	Newton	The thrust the engine is currently delivering

torqueAxis()

Returns the engine torque axis

Argument/Return	Type	Description
return	vec3	The torque axis in world coordinates

thrustAxis()

Returns the engine thrust direction

Argument/Return	Type	Description
return	vec3	The engine thrust direction in world coordinates

getDistanceToObstacle()

Returns the distance to the first object detected in the direction of the thrust

Argument/Return	Type	Description
return	meter	The distance to the first obstacle

isOutOfFuel()

Is the engine out of fuel?

Argument/Return	Type	Description
return	bool	1 when there is no fuel left, 0 otherwise

hasBrokenFuelTank()

Is the engine linked to a broken fuel tank?

Argument/Return	Type	Description
return	bool	1 when the linked tank is broken, 0 otherwise

getCurrentFuelRate()

The engine rate of fuel consumption per newton delivered per second

Argument/Return	Type	Description
return	m3/(N.s)	How many litres of fuel per newton per second

getFuelRateEfficiency()

Returns the ratio between the current fuel rate and the theoretical nominal fuel rate

Argument/Return	Type	Description
return	-	Usually 1 but can be higher for certain engines at certain speeds

getT50()

The time needed for the engine to reach 50% of its maximal thrust (all engines do not instantly reach the thrust that is set for them, but they can take time to "warm up" to the final value)

Argument/Return	Type	Description
return	second	The time to half thrust

isObstructed()

If the engine exhaust is obstructed by some element or voxel material, it will stop working or may work randomly in an instable way and you should probably fix your design.

Argument/Return	Type	Description
return	bool	1 when the engine is obstructed

getObstructionFactor()

Returns the obstruction ratio of the engine exhaust by elements and voxels. The more obstructed the engine is, the less properly it will work. Try to fix your design if this is the case.

Argument/Return	Type	Description
return	-	The obstruction ratio of the engine

getTags()

Tags of the engine

Argument/Return	Type	Description
return	csv	Tags of the engine, in a CSV string

setTags(tags)

Set the tags of the engine

Argument/Return	Type	Description
tags	string	CSV string of the tags

getFuelConsumption()

The current rate of fuel consumption

Argument/Return	Type	Description
return	m3/s	How many cubic meters of fuel per unit of time

Fireworks unit

A unit capable to launch fireworks that are stored in the attached container.

activate()

Fire the firework

setExplosionDelay(t)

Set the delay before the launched fireworks explodes. Max=5s

Argument/Return	Type	Description
t	second	The delay before explosion

setLaunchSpeed(v)

Set the speed at which the firework will be launched (impacts its altitude, depending on the local gravity). Max=200m/s

Argument/Return	Type	Description
v	m/s	The launch speed

setType(type)

Set the type of launched firework (will affect which firework is picked in the attached container)

Argument/Return	Type	Description
type	int	0=BALL, 1=PALMTREE, 2=RING, 3=SHOWER

setColor(color)

Set the color of the launched firework (will affect which firework is picked in the attached container)

Argument/Return	Type	Description
color	int	0=BLUE, 1=GOLD, 2=GREEN, 3=PURPLE, 4=RED, 5=SILVER

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 activation state of the field

Argument/Return	Type	Description
return	-	1 when the field is active, 0 otherwise

Landing gear 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 activation state of the landing gear

Argument/Return	Type	Description
return	-	1 when the landing gear is opened, 0 otherwise

Light unit

Emits a source of light.

activate()

Switches the light on

deactivate()

Switches the light off

toggle()

Toggle the state of the light

getState()

Returns the activation state of the light

Argument/Return	Type	Description
return	-	1 when the light is on, 0 otherwise

getRGBColor()

Get the light color in RGB

Argument/Return	Type	Description
return	vec3	A vec3 for the red, blue and green components of the light, with values between 0 and 255

setRGBColor(r,g,b)

Set the light color in RGB

Argument/Return	Type	Description
r	int	The red component, between 0 and 255
g	int	The green component, between 0 and 255
b	int	The blue component, between 0 and 255

Lua Scripting

Anti gravity generator unit

Generates graviton condensates to power anti-gravity pulsors

activate()

Start the anti-g generator

deactivate()

Stop the anti-g generator

toggle()

Toggle the state of the anti-g generator

getState()

Returns the state of activation of the anti-g generator

Argument/Return	Type	Description
return	-	1 when the anti-g generator is started, 0 otherwise

setBaseAltitude(altitude)

Set the base altitude for the anti-gravity field

Argument/Return	Type	Description
altitude	m	The desired altitude. It will be reached with a slow acceleration (not instantaneous)

getBaseAltitude()

Return the base altitude for the anti-gravity field

Argument/Return	Type	Description
return	m	The base altitude

Industry unit

Can mass-produce produce any item/element.

start()

Start the production, and it will run unless it is stopped or the input resources run out.

startAndMaintain()

Start maintaining the specified quantity. Resumes production when the quantity in the output container is too low, and pauses production when it is equal or higher

Argument/Return	Type	Description
quantity	int	Quantity to maintain inside output containers

batchStart()

Start the production of numBatches and then stop

Argument/Return	Type	Description
numBatches	int	Number of batches to run before unit stops

softStop()

End the job and stop. The production keeps going until it is complete, then it switches to "STOPPED" status. If the output container is full, then it switches to "JAMMED"

hardStop()

Stop production immediately. The resources are given back to the input container. If there is not enough room in the input containers, production stoppage is skipped if allowIngredientLoss is set to 0, or ingredients are lost if set to 1

Argument/Return	Type	Description
allowIngredientLoss	0/1	0 = forbid loss, 1 = enable loss

getStatus()

Get the status of the industry

Argument/Return	Type	Description
return	string	The status of the industry can be: STOPPED, RUNNING, JAMMED_MISSING_INGREDIENT, JAMMED_OUTPUT_FULL, JAMMED_NO_OUTPUT_CONTAINER

getCycleCountSinceStartup()

Get the count of completed cycles since the player started the unit

Argument/Return	Type	Description
return	int	The count of completed cycles since startup

getEfficiency()

Get the efficiency of the industry

Argument/Return	Type	Description
return	0..1	The efficiency rate between 0 and 1

getUptime()

Get the time elapsed in seconds since the player started the unit for the latest time

Argument/Return	Type	Description
return	s	The time elapsed in seconds

completed()   event

Emitted when the industry unit has completed a run

statusChanged(status)   event

Emitted when the industry status has changed

Argument/Return	Type	Description
status	string	The status of the industry can be: STOPPED, RUNNING, JAMMED_MISSING_INGREDIENT, JAMMED_OUTPUT_FULL, JAMMED_NO_OUTPUT_CONTAINER

Counter unit

Cycle its output signal over a set of n-plugs, incrementing the activate plug by one step at each impulse received on its IN plug.

getCounterState()

Returns the rank of the currently active OUT plug

Argument/Return	Type	Description
return	-	The index of the active plug

next()

Moves the counter one step further (equivalent to signal received on the IN plug)

Emitter unit

This unit is capable of emitting messages on channels.

send(channel,message)

Send a message on the given channel

Argument/Return	Type	Description
channel	string	The channel name
message	string	The message to transmit

getRange()

Returns the emitter range

Argument/Return	Type	Description
return	meter	The range

Receiver unit

Receives messages on given channels.

getRange()

Returns the receiver range

Argument/Return	Type	Description
return	meter	The range

receive(channel,message)   event

Emitted when a message is received on any channel

Argument/Return	Type	Description
channel	string	The channel; can be used as a filter
message	string	The message received

Core unit

This is the heart of your construct. It represents the construct and gives access to all construct-related information.

getConstructMass()

Returns the mass of the construct

Argument/Return	Type	Description
return	kg	The mass of the construct

getConstructIMass()

Returns the inertial mass of the construct, calculated as 1/3 of the trace of the inertial tensor.

Argument/Return	Type	Description
return	kg*m2	The inertial mass of the construct

getConstructCrossSection()

Returns the construct's cross sectional surface in the current direction of movement

Argument/Return	Type	Description
return	m2	The construct's surface exposed in the current direction of movement

getMaxKinematicsParametersAlongAxis()

Returns the construct max kinematics parameters in both atmo and space range, in newtons. Kinematics parameters designate here the maximal positive and negative base force the construct is capable of producing along the chosen Axisvector, as defined by the core unit or the gyro unit, if active. In practice, this gives you an estimate of the maximum thrust your ship is capable of producing in space or in atmosphere, as well as the max reverse thrust. These are theoretical estimates and correspond with the addition of the maxThrustBase along the corresponding axis. It might not reflect the accurate current max thrust capacity of your ship, which depends on various local conditions (atmospheric density, orientation, obstruction, engine damage, etc). This is typically used in conjunction with the control unit throttle to setup the desired forward acceleration.

Argument/Return	Type	Description
taglist	csv	Comma (for union) or space (for intersection) separated list of tags. You can set tags directly on the engines in the right-click menu.
CRefAxis	vec3	Axis along which to compute the max force (in construct reference)
return	vec4,Newton	The kinematics parameters in the order: atmoRange.FMaxPlus, atmoRange.FMaxMinus, spaceRange.FMaxPlus, spaceRange.FMaxMinus

getConstructWorldPos()

Returns the world position of the construct

Argument/Return	Type	Description
return	vec3	The xyz world coordinates of the construct core unit position

getConstructId()

Returns the construct unique ID

Argument/Return	Type	Description
return	int	The unique ID. Can be used with database.getConstruct to retrieve info about the construct

getWorldAirFrictionAngularAcceleration()

Returns the acceleration torque generated by air resistance

Argument/Return	Type	Description
return	vec3	The xyz world acceleration torque generated by air resistance

getWorldAirFrictionAcceleration()

Returns the acceleration generated by air resistance

Argument/Return	Type	Description
return	vec3	The xyz world acceleration generated by air resistance

spawnNumberSticker(nb,x,y,z,orientation)

Spawns a number sticker in the 3D world, with coordinates relative to the construct.

Argument/Return	Type	Description
nb	0-9	The number to display
x	meter	The x-coordinate in the construct. 0 = center
y	meter	The y-coordinate in the construct. 0 = center
z	meter	The z-coordinate in the construct. 0 = center
orientation	string	Orientation of the number. Possible values are "front", "side"
return	int	An index that can be used later to delete or move the item, -1 if error or maxnumber reached

spawnArrowSticker(x,y,z,orientation)

Spawns an arrow sticker in the 3D world, with coordinates relative to the construct.

Argument/Return	Type	Description
x	meter	The x-coordinate in the construct. 0 = center
y	meter	the y-coordinate in the construct. 0 = center
z	meter	The z-coordinate in the construct. 0 = center
orientation	string	Orientation of the arrow. Possible values are "up", "down", "north", "south", "east", "west"
return	int	An index that can be used later to delete or move the item, -1 if error or max number reached

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 referenced sticker.

Argument/Return	Type	Description
x	meter	The x-coordinate in the construct. 0 = center
y	meter	the y-coordinate in the construct. 0 = center
z	meter	The z-coordinate in the construct. 0 = center
index	int	Index of the sticker to move
return	int	1 in case of success, 0 otherwise

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

getElementIdList()

List of all the UIDs of the elements of this construct

Argument/Return	Type	Description
return	list	List of elements UIDs

getElementNameById(uid)

Name of the element, identified by its UID

Argument/Return	Type	Description
uid	int	The UID of the element
return	string	Name of the element

getElementTypeById(uid)

Type of the element, identified by its UID

Argument/Return	Type	Description
uid	int	The UID of the element
return	string	The type of the element

getElementHitPointsById(uid)

Current level of hit points of the element, identified by its UID

Argument/Return	Type	Description
uid	int	The UID of the element
return	float	Current level of hit points of the element

getElementMaxHitPointsById(uid)

Max level of hit points of the element, identified by its UID

Argument/Return	Type	Description
uid	int	The UID of the element
return	float	Max level of hit points of the element

getElementMassById(uid)

Mass of the element, identified by its UID

Argument/Return	Type	Description
uid	int	The UID of the element
return	kg	Mass of the element

getAltitude()

Altitude above sea level, with respect to the closest planet (0 in space)

Argument/Return	Type	Description
return	m	The sea level altitude

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
return	m/s2	The local gravity field vector in world coordinates

getWorldVertical()

Vertical unit vector along gravity, in world coordinates (0 in space)

Argument/Return	Type	Description
return	m/s2	The local vertical vector in world coordinates

getAngularVelocity()

The construct's angular velocity, in construct local coordinates

Argument/Return	Type	Description
return	rad/s	Angular velocity vector, in construct local coordinates

getWorldAngularVelocity()

The construct's angular velocity, in world coordinates

Argument/Return	Type	Description
return	rad/s	Angular velocity vector, in world coordinates

getAngularAcceleration()

The construct's angular acceleration, in construct local coordinates

Argument/Return	Type	Description
return	rad/s2	Angular acceleration vector, in construct local coordinates

getWorldAngularAcceleration()

The construct's angular acceleration, in world coordinates

Argument/Return	Type	Description
return	rad/s2	Angular acceleration vector, in world coordinates

getVelocity()

The construct's linear velocity, in construct local coordinates

Argument/Return	Type	Description
return	m/s	Linear velocity vector, in construct local coordinates

getWorldVelocity()

The construct's linear velocity, in world coordinates

Argument/Return	Type	Description
return	m/s	Linear velocity vector, in world coordinates

getWorldAcceleration()

The construct's linear acceleration, in world coordinates

Argument/Return	Type	Description
return	m/s2	Linear acceleration vector, in world coordinates

getAcceleration()

The construct's linear acceleration, in construct local coordinates

Argument/Return	Type	Description
return	m/s2	Linear acceleration vector, in construct local coordinates

getConstructOrientationUp()

The construct's current orientation up vector, in construct local coordinates

Argument/Return	Type	Description
return	vec3	Up vector of current orientation, in local coordinates

getConstructOrientationRight()

The construct's current orientation right vector, in construct local coordinates

Argument/Return	Type	Description
return	vec3	Right vector of current orientation, in local coordinates

getConstructOrientationForward()

The construct's current orientation forward vector ,in construct local coordinates

Argument/Return	Type	Description
return	vec3	Forward vector of current orientation, in local coordinates

getConstructWorldOrientationUp()

The construct's current orientation up vector, in world coordinates

Argument/Return	Type	Description
return	vec3	Up vector of current orientation, in world coordinates

getConstructWorldOrientationRight()

The construct's current orientation right vector, in world coordinates

Argument/Return	Type	Description
return	vec3	Right vector of current orientation, in world coordinates

getConstructWorldOrientationForward()

The construct's current orientation forward vector, in world coordinates

Argument/Return	Type	Description
return	vec3	Forward vector of current orientation, in world coordinates

Screen unit

Screen units can display any HTML code or text message, and 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.

addText(x,y,fontSize,text)

Displays the given text at the given coordinates in the screen, and returns an ID to move it later

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 a percentage 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

setHTML(html)

Set the whole screen HTML content (overrides anything already set)

Argument/Return	Type	Description
html	html	The HTML content to display

addContent(x,y,html)

Displays the given HTML content at the given coordinates in the screen, and returns an ID to move it later

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 integer id that can be used later to update/remove the added element

setSVG(svg)

Displays SVG code (anything that fits within a <svg> section), which overrides any preexisting content

Argument/Return	Type	Description
svg	svg	The SVG content to display, which fits inside a 1920x1080 canvas

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 setContent 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 percentage of the screen width
y	0..100	Vertical position, as a percentage of the screen height
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.

getMouseX()

Returns the x-coordinate of the position pointed at in the screen

Argument/Return	Type	Description
return	0..1	The x-position as a percentage of screen width; -1 if nothing is pointed at

getMouseY()

Returns the y-coordinate of the position pointed at in the screen

Argument/Return	Type	Description
return	0..1	The y-position as a percentage of screen height; -1 if nothing is pointed at

getMouseState()

Returns the state of the mouse click

Argument/Return	Type	Description
return	0 or 1	0 when the mouse is not clicked and 1 otherwise

clear()

Clear the screen

mouseDown(x,y)   event

Emitted when the player starts a click on the screen unit

Argument/Return	Type	Description
x	0..1	X-coordinate of the click in percentage of the screen width
y	0..1	Y-coordinate of the click in percentage of the screen height

mouseUp(x,y)   event

Emitted when the player releases a click on the screen unit

Argument/Return	Type	Description
x	0..1	X-coordinate of the click in percentage of the screen width
y	0..1	Y-coordinate of the click in percentage of the screen height

Detection zone unit

Detect the intrusion of any player inside the effect zone.

enter(id)   event

A player just entered the zone

Argument/Return	Type	Description
id	int	The ID of the player. Use database.getPlayer(ID).name to retrieve its name.

leave(id)   event

A player just left the zone

Argument/Return	Type	Description
id	int	The ID of the player. Use database.getPlayer(ID).name to retrieve its name.

Gyro unit

A general kinematic unit to obtain information about the ship orientation, velocity, and acceleration.

activate()

Selects this gyro as the main gyro used for ship orientation

deactivate()

Deselects this gyro as the main gyro used for ship orientation, using the core unit instead

toggle()

Toggle the activation state of the gyro

getState()

Returns the activation state of the gyro

Argument/Return	Type	Description
return	-	1 when the gyro is used for ship orientation, 0 otherwise

localUp()

The up vector of the gyro unit, in construct local coordinates

Argument/Return	Type	Description
return	-	Normalized up vector of the gyro unit, in construct local coordinates

localForward()

The forward vector of the gyro unit, in construct local coordinates

Argument/Return	Type	Description
return	-	Normalized forward vector of the gyro unit, in construct local coordinates

localRight()

The right vector of the gyro unit, in construct local coordinates

Argument/Return	Type	Description
return	-	Normalized right vector of the gyro unit, in construct local coordinates

worldUp()

The up vector of the gyro unit, in world coordinates

Argument/Return	Type	Description
return	-	Normalized up vector of the gyro unit, in world coordinates

worldForward()

The forward vector of the gyro unit, in world coordinates

Argument/Return	Type	Description
return	-	Normalized forward vector of the gyro unit, in world coordinates

worldRight()

The right vector of the gyro unit, in construct local coordinates

Argument/Return	Type	Description
return	-	Normalized right vector of the gyro unit, in world coordinates

getPitch()

The pitch value relative to the gyro orientation and the local gravity

Argument/Return	Type	Description
return	deg	The pitch angle in degrees, relative to the gyro orientation and the local gravity

getRoll()

The roll value relative to the gyro orientation and the local gravity

Argument/Return	Type	Description
return	deg	The roll angle in degrees, relative to the gyro orientation and the local gravity

Laser detector unit

Detect the hit of a laser.

getState()

Returns the current state of the laser detector

Argument/Return	Type	Description
return	-	0 if the detector has no laser pointed to it, 1 otherwise

laserHit()   event

A laser has just hit the detector

laserRelease()   event

All lasers have stopped hitting the detector

Laser emitter unit

Emits a laser ray that can be use to detect the passage of a player or on a laser detector unit.

activate()

Start the laser

deactivate()

Stop the laser

toggle()

Toggle the state of the laser

getState()

Returns the activation state of the laser

Argument/Return	Type	Description
return	-	1 when the laser is activated, 0 otherwise

Manual button

Emits a signal for the duration it is pressed.

getState()

Returns the activation state 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

toggle()

Toggle the state of the switch

getState()

Returns the activation state of the switch

Argument/Return	Type	Description
return	-	1 when the switch is on, 0 otherwise

pressed()   event

The button has been pressed

released()   event

The button has been released

Pressure tile unit

Emits a signal when a player walks on the tile.

getState()

Returns the activation state of the pressure tile

Argument/Return	Type	Description
return	-	1 when the tile is pressed, 0 otherwise

pressed()   event

Someone stepped on the tile

released()   event

Someone left the tile

Radar unit

List local constructs and access their ID.

getRange()

Returns the current range of the radar

Argument/Return	Type	Description
return	meter	The range

getEntries()

Returns the list of construct IDs currently detected in the range

Argument/Return	Type	Description
return	list	The list of construct IDs, can be used with database.getConstruct to retrieve info about each construct

getConstructOwner(id)

Return the player id of the owner of the given construct, if in range

Argument/Return	Type	Description
id	int	The ID of the construct
return	int	The player ID of the owner. Use database.getPlayer(ID) to retrieve info about it.

getConstructSize(id)

Return the size of the bounding box of the given construct, if in range

Argument/Return	Type	Description
id	int	The ID of the construct
return	vec3	The size of the construct in xyz-coordinates

getConstructType(id)

Return the type of the given construct

Argument/Return	Type	Description
id	int	The ID of the construct
return	string	The type of the construct,;can be 'static' or 'dynamic'

getConstructWorldPos(id)

Return the world coordinates of the given construct, if in range

Argument/Return	Type	Description
id	int	The ID of the construct
return	vec3	The xyz world coordinates of the construct

getConstructWorldVelocity(id)

Return the world coordinates of the given construct's speed, if in range

Argument/Return	Type	Description
id	int	The ID of the construct
return	vec3	The xyz world coordinates of the construct's velocity relative to absolute space

getConstructWorldAcceleration(id)

Return the world coordinates of the given construct's acceleration, if in range

Argument/Return	Type	Description
id	int	The ID of the construct
return	vec3	The xyz world coordinates of the construct's acceleration relative to absolute space

getConstructPos(id)

Return the radar local coordinates of the given construct, if in range

Argument/Return	Type	Description
id	int	The ID of the construct
return	vec3	The xyz radar local coordinates of the construct

getConstructVelocity(id)

Return the radar local coordinates of the given construct's speed, if in range

Argument/Return	Type	Description
id	int	The ID of the construct
return	vec3	The xyz radar local coordinates of the construct's velocity relative to absolute space

getConstructAcceleration(id)

Return the radar local coordinates of the acceleration of the given construct, if in range

Argument/Return	Type	Description
id	int	The ID of the construct
return	vec3	The xyz radar local coordinates of the construct's acceleration relative to absolute space

getConstructName(id)

Return the name of the given construct, if defined

Argument/Return	Type	Description
id	int	The ID of the construct
return	string	The name of the construct

enter(id)   event

Emitted when a construct enters the range of the radar unit

Argument/Return	Type	Description
id	int	ID of the construct; can be used with database.getConstruct to retrieve info about it

leave(id)   event

Emitted when a construct leaves the range of the radar unit

Argument/Return	Type	Description
id	int	ID of the construct; can be used with database.getConstruct to retrieve info about it

Telemeter unit

Measures the distance to an obstacle in front of it.

getDistance()

Returns the distance to the first obstacle in front of the telemeter

Argument/Return	Type	Description
return	meter	The distance to the obstacle. Returns -1 if there are no obstacles up to getMaxDistance.

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

Warp drive unit

Based on the principle of the Alcubierre drive, this unit creates a powerful negative energy-density field capable to distort space-time and transport your ship at hyper speeds through space.

activateWarp()

Start the warp drive, if a warp destination has been selected

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_c1,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

Argument/Return	Type	Description
vec_c1	vec3	The first column of the matrix M
vec_c2	vec3	The second column of the matrix M
vec_c3	vec3	The third column of the matrix M
vec_c0	vec3	The target column vector of the system
return	vec3	The vec3 solution of the above system

systemResolution2(vec_c1,vec_c2,vec_c0)

Solve the 2D linear system M*x=c0 where M is defined by its column vectors c1,c2

Argument/Return	Type	Description
vec_c1	vec3	The first column of the matrix M
vec_c2	vec3	The second column of the matrix M
vec_c0	vec3	The target column vector of the system
return	vec2	The vec2 solution of the above system

System

System is a virtual element that represents your computer. It gives access to events like key strokes or mouse movements that can be used inside your scripts. It also gives you access to regular updates that can be used to pace the execution of your script.

getActionKeyName(actionName)

Return the currently key bound to the given action. Useful to display tips.

Argument/Return	Type	Description
return	string	The key associated to the given action name

showScreen(bool)

Control the display of the control unit custom screen, where you can define customized display information in HTML. Note that this function is disabled if the player is not running the script explicitly (pressing F on the Control unit, vs. via a plug signal).

Argument/Return	Type	Description
bool	boolean	1 show the screen, 0 hide the screen

setScreen(content)

Set the content of the control unit custom screen with some HTML code. Note that this function is disabled if the player is not running the script explicitly (pressing F on the control unit, vs. via a plug signal).

Argument/Return	Type	Description
content	html	The HTML content you want to display on the screen widget. You can also use SVG here to make drawings.

createWidgetPanel(label)

Create an empty panel. Note that this function is disabled if the player is not running the script explicitly (pressing F on the Control unit, vs. via a plug signal).

Argument/Return	Type	Description
label	string	The title of the panel
return	string	The panel ID, or "" on failure

destroyWidgetPanel(panelId)

Destroy the panel. Note that this function is disabled if the player is not running the script explicitly (pressing F on the control unit, vs. via a plug signal).

Argument/Return	Type	Description
panelId	string	The panel ID
return	boolean	1 on success, 0 on failure.

createWidget(panelId, type)

Create an empty widget and add it to a panel. Note that this function is disabled if the player is not running the script explicitly (pressing F on the Control unit, vs. via a plug signal).

Argument/Return	Type	Description
panelId	string	The panel ID
type	string	Widget type, determining how it will display data attached to ID
return	string	The widget ID, or "" on failure

destroyWidget(widgetId)

Destroy the widget. Note that this function is disabled if the player is not running the script explicitly (pressing F on the control unit, vs. via a plug signal).

Argument/Return	Type	Description
widgetId	string	The widget ID
return	boolean	1 on success, 0 on failure.

createData(dataJson)

Create data. Note that this function is disabled if the player is not running the script explicitly (pressing F on the Control unit, vs. via a plug signal).

Argument/Return	Type	Description
dataJson	string	The data fields as JSON
return	string	The data ID, or "" on failure

destroyData(dataId)

Destroy the data. Note that this function is disabled if the player is not running the script explicitly (pressing F on the control unit, vs. via a plug signal).

Argument/Return	Type	Description
dataId	string	The data ID
return	boolean	1 on success, 0 on failure.

updateData(dataId, dataJson)

Update JSON associated to data. Note that this function is disabled if the player is not running the script explicitly (pressing F on the Control unit, vs. via a plug signal).

Argument/Return	Type	Description
dataId	string	The data ID
dataJson	string	The data fields as JSON
return	boolean	1 on success, 0 on failure.

addDataToWidget(dataId, widgetId)

Add data to widget. Note that this function is disabled if the player is not running the script explicitly (pressing F on the Control unit, vs. via a plug signal).

Argument/Return	Type	Description
dataId	string	The data ID
widgetId	string	The widget ID
return	boolean	1 on success, 0 on failure.

removeDataFromWidget(dataId, widgetId)

Remove data from widget. Note that this function is disabled if the player is not running the script explicitly (pressing F on the Control unit, vs. via a plug signal).

Argument/Return	Type	Description
dataId	string	The data ID
widgetId	string	The widget ID
return	boolean	1 on success, 0 on failure.

getMouseWheel()

Return the current value of the mouse wheel

Argument/Return	Type	Description
return	0..1	The current value of the mouse wheel

getMouseDeltaX()

Return the current value of the mouse delta X

Argument/Return	Type	Description
return	float	The current value of the mouse delta X

getMouseDeltaY()

Return the current value of the mouse delta Y

Argument/Return	Type	Description
return	float	The current value of the mouse delta Y

getMousePosX()

Return the current value of the mouse pos X

Argument/Return	Type	Description
return	float	The current value of the mouse pos X

getMousePosY()

Return the current value of the mouse pos Y

Argument/Return	Type	Description
return	float	The current value of the mouse pos Y

getThrottleInputFromMouseWheel()

Return the current value of the mouse wheel (for the throttle speedUp/speedDown action)

Argument/Return	Type	Description
return	0..1	The current input

getControlDeviceForwardInput()

Return the mouse input for the ship control action (forward/backward)

Argument/Return	Type	Description
return	-1..1	The current input

getControlDeviceYawInput()

Return the mouse input for the ship control action (yaw right/left)

Argument/Return	Type	Description
return	-1..1	The current input

getControlDeviceLeftRightInput()

Return the mouse input for the ship control action (right/left)

Argument/Return	Type	Description
return	float	The current value of the mouse delta Y

lockView()

Lock or unlock the mouse free look. Note that this function is disabled if the player is not running the script explicitly (pressing F on the Control unit, vs. via a plug signal).

Argument/Return	Type	Description
state	boolean	1 to lock and 0 to unlock

isViewLocked()

Return the lock state of the mouse free look

Argument/Return	Type	Description
return	boolean	1 when locked and 0 when unlocked

freeze(bool)

Freezes the character, liberating the associated movement keys to be used by the script. Note that this function is disabled if the player is not running the script explicitly (pressing F on the control unit, vs. via a plug signal).

Argument/Return	Type	Description
bool	boolean	1 freeze the character, 0 unfreeze the character

isFrozen()

Return the frozen status of the character (see 'freeze')

Argument/Return	Type	Description
return	boolean	1 if the character is frozen, 0 otherwise

getTime()

Return the current time since the arrival of the Arkship

Argument/Return	Type	Description
return	second	The current time in seconds, with a microsecond precision

getActionUpdateDeltaTime()

Return delta time of action updates (to use in ActionLoop)

Argument/Return	Type	Description
return	second	The delta time in seconds

getPlayerName(id)

Return the name of the given player, if in range of visibility

Argument/Return	Type	Description
id	int	The ID of the player
return	string	The name of the player

getPlayerWorldPos(id)

Return the world position of the given player, if in range of visibility

Argument/Return	Type	Description
id	int	The ID of the player
return	vec3	The coordinates of the player in world coordinates

print(msg)

Print a message in the Lua console

Argument/Return	Type	Description
msg	string	The message to print

actionStart(action)   event

Emitted when an action starts

Argument/Return	Type	Description
action	LUA action	The action, represented as a string taken among the set of predefined Lua-available actions (you can check the drop down list to see what is available)

actionStop(action)   event

Emitted when an action stops

Argument/Return	Type	Description
action	LUA action	The action, represented as a string taken among the set of predefined Lua-available actions (you can check the drop down list to see what is available)

actionLoop(action)   event

Emitted at each update as long as the action is maintained

Argument/Return	Type	Description
action	LUA action	The action, represented as a string taken among the set of predefined Lua-available actions (you can check the drop down list to see what is available)

update()   event

Game update event. This is equivalent to a timer set at 0 seconds, as updates will go as fast as the FPS can go.

flush()   event

physics update. Do not use to put anything else by a call to updateICC on your control unit, as many functions are disabled when called from 'flush'. This is only to update the physics (engine control, etc), not to setup some gameplay code.

Lua Changes and Additions - added 18/10/2021

Lua Improvements and Changes

• Changes in the management of construct and element referentials.
  For more consistency and to pave the way for future radar changes, the Lua now uses the construct building zone center as origin for all. This change affects local elements or player position and radar construct positions.
  We removed the quaternions from the Lua API are now exposing the direction vectors of the objects instead. This change was made to improve the overall player experience as not all players may be familiar with this mathematical notion of representing rotation.
  For more information you can read the Lua Improvements and Changes devblog, Part 1.
  
  • Added Lua functions on Core Unit:
    • core.getOrientationUnitId() : Returns the UID of the currently active orientation unit (the core unit or the gyro unit).
    • core.getVelocity(): Returns the construct's linear velocity, relative to its parent, in construct local coordinates.
    • core.getWorldVelocity(): Returns the construct's linear velocity, relative to its parent, in world coordinates.
    • core.getAbsoluteVelocity(): Returns the construct's absolute linear velocity in construct local coordinates.
    • core.getWorldAbsoluteVelocity(): Returns the construct's absolute linear velocity in world coordinates.
    • core.getParentPosition(): Returns the position of the construct's parent when docked in construct local coordinates.
    • core.getParentWorldPosition(): Returns the position of the construct's parent when docked in world coordinates.
    • core.getParentForward(): Returns the construct's parent forward direction vector in construct local coordinates.
    • core.getParentUp(): Returns the construct's parent up direction vector in construct local coordinates.
    • core.getParentRight(): Returns the construct's parent right direction vector in construct local coordinates.
    • core.getParentWorldForward(): Returns the construct's parent forward direction vector in world coordinates.
    • core.getParentWorldUp(): Returns the construct's parent up direction vector in world coordinates.
    • core.getParentWorldRight(): Returns the construct's parent right direction vector in world coordinates.
    • core.getElementForwardById( uid) : Returns the forward direction vector of the element identified by its UID in construct local coordinates.
    • core.getElementUpById( uid) : Returns the up direction vector of the element identified by its UID in construct local coordinates.
    • core.getElementRightById( uid) : Returns the right direction vector of the element identified by its UID in construct local coordinates.
  • Added Lua functions on Control Unit:
    • unit.getMasterPlayerPosition() : Returns the position of the player currently running the control unit in construct local coordinates (relative to the construct center instead of the control unit).
    • unit.getMasterPlayerWorldPosition() : Returns the position of the player currently running the control unit in world coordinates.
    • unit.getMasterPlayerForward() : Returns the forward direction vector of the player currently running the control unit in construct local coordinates.
    • unit.getMasterPlayerUp() : Returns the up direction vector of the player currently running the control unit in construct local coordinates.
    • unit.getMasterPlayerRight() : Returns the right direction vector of the player currently running the control unit in construct local coordinates.
    • unit.getMasterPlayerWorldForward() : Returns the forward direction vector of the player currently running the control unit in world coordinates.
    • unit.getMasterPlayerWorldUp() : Returns the up direction vector of the player currently running the control unit in world coordinates.
    • unit.getMasterPlayerWorldRight() : Returns the right direction vector of the player currently running the control unit in world coordinates.
  • Changed existing Lua functions:
    • core.getConstructOrientationForward() : Returns the forward direction vector of the active orientation unit in construct local coordinates.
    • core.getConstructOrientationUp() : Returns the up direction vector of the active orientation unit in construct local coordinates.
    • core.getConstructOrientationRight() : Returns the right direction vector of the active orientation unit in construct local coordinates.
    • core.getConstructWorldOrientationForward() : Returns the forward direction vector of the active orientation unit in world coordinates.
    • core.getConstructWorldOrientationUp() : Returns the up direction vector of the active orientation unit in world coordinates.
    • core.getConstructWorldOrientationForward() : Returns the right direction vector of the active orientation unit in world coordinates.
    • core.getConstructWorldPos() : Returns the position of the center of the construct in world coordinates (instead of orientation units position).
    • core.getElementPositionById(<int> uid) : Returns the position of the element, identified by its UID in construct local coordinates (instead of the construct corner).
  • Deprecated existing Lua functions:
    • core.getElementRotationById() : Deprecated.
    • unit.getMasterPlayerRelativePosition() : Deprecated.
    • unit.getMasterPlayerRelativeOrientation() : Deprecated.
  • Removed Lua functions that were previously deprecated:
    • unit.getOwnerRelativePosition(),
    • core.getElementList(),
    • core.getElementName(),
    • core.getElementType(),
    • core.getElementHitPoints(),
    • core.getElementMaxHitPoints(),
    • core.getElementMass(),
    • engine.getFuelRate(),
    • engine.isObstructed(),
    • gyro.setYawWorldReference(),
    • gyro.getYaw()
      
• Radar and transponder changes. There are some future backend radar changes in the planning stages now. In preparation, we have made some improvements to the Lua implementation of the radar. These should not only have a usability benefit but also improve performance as we reduce the usage of JSON strings to deliver payloads in Lua in favor of tables and values. We also heard your feedback that many of you found the transponder lacking in usability. To counter this,  we’ve added the transponder Lua API. For more information on the radar changes, you can read the Lua Improvements and Changes, Part 2 devblog.
  • Added Lua functions on radar unit:
    • radar.isOperational() : Returns 1 if the radar is not broken, works in the current environment and is not used by another control unit.
    • radar.getRange() : Returns the scan range of the radar unit.
    • radar.getIdentifyRanges() : Returns ranges to identify a target based on its core size.
    • radar.getConstructIds() : Returns the list of construct IDs in the scan range.
    • radar.getIdentifiedConstructIds() : Returns the list of identified construct IDs.
    • radar.getTargetId() : Returns the ID of the target construct.
    • radar.getConstructDistance( cid) : Returns the distance to the given construct.
    • radar.isConstructIdentified( cid) : Returns 1 if the given construct is identified.
    • radar.isConstructAbandoned( cid) : Returns 1 if the given construct was abandoned.
    • radar.getConstructCoreSize( cid) : Returns the core size of the given construct.
    • radar.getThreatTo( cid) : Returns the threat rate your construct is for the given construct.
    • radar.getThreatFrom( cid) : Returns the threat rate the given construct is for your construct.
    • radar.getConstructOwner( cid) : Returns a table with ID of the owner entities (player or organization) of the given construct if in range and if active transponder tags match.
    • radar.getConstructPos( cid) : Returns the position of the given construct in construct local coordinates if the active transponder tags match.
    • radar.getConstructWorldPos( cid) : Returns the position of the given construct in world coordinates if in range and if the active transponder tags match.
    • radar.getConstructSpeed( cid) : Returns the speed of the given construct if identified.
    • radar.getConstructAngularSpeed( cid) : Returns the angular speed of the given construct relative to your construct if identified.
    • radar.getConstructRadialSpeed( cid) : Returns the radial speed of the given construct relative to your construct if identified.
    • radar.getConstructMass( cid) : Returns the mass of the given construct if identified.
    • radar.getConstructInfos( cid) : Returns a list of working elements on the given construct if identified.
    • radar.getConstructVelocity( cid) : Returns the velocity vector of the given construct in construct local coordinates if identified and if the active transponder tags match.
    • radar.getConstructWorldVelocity( cid) : Returns the velocity vector of the given construct in world coordinates if identified and if the active transponder tags match.
  • Added Lua functions on Transponder Unit:
    • transponder.activate() : Activate the transponder.
    • transponder.deactivate() : Deactivate the transponder.
    • transponder.toggle() : Toggle the state of the transponder.
    • transponder.getState() : Returns the activation state of the transponder.
    • transponder.setTags( tags) : Set the tags list with up to eight entries. Returns 1 if the application was successful, 0 if the tag format is invalid.
    • transponder.getTags() : Returns the tag list.
    • transponder.toggled( active) event : Emitted when the transponder is started or stopped.
  • Deprecated existing Lua functions:
    • radar.getEntries() : has been renamed to getConstructIds for consistency.
  • The radar can now be connected to all controllers. You can only use radar for PvP on restricted links or you will not be able to identify or engage a target with it.
    
• Additional local libraries and update We took the time to add a few minor features to the Lua following some popular requests that we felt would gel well with the other changes. For more information on the libraries, you can read the Lua Improvements and Changes, Part 3 devblog.
  • Updated database Lua library:
    • database.getPlayer( pid) : Returns all information about a given player, identified by its ID.
    • database.getMasterPlayer( unit) : Returns all information about the player running the script.
    • database.getConstruct( cid) : Returns all information about a given construct, identified by its ID;  requires a radar to detect the construct.
    • database.getElement( core, uid) : Returns all information about a given element, identified by its ID, and requires a linked core unit.
  • Added the atlas Lua library containing all the information about the stellar bodies. (Check the devblog or check the file in your local Lua game folder.)
  • Added the event Lua library designed to help players create events in pure Lua. (Check the devblog or check the file in your local Lua game folder.)
    
• Other changes and improvements.
  • Ammo containers now have the same Lua API as other container elements.
  • Added a section on RenderScript and Lua screen units to the Codex.
  • Added Lua functions on Lua screen units:
    • getTime(): Return the time, in seconds, relative to the first execution.
    • getAvailableFontCount(): Return the number of fonts available to be used by render script.
    • getAvailableFontName(index): Return the name of the nth available font
  • Added additional Lua functions :
    • core.getConstructName() : Returns the name of the construct.
    • core.getCurrentPlanetId() : Returns the ID of the current close stellar body.
    • system.getPlayerName( pid) : Returns the name of the given player if in range of visibility or broadcasted by a transponder.
    • unit.getMasterPlayerOrgIds() : Returns the list of organization IDs of which the player running the script is a member.
    • system.getOrganizationName( oid) : Returns the name of the given organization, if known, e.g. broadcasted by a transponder.
    • system.getOrganizationTag( oid) : Returns the tag of the given organization, if known, e.g. broadcasted by a transponder.
  • Deprecated isFontLoaded() function due to a bug fix related to font loading.