Module ControlUnit
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 in on its CONTROL plugs. Kinematics control units like cockpit or commander seats are also capable of controlling the ship's engines via the update ICC method.
Element class:
- Generic: Programming Board
- RemoteControlUnit: Remote Controller
- CockpitHovercraftUnit: Hovercraft Seat
- CockpitFighterUnit: Cockpit
- CockpitCommandmentUnit: Command Seat
- PVPSeatUnit: Gunner Modules
- ECU: Emergency Controller
Displayed widget fields for Generic, ECU, and PVPSeatUnit element classes:
- showScriptError
- elementId
- controlMasterModeId
Additional widget fields for Cockpit and Remote classes:
- showHasBrokenFuelTank
- showOutOfFuel
- showOverload
- showSlowDown
- speed
- acceleration
- airDensity
- airResistance
- atmoThrust
- spaceThrust
- controlData
- currentBrake (not always shown)
- maxBrake (not always shown)
Extends: Element
Functions
| exit () | Stops the control unit's Lua code and exits. |
| setTimer (tag, period) | Set up a timer with a given tag in a given period. |
| stopTimer (tag) | Stop the timer with the given tag. |
| getAtmosphereDensity () | Returns the ambient atmosphere density. |
| getClosestPlanetInfluence () | Returns the influence rate of the closest planet. |
| getMasterPlayerPosition () | Deprecated: Return the position of the player currently running the control unit, in construct local coordinates. |
| getMasterPlayerWorldPosition () | Deprecated: Return the position of the player currently running the control unit, in construct local coordinates. |
| getMasterPlayerForward () | Deprecated: Returns the forward direction vector of the player currently running the control unit, in construct local coordinates. |
| getMasterPlayerUp () | Deprecated: Returns the up direction vector of the player currently running the control unit, in construct local coordinates. |
| getMasterPlayerRight () | Deprecated: Returns the right direction vector of the player currently running the control unit, in construct local coordinates. |
| getMasterPlayerWorldForward () | Deprecated: Returns the forward direction vector of the player currently running the control unit, in world coordinates. |
| getMasterPlayerWorldUp () | Deprecated: Returns the up direction vector of the player currently running the control unit, in world coordinates. |
| getMasterPlayerWorldRight () | Deprecated: Returns the right direction vector of the player currently running the control unit, in world coordinates. |
| getMasterPlayerId () | Deprecated: Return the ID of the player currently running the control unit. |
| getMasterPlayerOrgIds () | Deprecated: Returns the list of organization IDs of the player running the control unit. |
| getMasterPlayerMass () | Deprecated: Returns the mass of the active player. |
| getMasterPlayerParent () | Deprecated: Returns the id of the construct on which the active player is boarded. |
| hasDRM () | Checks if the control unit is protected by DRM. |
| isRemoteControlled () | Check if the construct is remote controlled. |
| 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. |
| setEngineThrust (taglist, thrust) | Sets the thrust values for all engines in the tag list. |
| getEngineThrust (taglist) | Returns the total thrust values of all engines in the tag list. |
| setAxisCommandValue (axis, commandValue) | Set the value of the throttle in the cockpit, which will be displayed in the cockpit widget when flying. |
| getAxisCommandValue (axis) | Get the value of the throttle in the cockpit. |
| setupAxisCommandProperties (axis, commandType, targetSpeedRanges) | Set the properties of an axis command. |
| setupControlMasterModeProperties (controlMasterModeId, displayName) | Deprecated: Set the display name of a master mode as shown in the UI. |
| getControlMasterModeId () | Deprecated: Get the current master mode in use. |
| getControlMode () | Returns the current control mode. |
| cancelCurrentControlMasterMode () | Cancel the current master mode in used. |
| isMouseControlActivated () | Check if a mouse control scheme is selected. |
| isMouseDirectControlActivated () | Check if the mouse control direct scheme is selected. |
| isMouseVirtualJoystickActivated () | Check if the mouse control virtual joystick scheme is selected. |
| activateGroundEngineAltitudeStabilization (targetAltitude) | The ground engines will stabilize to this altitude within their limits. |
| getSurfaceEngineAltitudeStabilization () | Return the ground engines stabilization altitude. |
| deactivateGroundEngineAltitudeStabilization () | The ground engines will behave like regular engine. |
| computeGroundEngineAltitudeStabilizationCapabilities () | Returns ground engine stabilization altitude capabilities (lower and upper ranges). |
| getThrottle () | Return the current throttle value. |
| setWidgetControlModeLabel (modeId, label) | Set the label of a control mode button shown in the control unit widget. |
| isAnyLandingGearExtended () | Deprecated: Check landing gear status. |
| isAnyLandingGearDeployed () | Checks if any landing gear is deployed. |
| extendLandingGears () | Deprecated: Extend/activate/drop the landing gears. |
| deployLandingGear () | Deploy all landing gears. |
| retractLandingGears () | Retract all landing gears. |
| isAnyHeadlightSwitchedOn () | Check construct lights status. |
| switchOnHeadlights () | Turn on the construct's headlights. |
| switchOffHeadlights () | Turn off the construct's headlights. |
| isMasterPlayerSeated () | Deprecated: Checks if the player currently running the control unit is seated. |
| getMasterPlayerSeatId () | Deprecated: Returns the UID of the seat on which the player currently running the control unit is sitting. |
| setSignalIn (plug, state) | Set the value of a signal in the specified IN plug of the element. |
| getSignalIn (plug) | Return the value of a signal in the specified IN plug of the element. |
| EVENT_tick (timerId) | Deprecated: Event: Emitted when the timer with id 'timerId' is ticking. |
| EVENT_onTimer (tag) | Event: Emitted when the timer with id 'tag' is ticking. |
| mockRegisterTimer (callback, filter) | Mock only, not in-game: Register a handler for the in-game `tick(timerId)` event. |
| mockDoTick (timerId) | Mock only, not in-game: Simulates a timer tick. |
| mockGetClosure () | Mock only, not in-game: Bundles the object into a closure so functions can be called with "." instead of ":". |
Functions
- 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 (tag, period)
-
Set up a timer with a given tag in a given period. This will start to trigger the 'onTimer' event with the
corresponding tag as an argument, to help you identify what is ticking, and when.
Parameters:
- tag string The tag of the timer, as a string, which will be used in the 'onTimer' 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 (tag)
-
Stop the timer with the given tag.
Parameters:
- tag string The tag of the timer to stop, as a string.
- getAtmosphereDensity ()
-
Returns the ambient atmosphere density.
Returns:
-
float
The atmosphere density (between 0 and 1).
- getClosestPlanetInfluence ()
-
Returns the influence rate of the closest planet.
Returns:
-
float
The closest planet influence rate (between 0 and 1).
- getMasterPlayerPosition ()
-
Deprecated: Return the position of the player currently running the control unit, in construct local coordinates.
This method is deprecated: player.getPosition should be used instead
Returns:
-
vec3
Master player position in construct local coordinates.
See also:
- getMasterPlayerWorldPosition ()
-
Deprecated: Return the position of the player currently running the control unit, in construct local coordinates.
This method is deprecated: player.getWorldPosition should be used instead
Returns:
-
vec3
Master player position in world coordinates.
See also:
- getMasterPlayerForward ()
-
Deprecated: Returns the forward direction vector of the player currently running the control unit, in construct local coordinates.
This method is deprecated: player.getForward should be used instead
Returns:
-
vec3
Master player forward direction vector in construct local coordinates.
See also:
- getMasterPlayerUp ()
-
Deprecated: Returns the up direction vector of the player currently running the control unit, in construct local coordinates.
This method is deprecated: player.getUp should be used instead
Returns:
-
vec3
Master player up direction vector in construct local coordinates.
See also:
- getMasterPlayerRight ()
-
Deprecated: Returns the right direction vector of the player currently running the control unit, in construct local coordinates.
This method is deprecated: player.getRight should be used instead
Returns:
-
vec3
Master player right direction vector in construct local coordinates.
See also:
- getMasterPlayerWorldForward ()
-
Deprecated: Returns the forward direction vector of the player currently running the control unit, in world coordinates.
This method is deprecated: player.getWorldForward should be used instead
Returns:
-
vec3
Master player forward direction vector in world coordinates.
See also:
- getMasterPlayerWorldUp ()
-
Deprecated: Returns the up direction vector of the player currently running the control unit, in world coordinates.
This method is deprecated: player.getWorldUp should be used instead
Returns:
-
vec3
Master player up direction vector in world coordinates.
See also:
- getMasterPlayerWorldRight ()
-
Deprecated: Returns the right direction vector of the player currently running the control unit, in world coordinates.
This method is deprecated: player.getWorldRight should be used instead
Returns:
-
vec3
Master player right direction vector in world coordinates.
See also:
- getMasterPlayerId ()
-
Deprecated: Return the ID of the player currently running the control unit.
This method is deprecated: player.getId should be used instead
Returns:
-
int
ID of the player running the control unit.
See also:
- getMasterPlayerOrgIds ()
-
Deprecated: Returns the list of organization IDs of the player running the control unit.
This method is deprecated: player.getOrgIds should be used instead
Returns:
-
list
Organization IDs of the player running the control unit.
See also:
- getMasterPlayerMass ()
-
Deprecated: Returns the mass of the active player.
This method is deprecated: player.getMass should be used instead
Returns:
-
float
The mass of the player in kilograms.
See also:
- getMasterPlayerParent ()
-
Deprecated: Returns the id of the construct on which the active player is boarded.
This method is deprecated: player.getParent should be used instead
Returns:
-
int
The parent id.
See also:
- hasDRM ()
-
Checks if the control unit is protected by DRM.
Returns:
-
0/1
1 if the control unit is protected by DRM.
- isRemoteControlled ()
-
Check if the construct is remote controlled.
Returns:
-
0/1
1 if the construct is remote controlled.
- 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.onFlush 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.
Note: This function must be used on a piloting controller in system.onFlush event.
Parameters:
- taglist string 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 vec3 The desired acceleration expressed in world coordinates in m/s2.
- angularAcceleration vec3 The desired angular acceleration expressed in world coordinates in rad/s2.
- 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.
- priority1SubTags string Comma (for union) or space (for intersection) separated list of tags of included engines to use as priority 1.
- priority2SubTags string Comma (for union) or space (for intersection) separated list of tags of included engines to use as priority 2.
- priority3SubTags string Comma (for union) or space (for intersection) separated list of tags of included engines to use as priority 3.
- toleranceRatioToStopCommand float When going through with priorities, if we reach a command that is achieved within this tolerance, we will stop there.
- setEngineThrust (taglist, thrust)
-
Sets the thrust values for all engines in the tag list.
Note: This function must be used on a piloting controller.
Parameters:
- taglist string Comma separated list of tags. You can set tags directly on the engines in the right-click menu.
- thrust float The desired thrust in newtons (note that for boosters, any non zero value here will set them to 100%).
- getEngineThrust (taglist)
-
Returns the total thrust values of all engines in the tag list.
Note: This function must be used on a piloting controller.
Parameters:
- taglist string Comma separated list of tags. You can set tags directly on the engines in the right-click menu.
Returns:
-
vec3
The total thrust in newtons.
- setAxisCommandValue (axis, commandValue)
-
Set the value of the throttle in the cockpit, which will be displayed in the cockpit widget when flying.
Note: This function must be used on a piloting controller.
Parameters:
- axis int Longitudinal = 0, lateral = 1, vertical = 2.
- commandValue float 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 the throttle in the cockpit.
Note: This function must be used on a piloting controller.
Parameters:
- axis int Longitudinal = 0, lateral = 1, vertical = 2.
Returns:
-
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, targetSpeedRanges)
-
Set the properties of an axis command. These properties will be used to display the command in UI.
Note: This function must be used on a piloting controller.
Parameters:
- axis int Longitudinal = 0, lateral = 1, vertical = 2.
- commandType int 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) in m/s.
- setupControlMasterModeProperties (controlMasterModeId, displayName)
-
Deprecated: Set the display name of a master mode as shown in the UI.
This method is deprecated: setWidgetControlModeLabel should be used instead
Parameters:
- controlMasterModeId int The master mode, 0=Travel Mode, 1=Cruise Control.
- displayName string The name of the master mode.
See also:
- getControlMasterModeId ()
-
Deprecated: Get the current master mode in use. The mode is set by clicking the UI button or using the
associated keybinding.
This method is deprecated: getControlMode should be used instead
Returns:
-
int
The current master mode (for now, only 2 are available, 0 and 1).
See also:
- getControlMode ()
-
Returns the current control mode. The mode is set by clicking the UI button or using the associated keybinding.
Note: This function must be used on a piloting controller.
Returns:
-
int
The current control mode (for now, only 2 are available, 0 and 1).
- cancelCurrentControlMasterMode ()
-
Cancel the current master mode in used.
Note: This function must be used on a piloting controller.
- isMouseControlActivated ()
-
Check if a mouse control scheme is selected.
Note: This function must be used on a piloting controller.
Returns:
-
0/1
1 if a mouse control scheme is selected.
- isMouseDirectControlActivated ()
-
Check if the mouse control direct scheme is selected.
Note: This function must be used on a piloting controller.
Returns:
-
0/1
1 if a mouse control direct scheme is selected.
- isMouseVirtualJoystickActivated ()
-
Check if the mouse control virtual joystick scheme is selected.
Note: This function must be used on a piloting controller.
Returns:
-
0/1
1 if a mouse control virtual joystick scheme is selected.
- 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.
Note: This function must be used on a piloting controller.
Parameters:
- targetAltitude float The stabilization target altitude in m.
- getSurfaceEngineAltitudeStabilization ()
-
Return the ground engines stabilization altitude.
Note: This function must be used on a piloting controller.
Returns:
-
float
The stabilization altitude in meters or 0 if none is set.
- deactivateGroundEngineAltitudeStabilization ()
-
The ground engines will behave like regular engine. This includes VerticalBooster and HoverEngine.
Note: This function must be used on a piloting controller.
- computeGroundEngineAltitudeStabilizationCapabilities ()
-
Returns ground engine stabilization altitude capabilities (lower and upper ranges).
Note: This function must be used on a piloting controller.
Returns:
-
vec2
Stabilization altitude capabilities for the least powerful engine and the most powerful engine.
- getThrottle ()
-
Return the current throttle value.
Note: This function must be used on a piloting controller.
Returns:
-
float
The throttle value between -100 and 100.
- setWidgetControlModeLabel (modeId, label)
-
Set the label of a control mode button shown in the control unit widget.
Note: This function must be used on a piloting controller.
Parameters:
- modeId int The control mode: 0 = Travel Mode, 1 = Cruise Control by default.
- label string The display name of the control mode, displayed on the widget button.
- isAnyLandingGearExtended ()
-
Deprecated: Check landing gear status.
This method is deprecated: isAnyLandingGearDeployed should be used instead
Returns:
-
0/1
1 if any landing gear is extended.
See also:
- isAnyLandingGearDeployed ()
-
Checks if any landing gear is deployed.
Returns:
-
0/1
1 if any landing gear is deployed.
- extendLandingGears ()
-
Deprecated: Extend/activate/drop the landing gears.
This method is deprecated: deployLandingGear should be used instead
See also:
- deployLandingGear ()
- Deploy all landing gears.
- retractLandingGears ()
- Retract all landing gears.
- isAnyHeadlightSwitchedOn ()
-
Check construct lights status.
Returns:
-
0/1
1 if any headlight is switched on.
- switchOnHeadlights ()
- Turn on the construct's headlights.
- switchOffHeadlights ()
- Turn off the construct's headlights.
- isMasterPlayerSeated ()
-
Deprecated: Checks if the player currently running the control unit is seated.
This method is deprecated: player.isSeated should be used instead
Returns:
-
0/1
1 if the player is seated.
See also:
- getMasterPlayerSeatId ()
-
Deprecated: Returns the UID of the seat on which the player currently running the control unit is sitting.
This method is deprecated: player.getSeatId should be used instead
Returns:
-
int
The UID of the seat, or 0 if not seated.
See also:
- setSignalIn (plug, state)
-
Set the value of a signal in the specified IN plug of the element.
Valid plug names are:
- "in" for the in signal (seems to have no actual effect when modified this way).
Parameters:
- plug string A valid plug name to set.
- state 0/1 The plug signal state
- getSignalIn (plug)
-
Return the value of a signal in the specified IN plug of the element.
Valid plug names are:
- "in" for the in signal.
Note: Only defined for Programming Board and ECU.
Parameters:
- plug string A valid plug name to query.
Returns:
-
0/1
The plug signal state
- EVENT_tick (timerId)
-
Deprecated: Event: Emitted when the timer with id 'timerId' is ticking.
Note: This is documentation on an event handler, not a callable method.
This event is deprecated: EVENT_onTimer should be used instead.
Parameters:
- timerId string The ID (int) of the timer that just ticked (see setTimer to set a timer with a given ID)
See also:
- EVENT_onTimer (tag)
-
Event: Emitted when the timer with id 'tag' is ticking.
Note: This is documentation on an event handler, not a callable method.
Parameters:
- tag string The tag of the timer that just ticked (see setTimer to set a timer with a given tag).
See also:
- mockRegisterTimer (callback, filter)
-
Mock only, not in-game: Register a handler for the in-game `tick(timerId)` event.
Parameters:
- callback function The function to call when the timer ticks.
- filter string The timerId to filter on, or "*" for all.
Returns:
-
int
The index of the callback.
See also:
- mockDoTick (timerId)
-
Mock only, not in-game: Simulates a timer tick.
Parameters:
- timerId string The ID of the timer that ticked.
- mockGetClosure ()
-
Mock only, not in-game: Bundles the object into a closure so functions can be called with "." instead of ":".
Returns:
-
table
A table encompasing the api calls of object.
See also: