Dual Universe Lua Scripting

From Dual Universe Wiki
Jump to: navigation, search


Contents

Introduction[edit | edit source]

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[edit | edit source]

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


Physics scripting, how is your ship flying?[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

Generic element[edit | edit source]

All elements share the same generic methods described below:

show()[edit | edit source]

Show the element widget in the in-game widget stack

hide()[edit | edit source]

Hide the element widget in the in-game widget stack

getData()[edit | edit source]

Get element data as JSON

Argument/Return Type Description
return string Data as JSON.

getDataId()[edit | edit source]

Get element data ID

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

getWidgetType()[edit | edit source]

Get widget type compatible with the element data

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

getIntegrity()[edit | edit source]

The element integrity between 0 and 100

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

getHitPoints()[edit | edit source]

The element current hit points (0 = destroyed)

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

getMaxHitPoints()[edit | edit source]

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

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

getId()[edit | edit source]

A construct unique ID for the element

Argument/Return Type Description
return - The element ID

getMass()[edit | edit source]

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()[edit | edit source]

The class of the element

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

setSignalIn(plug, state)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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[edit | edit source]

Stores items

getItemsMass()[edit | edit source]

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()[edit | edit source]

Returns the container self mass

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

Control unit[edit | edit source]

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()[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

Stop the timer with the given ID

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

getAtmosphereDensity()[edit | edit source]

Returns the local atmosphere density, between 0 and 1

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

getClosestPlanetInfluence()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

Cancel the current master mode in used

isAnyLandingGearExtended()[edit | edit source]

Check landing gear status

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

extendLandingGears()[edit | edit source]

Extend/activate/drop the landing gears

retractLandingGears()[edit | edit source]

Retract/deactivate the landing gears

isMouseControlActivated()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

Check lights status

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

switchOnHeadlights()[edit | edit source]

switchOn the lights

switchOffHeadlights()[edit | edit source]

switchOff the lights

isRemoteControlled()[edit | edit source]

Check if the construct is remote controlled

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

activateGroundEngineAltitudeStabilization(targetAltitude)[edit | edit source]

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()[edit | edit source]

return the ground engines stabilization altitude

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

deactivateGroundEngineAltitudeStabilization()[edit | edit source]

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

computeGroundEngineAltitudeStabilizationCapabilities()[edit | edit source]

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()[edit | edit source]

return the current throttle value

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

tick(timerId)   event[edit | edit source]

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[edit | edit source]

Stores key/value pairs in a persistent way.

clear()[edit | edit source]

Clear the data bank

getNbKeys()[edit | edit source]

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

Argument/Return Type Description
return int The number of keys

getKeys()[edit | edit source]

Returns all the keys in the data bank

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

hasKey(key)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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[edit | edit source]

A door that can be opened or closed.

activate()[edit | edit source]

Open the door

deactivate()[edit | edit source]

Close the door

toggle()[edit | edit source]

Toggle the state of the door

getState()[edit | edit source]

Returns the activation state of the door

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

Engine unit[edit | edit source]

An engine is capable to produce a force and/or a torque to move your construct.

activate()[edit | edit source]

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

deactivate()[edit | edit source]

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

toggle()[edit | edit source]

Toggle the state of the engine

getState()[edit | edit source]

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)[edit | edit source]

Set the engine thrust between 0 and maxThrust

Argument/Return Type Description
thrust Newton The engine thrust

getMaxThrustBase()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

Returns the current thrust level of the engine

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

torqueAxis()[edit | edit source]

Returns the engine torque axis

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

thrustAxis()[edit | edit source]

Returns the engine thrust direction

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

getDistanceToObstacle()[edit | edit source]

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()[edit | edit source]

Is the engine out of fuel?

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

hasBrokenFuelTank()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

Tags of the engine

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

setTags(tags)[edit | edit source]

Set the tags of the engine

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

getFuelConsumption()[edit | edit source]

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[edit | edit source]

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

activate()[edit | edit source]

Fire the firework

setExplosionDelay(t)[edit | edit source]

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

Argument/Return Type Description
t second The delay before explosion

setLaunchSpeed(v)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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[edit | edit source]

A forcefield to create an uncrossable energy barrier.

activate()[edit | edit source]

Activate the field

deactivate()[edit | edit source]

Deactivate the field

toggle()[edit | edit source]

Toggle the state

getState()[edit | edit source]

Returns the activation state of the field

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

Landing gear unit[edit | edit source]

A landing gear that can be opened or closed.

activate()[edit | edit source]

Open the landing gear

deactivate()[edit | edit source]

Close the landing gear

toggle()[edit | edit source]

Toggle the state of the gear

getState()[edit | edit source]

Returns the activation state of the landing gear

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

Light unit[edit | edit source]

Emits a source of light.

activate()[edit | edit source]

Switches the light on

deactivate()[edit | edit source]

Switches the light off

toggle()[edit | edit source]

Toggle the state of the light

getState()[edit | edit source]

Returns the activation state of the light

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

Anti gravity generator unit[edit | edit source]

Generates graviton condensates to power anti-gravity pulsors

activate()[edit | edit source]

Start the anti-g generator

deactivate()[edit | edit source]

Stop the anti-g generator

toggle()[edit | edit source]

Toggle the state of the anti-g generator

getState()[edit | edit source]

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)[edit | edit source]

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()[edit | edit source]

Return the base altitude for the anti-gravity field

Argument/Return Type Description
return m The base altitude

Industry unit[edit | edit source]

Can mass-produce produce any item/element.

start()[edit | edit source]

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

startAndMaintain()[edit | edit source]

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()[edit | edit source]

Start the production of numBatches and then stop

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

softStop()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

Get the efficiency of the industry

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

getUptime()[edit | edit source]

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[edit | edit source]

Emitted when the industry unit has completed a run

statusChanged(status)   event[edit | edit source]

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[edit | edit source]

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()[edit | edit source]

Returns the rank of the currently active OUT plug

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

next()[edit | edit source]

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

Emitter unit[edit | edit source]

This unit is capable of emitting messages on channels.

send(channel,message)[edit | edit source]

Send a message on the given channel

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

getRange()[edit | edit source]

Returns the emitter range

Argument/Return Type Description
return meter The range

Receiver unit[edit | edit source]

Receives messages on given channels.

getRange()[edit | edit source]

Returns the receiver range

Argument/Return Type Description
return meter The range

receive(channel,message)   event[edit | edit source]

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[edit | edit source]

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

getConstructMass()[edit | edit source]

Returns the mass of the construct

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

getConstructIMass()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

Returns the world position of the construct

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

getConstructId()[edit | edit source]

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()[edit | edit source]

Returns the acceleration torque generated by air resistance

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

getWorldAirFrictionAcceleration()[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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()[edit | edit source]

List of all the UIDs of the elements of this construct

Argument/Return Type Description
return list List of elements UIDs

getElementNameById(uid)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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()[edit | edit source]

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

Argument/Return Type Description
return m The sea level altitude

g()[edit | edit source]

Local gravity intensity

Argument/Return Type Description
return m/s2 The gravitation acceleration where the construct is located

getWorldGravity()[edit | edit source]

Local gravity vector in world coordinates

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

getWorldVertical()[edit | edit source]

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()[edit | edit source]

The construct's angular velocity, in construct local coordinates

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

getWorldAngularVelocity()[edit | edit source]

The construct's angular velocity, in world coordinates

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

getAngularAcceleration()[edit | edit source]

The construct's angular acceleration, in construct local coordinates

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

getWorldAngularAcceleration()[edit | edit source]

The construct's angular acceleration, in world coordinates

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

getVelocity()[edit | edit source]

The construct's linear velocity, in construct local coordinates

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

getWorldVelocity()[edit | edit source]

The construct's linear velocity, in world coordinates

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

getWorldAcceleration()[edit | edit source]

The construct's linear acceleration, in world coordinates

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

getAcceleration()[edit | edit source]

The construct's linear acceleration, in construct local coordinates

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

getConstructOrientationUp()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

Clear the screen

mouseDown(x,y)   event[edit | edit source]

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[edit | edit source]

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[edit | edit source]

Detect the intrusion of any player inside the effect zone.

enter(id)   event[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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

activate()[edit | edit source]

Selects this gyro as the main gyro used for ship orientation

deactivate()[edit | edit source]

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

toggle()[edit | edit source]

Toggle the activation state of the gyro

getState()[edit | edit source]

Returns the activation state of the gyro

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

localUp()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

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[edit | edit source]

Detect the hit of a laser.

getState()[edit | edit source]

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[edit | edit source]

A laser has just hit the detector

laserRelease()   event[edit | edit source]

All lasers have stopped hitting the detector

Laser emitter unit[edit | edit source]

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

activate()[edit | edit source]

Start the laser

deactivate()[edit | edit source]

Stop the laser

toggle()[edit | edit source]

Toggle the state of the laser

getState()[edit | edit source]

Returns the activation state of the laser

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

Manual button[edit | edit source]

Emits a signal for the duration it is pressed.

getState()[edit | edit source]

Returns the activation state of the button

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

pressed()   event[edit | edit source]

The button has been pressed

released()   event[edit | edit source]

The button has been released

Manual switch unit[edit | edit source]

A manual switch that can be in an on/off state.

activate()[edit | edit source]

Activate the switch on

deactivate()[edit | edit source]

Deactivate the switch

toggle()[edit | edit source]

Toggle the state of the switch

getState()[edit | edit source]

Returns the activation state of the switch

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

pressed()   event[edit | edit source]

The button has been pressed

released()   event[edit | edit source]

The button has been released

Pressure tile unit[edit | edit source]

Emits a signal when a player walks on the tile.

getState()[edit | edit source]

Returns the activation state of the pressure tile

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

pressed()   event[edit | edit source]

Someone stepped on the tile

released()   event[edit | edit source]

Someone left the tile

Radar unit[edit | edit source]

List local constructs and access their ID.

getRange()[edit | edit source]

Returns the current range of the radar

Argument/Return Type Description
return meter The range

getEntries()[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

Measures the distance to an obstacle in front of it.

getDistance()[edit | edit source]

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()[edit | edit source]

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[edit | edit source]

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()[edit | edit source]

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

Library[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

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()[edit | edit source]

Return the current value of the mouse wheel

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

getMouseDeltaX()[edit | edit source]

Return the current value of the mouse delta X

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

getMouseDeltaY()[edit | edit source]

Return the current value of the mouse delta Y

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

getMousePosX()[edit | edit source]

Return the current value of the mouse pos X

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

getMousePosY()[edit | edit source]

Return the current value of the mouse pos Y

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

getThrottleInputFromMouseWheel()[edit | edit source]

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()[edit | edit source]

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

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

getControlDeviceYawInput()[edit | edit source]

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

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

getControlDeviceLeftRightInput()[edit | edit source]

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()[edit | edit source]

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()[edit | edit source]

Return the lock state of the mouse free look

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

freeze(bool)[edit | edit source]

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()[edit | edit source]

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

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

getTime()[edit | edit source]

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()[edit | edit source]

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

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

getPlayerName(id)[edit | edit source]

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)[edit | edit source]

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)[edit | edit source]

Print a message in the Lua console

Argument/Return Type Description
msg string The message to print

actionStart(action)   event[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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.