Yoarii's Flight system for Dual Universe

Important

I have quit playing Dual Universe and will not return. I will not update the script further. This repository and those brought in via Git-submodules are made public so that someone else may continue the development and so that if NovaQuark brakes the Lua API, the script can be fixed without my involvement.

Note: This manual is always for the latest version of the script.

Please read the entire manual before attempting to perform an installation, there are important information throughout that will impact the choices you make.

Yoarii's Flight system for Dual Universe

Overview

The goal of this project was initially to write a flight system capable of working as what is known as a shaft-less space elevator. i.e. vertical movement around a predefined path. The chosen design does however allow for more than just that and is capable of movement in any direction, within limits of the construct it operates. The original target of only vertical movement along the gravity vector was thus surpassed and it is possible to go in a straight line at an angle from the vertical gravity vector. Further, it also allows you to do up-and-over maneuvers where the construct parks itself on a space platform from whichever direction you desire.

Required elements (for Do-It-Yourself kits)

A telemeter named "FloorDetector", pointing downwards
A data bank named "Routes"
Optional data bank named "Settings"
Screen (optional, but strongly recommended)
Atmospheric engines are required in all direction, except in the upward direction as gravity does the job. Upward engines are used if present.
In space, you need engines in all directions.
Aim for 3g for upward lift when fully loaded.
Don't forget the brakes

Optional parts

Emitter
Receiver
Atmospheric Radar
Space Radar

Link order

These elements must be linked first, in the following order for things to work as expected and to be reasonably future proofed for later versions of the script when/if support for radar events are introduced.

Receiver
Space Radar
Atmospheric Radar

Routes and Waypoints

Routes is an important concept for this flight system as they are what guides the construct between positions. A route consists of two or more waypoints, a start, an end, and any number of waypoints in-between. A waypoint specifies a position in the world. When added to a route a waypoint is associated with other attributes, such as alignment direction and maximum speed. A route can also contain anonymous waypoints; these exists only in one route and can't be reused. When traveling along a route, the next waypoint dictates the direction the constructs forward should point in. Normally this is towards the waypoint itself, but it can be locked to another direction. When a route is run in reverse, the previous waypoint determines the alignment direction so that the the construct performs each movement in reverse along the entire route. When a route is activated, the closest point is calculated and the construct will first move to that point before moving to the next waypoint.

Route vs Floor mode

By default, the screen will show two buttons for the start and end of each available route. Pressing either will active the route. Below the two buttons, there's a button named "Waypoints" that shows the individual waypoints in the route. If you would rather have a specific route shown as a list of waypoints to select from at startup, i.e. floor-mode, use the command set -showFloor 'nameOfYourRoute'. To revert to the default behavior, type set -showFloor '-'. Only waypoints that have not been marked as unselectable via the route editor are shown.

Waypoint alignment

The construct will align towards the next point in the route (see setting yawAlignmentThrustLimiter), unless that point has a locked alignment direction, in which case the construct will keep that direction while approaching the waypoint. The construct will also automatically lock and hold the direction if the next target point is nearly straight up or down from its current position, also when issued a move command.

Skippable waypoints

You can mark a waypoint in the route as skippable. Doing so makes the system ignore that point when calculating the path to travel to the selected waypoint. However, even if a waypoint is marked as such, it is still used to find the closest point on the complete path when a route is activated.

Enclosures

If you intend to build an enclosure for the construct remember that physics in Dual Universe creates a hit box around constructs in the shape of a box, not the visual contours. As such your enclosure must be able to fit a box the size of the extreme distances of the construct on all three axes. Leave a margin at least a full voxel (moving vertices does not count, the entire voxel must be deleted)

Floors for parking; ground and space

When creating floors for any dynamic construct, ensure that the floor fully encompasses the dynamic construct and it does NOT cross core boundaries or it might clip through and fall, or worse, explode.

Cargo mass capacity

The cargo mass ratings given for constructs are given in raw mass values, i.e. not taking mass reduction talents into account. As such, do not blindly look at the mass shown in the inventory interface of DU. Instead, inspect the item/stack and look at the actual mass of the stack - the DU interface show only 75% of the actual mass when the construct is fully boosted.

The rating is based on these prerequisites:

Take off from near water level at 100% atmosphere.
Gravity of 1g.
Atmosphere thickness of Alioth.
Zero personal talents.
Construct full boosted with lvl 5 flight/container/tank skills.

From the above it should be understood that taking off from lower atmosphere (such as from a higher point, or a low-atmosphere planet) makes a big difference in capacity. Likewise, coming into atmosphere and stopping at higher up/in low atmosphere is also subject to the same altered performance.

Automatic shutdown

When the last point in the route is reached, and the telemeter reports a distance less than the one configured, the script will automatically shutdown.

Integrations

Gate control

You can setup automatic control of gates or doors, completely automating the travel, this gets you:

Automatically opened gates/doors on route activation.
Automatically closed gates/doors when arriving at the final waypoint (also a mid-point in floor mode).

You do not get automatically closed gates/doors on leaving the start of the route.

Elements needed on the space/static construct:

1x Receiver
1x Emitter
1x Programming Board
1x Relay (2x if you want to control more than one gate/door)
1x XOR operator
1x OR operator
1x 2-Counter
2x Manual Switch
Any number of gates/doors. At least four medium sliding doors if you're setting up a space dock for anything but a very small elevator.

Note:

Doors must be mounted such that they open (i.e. are out of the way of the elevator) when the button that controls them is lit.

Link the following elements on the ground/space construct as follows. You must link the element in the order below. Names in [square brackets] identify different elements of the same type, make sure to link to/from the correct one.

PB -> Receiver (green link)
PB -> Emitter (green link)
PB -> Manual Switch [hold] (green link)
PB -> Manual Switch [gates] (green link)
Manual Switch [hold] -> OR (blue link)
Receiver -> Relay (blue link)
Relay -> 2-counter (blue link)
Relay -> XOR (blue link)
2-counter -> XOR (blue link)
XOR -> OR (blue link)
OR -> PB (blue link)
Manual Switch [gates] -> Relay and/or gates/doors

*PB = Programming Board

Now copy the contents of the latest released Json file from here, right-click on the Programming Board, open the Advanced menu and click Paste Lua Configuration from clipboard. Ensure you get a success message on screen.

Right-click on the programming board and click Edit Lua parameters and set a unique communication channel, using alpha numerical characters only, no spaces. Ensure you keep the quotation marks! The channel must be unique per elevator/gate set or they will interfere with each other. Click OK to close the dialog. Now activate the programming board to complete the setup of the worker side, look in Lua chat for any errors printed and adjust accordingly.

Note

Gate Control is only active while running a route, not when manually controlling the construct with keys or via the move command.

Gates are only opened at route activation if closer to a controlled point than configured with setting openGateMaxDistance.

Gate control only works as long as the receiving elements are loaded. Elements such as those used on the receiver side are unloaded by the game at fairly short distances so place them as close to the elevator as possible. In the case of multi-floor, a central position to all waypoints is recommended

Gate control adds a few seconds after activating a route and before any movements happens. Look in Lua chat to see if it is waiting for the doors to open or close.

Elevator side

The receiver must be linked on the first slot of the remote controller. If your construct didn't come with this pre-linked, you do this easiest by removing all links, then linking from the Remote Controller to the Receiver, followed by linking the space radar, atmospheric radar, Core, Telemeter, Screen, Databank(s) and Emitter.

In Lua chat, you must run the command set -commChannel CHANNEL, replacing CHANNEL with the same channel name you used on the programming board on the space/static construct so that they can communicate with each other. Now restart the elevator so that the channel can be applied. Next, for each point in the route you want the elevator to control the gates, open the route for editing then click to enable gate control using the on-screen UI for the points you want to control gates at. Finish by saving the route.

For example, the most common setup is to have gates/doors only at the space station. If we assume the first point in the route is at the ground and the route consists of two points, run route-set-pos-option -ix 2 -toggleGate to toggle the gate control for the second point.

Controlling switches

If linked to the remote controller, the script can control two Manual Switches, depending on their names:

A Manual Switch named "FollowGate" will be activated whenever the gate control opens the gates and deactivated when gates are closed.
A Manual Switch named "FollowRemote" will follow the state of the Remote Controller.

Fuel gauges

Fuel gauges on the HUD are sorted in alphabetical order so rename them if you want them in a certain order.

Installation as an elevator (ground to space)

Automatically aligning and positioning using two elements - recommended procedure

The easiest way to position and align the elevator to a static construct is to let it do it itself. All it needs are some coordinates for the center position and the forward direction. To get these numbers, follow these steps:

Place an Adjustor XS at the position you want the elevator to be. Name this element center. Note, this is relative to the center of build area, where the "blue icon" is displayed, not the visual center.
Place a second Adjustor XS beside the first one, in the direction you want to the elevator to align to. Name this element forward.
Place a Programming Board on the static construct that will contain the dock/cradle/landing pad of the elevator.
Link the programming board to the core, then to a screen. Order is important.
Paste the code below into unit -> start
Start the Programming Board and copy the command from the screen (CTRL-L to to open editor while pointing to the screen).
- The command is the part in the text = .... line of the screen code. Do not copy the quotation marks.
Start the elevator, enter manual control mode to prevent it to shutdown automatically when near ground.
- You may want to adjust the heightMargin argument to fit your need. It controls how much it will move up from its start point before moving over to the center position.
Paste the command into Lua-chat and press enter to perform the operation. The elevator will never reach the final position as it will be below, but it will come to rest on the static construct.
Once in place, either turn turn off the elevator or edit routes as needed. The position the elevator is in should work well as a starting point for a route.

local Vec3 = require("cpml/vec3")

function localToWorld(localCoord)
    local xOffset = localCoord.x * Vec3(construct.getWorldOrientationRight())
    local yOffset = localCoord.y * Vec3(construct.getWorldOrientationForward())
    local zOffset = localCoord.z * Vec3(construct.getWorldOrientationUp())
    return xOffset + yOffset + zOffset + Vec3(construct.getWorldPosition())
end

function getCoordsOfElement(name)
    for _, id in ipairs(slot1.getElementIdList()) do
        if slot1.getElementNameById(id) == name then
            return localToWorld(Vec3(slot1.getElementPositionById(id)))
        end
    end
    return nil
end

local center = getCoordsOfElement("center")
local forward = getCoordsOfElement("forward")

if not (center and forward) then
    system.print("Missing center or forward element")
    unit.exit()
    return
end

local cmd = string.format("position-above -heightMargin 15 -cx %0.14f -cy %0.14f -cz %0.14f -fx %0.14f -fy %0.14f -fz %0.14f",
    center.x, center.y, center.z,
    forward.x, forward.y, forward.z)

slot2.activate()
slot2.setCenteredText(cmd)

unit.exit()

Creating a route

Decide on what distance above (not height above sea level) you want the route to stop at.
Decide on a name for the route. You can use spaces in it, but you must surround it with single quotes, like so: 'a name'. Double quotes do currently not work due to a bug in DU. Keep the name at 14 characters or less so it fits on the screen.
Activate the elevator.
In Lua chat, type: create-vertical-route 'route name' -distance 12345, replacing values as appropriate.
- If this isn't your first elevator, and you want this one to run parallel to the first one, add the -distance, -x, -y, and -z arguments you get using the instructions in the "Travel vector for additional elevators" section.
  
  Example: create-vertical-route 'route name' -distance 100000 -x 0.1234 -y 0.5678 -z 0.9012

The screen will now show the name of your route with two buttons, one for the start (ground) and end (space). Simply clicking these buttons will make the elevator move to those respective locations.

You can now expand on this route by adding additional points to it (see Key-bindings, Manual Controls and Lua console commands), do do up-and-over maneuvers, sideways movements etc., to fit your exact needs. Needless to say, any additional movement increases fuel consumption. This is especially true in atmosphere where gravity generally is higher.

Route editor

The on-screen route editor (accessible from the main screen) allows you to perform the following operations on a route.

Add a waypoint to a route, with or without direction information.
Remove a waypoint from a route.
Reorder waypoints in a route.
Set a waypoint as skippable, allowing it to be skipped when moving along the route.
Set a waypoint as unselectable, which will hide it from from the floor-selection screen.
Add current pos with or without direction information.
Discard any changes made to the route.
Save the route.

If there are more waypoints that fit on a single screen, use the arrows below the list to switch to another page.

Custom travel vector for additional elevators

To ensure that elevators end up at the same relative distances in space as they have on the ground, you need to make them use the same travel direction. To do so, follow these instructions:

Note: This only looks at the two first points in the route. If you want to use other points, you can use the sub-pos command.

Select one elevator as the reference elevator.
Activate the elevator
Choose the route you want to use as a reference and type the following command in Lua chat, replacing with your route name.

get-parallel-from-route YOUR_ROUTE_NAME

This will print something like this:

[I] -distance 123456 -x 0.123456 -y 0.456789 -z 0.789012
Copy this from the chat (right click on the Lua chat tab to access menu) and paste it into your favorite text editor and extract the relevant parts after the [I], you'll find it at the very end of the text. Ensure that you get all the decimals.

See the accuracy section for additional information.

Space core placement

When placing the space core/construct, using the snapping mode on the elevator can make it much easier to align it correctly. Just keep in mind where the parking spot is meant to be etc.

Hint: To activate snapping mode, point into empty space, then click middle mouse button, then left click on the elevator to select it as a reference construct and move the new core/construct using normal adjustment keys. If you're doing it alone, the ECU must be holding the elevator in place, you can't actively run the remote controller while deploying a core/construct.

Key bindings

Key	Description	Lua key binding / Modifier
Alt + 0	Cycles radar sorting methods (see Lua chat for details)	Option 0
Alt + Shift + 0	Show/hides radar widget	Option 0 / Shift
Alt + Shift + 8	Show/hides widgets with diagnostic info as well as the build helper	Option 8 / Shift
Alt + Shift + 9	Locks/unlocks player movement / enters/exists manual control mode	Option 9 / Shift

By default option 1..9 means ALT-key plus keys 1 through 9, configured in the the game settings.

Manual Controls (when player movement is locked)

Key	Description	Lua key binding / Modifier
A	Turn left	yawleft
D	Turn right	yawright
W	Move forward	forward
S	Move backwards	backward
C	Move down	down
B	While held down, activates rocket boosters (only while in manual control)	boosters
G	Engage parking	gear
CTRL + SHIFT + G	Save current position perform an undock procedure. (EXPERIMENTAL)	gear
SHIFT + G	Perform an auto-dock procedure (EXPERIMENTAL)	gear
Space	Move up	up
Alt + A / Q	Strafe left	strafeleft, left
Alt + D / E	Strafe right	straferight, right
Mouse scroll wheel	Increase/decrease throttle/acceleration
Middle mouse button	Toggle forward thrust (if setting `allowForwardToggle` is set)

Note: For smaller constructs, autoPitch may be something that you want to enable so that the construct tilts when moving forward and up/down.

Manual control of heavy constructs are much less accurate (especially during vertical movements). Don't expect the same maneuverability as a tiny 1.5t construct. Rocket boosters are automatically turned off whenever brakes activate.

Lua console commands

Command	Parameters/options	Unit/type	Parameter Optional	Description
move				Initiates a movement relative to the current position
	-f	meter	Y	Forward distance; negate to move backwards.
	-u	meter	Y	Upward distance; negate to move downwards.
	-r	meter	Y	Rightward distance; negate to move leftwards.
	-forceVerticalUp	boolean	Y	If true, forces upside to align away from vertical up, regardless of `pathAlignmentAngleLimit`. Default true.
	-maxspeed	km/h	Y	Maximum approach speed
	-lockdir	boolean	Y	if true, locks the direction during the approach to that which the construct had when the command was issued.
	-margin	meter	Y	The maximum distance from the destination the construct may be for the destination to be considered reached.
goto	waypoint or ::pos{} string			Moves to the given point
	-maxspeed	km/h	Y	See <move>
	-lockdir		Y	See <move>
	-margin	meter	Y	See <move>
	-offset	meter	Y	If specified, the distance will be shortened by this amount, i.e. stop before reaching the position. Good for approaching unknown locations. Negative offsets means the other side of the point, i.e. overshoot.
	-forceVerticalUp	boolean	Y	If true, forces upside to align away from vertical up, regardless of `pathAlignmentAngleLimit`. Default true.
print-pos				Prints the current position and current alignment point
align-to	waypoint or ::pos{} string			Aligns to the given point or named waypoint
align-to-vector				Aligns to the given point, as given by a 3D-vector. See section "Aligning the elevator to your ground construct"
	-x	number	N	X-component of the vector
	-y	number	N	X-component of the vector
	-z	number	N	X-component of the vector
position-above				See Automatically aligning and positioning using two elements - recommended procedure
	-heightMargin	meter	N	Distance to move vertically before moving in above the center point.
	-cx			X coordinate of centering element
	-cy			Y coordinate of centering element
	-cz			Z coordinate of centering element
	-fx			X coordinate of forward element
	-fy			Y coordinate of forward element
	-fz			Z coordinate of forward element
floor	name of route	string	N	Shows the named route in floor-mode.
hold				Stops and returns to the position at the time of execution, then holds.
idle				Puts the system into idle mode, engines are off.
turn	angle	degrees	N	Turns the construct the specified number of degrees around the Z-axis (up)
strafe	distance	meter	N	Initiates a strafing move with locked direction.
route-list				Lists the currently available routes
route-edit	name of route		N	Opens a route for editing
route-create	name of route		N	Creates a new route and opens it for editing
route-save				Saves the currently open route, and closes it for editing.
route-activate	name of route		N	Activates the named route and starts the flight.
	-index	integer	Y	Specifies which waypoint index that shall be the final destination. Default is '0', meaning the last point in the route.
route-delete	name of route		N	Deletes the named route
route-rename				Renames a route
	-from	string		The name of the route to rename
	-to	string		The new name of the route
route-delete-pos	index of waypoint	number	N	Removes the point at index from the route.
route-move-pos				Moves a point from one index to another
	-from	number		The index to move from
	-to			The index to move to. Positions at and after the position are shifted forward.
route-move-pos-forward	position index, 1..n	number	N	Moves the position at the given index one step forward.
route-move-pos-back	position index, 1..n	number	N	Moves the position at the given index one step backward.
route-add-current-pos				Adds the current position to the current route
	-maxspeed	km/h	Y	See <move>
	-lockdir	boolean	Y	See <move>
	-margin	meter	Y	See <move>
route-add-named-pos
	name of waypoint			Adds a named waypoint to the route
	-maxspeed	km/h	Y	See <move>
	-lockdir		Y	See <move>
	-margin	meter	Y	See <move>
route-set-pos-option	-ix	number	N	Defines the first point to set the respective options on, in the currently edited route.
	-endIx	number	Y	Defines the optional ending index on which to set the respective option on. Use this to set the same options on several points at the same time.
	-toggleSkippable		Y	Toggles the skippable option of the point. A skippable point may be skipped when traveling to another point in the route.
	-toggleSelectable		Y	Toggles the selectable option of the point. A selectable point will show up in the list of available points when a route is show in floor-mode.
	-margin	meter	Y	Sets the margin, in meters, for the point.
	-maxSpeed	km/h	Y	Sets the max speed, in km/h for the point.
	-finalSpeed	km/h	Y	Sets the final speed, i.e. the speed to have when reaching the point.
	-toggleGate		Y	Toggles the gate control for the point.
route-print-pos-options		number	N	Prints the options of the given point in the currently open route.
route-print				Prints the current route to the console
pos-create-along-gravity	name of waypoint			Creates a waypoint relative to the constructs position along the gravity vector.
	-u	meter	N	Upward distance; negate to place point downwards the source of gravity
pos-create-relative	name of waypoint			Creates a waypoint relative to the construct and its current orientation.
	-f	meter	Y	Forward distance; negate to move backwards.
	-u	meter	Y	Upward distance; negate to move downwards.
	-r	meter	Y	Rightward distance; negate to move leftwards.
pos-print-relative				Prints the position relative to the construct and its current orientation.
	-f	meter	Y	Forward distance; negate to move backwards.
	-u	meter	Y	Upward distance; negate to move downwards.
	-r	meter	Y	Rightward distance; negate to move leftwards.
pos-save-current-as	name of waypoint	string		Save the current position as a named waypoint for later use in a route
	-auto		Y	If specified automatically created a waypoint by name WPnnn, such as WP001. Takes precedence over any provided argument.
pos-save-as	name of waypoint		N	Saves the provided position as a named waypoint for later use in a route
	-pos	::pos{}	N	The position string to save as the given name
pos-rename				Renames the waypoint and all references to it in routes.
	-old		N	Name of the existing waypoint
	-new		N	New name of the waypoint
pos-list				Lists the saved positions
pos-delete				Deletes a waypoint.
	name of waypoint	string	N	The waypoint to delete.
create-vertical-route	name of route			Creates a route by the given name from current position to a point above (or below) at the given distance along gravity or optionally, using the given values for the up-vector. The start end end points are given a margin of 0.3m to counter small construct movements when the controller turns off.
	-distance	number	N	The distance of the point above or below (when negative)
	-followGravInAtmo		Y	If specified an extra point will be added so that the part of the path that is in atmosphere will follow the gravity vector, regardless of the specified custom vector.
	-extraPointMargin	number	N	Specifies the margin used for the extra point, default 5 m.
	-x	number	N	Specifies the X-value of the direction vector (see 'Travel vector for additional elevators').
	-y	number	N	Specifies the Y-value of the direction vector (see 'Travel vector for additional elevators').
	-z	number	N	Specifies the Z-value of the direction vector (see 'Travel vector for additional elevators').
print-vertical-up				Prints the negative of the gravitational up-vector, i.e. 'up', at the current location. Used to get values for use with `create-vertical-route`.
get-parallel-from-route				Prints the direction and distance from the first to the second point in the route in a format directly usable by the `create-vertical-route` command. Can be used to create a route parallel to another one.
sub-pos	A `::pos{}` string	string	N	Prints the direction and distance in a format directly usable by the `create-vertical-route` command. Can be used to create a route parallel to another one.
	-sub	`::pos{}`	Y	If proved this is the subtrahend. If left out, the current position is used.
closest-on-line			N	Calculates the closest point on the line that passes through point a and b.
	-a	`::pos{}`	N	Point a
	-b	`::pos{}`	N	Point b
geofence	A `::pos{}` string	`::pos{}`	N	Activates a geofence around the given position.
	-boundary		N	The boundary distance.
disable-geofence				Disables the geofence.
set				Sets the specified setting to the specified value
	-autoBrakeAngle	number	Y	Sets the movement angle offset from the intended path at which the brakes auto engage. Can be used to make brakes engage earlier when turning in manual control. Default 45.
	-autoBrakeDelay	number	Y	Sets the delay before the brakes are applied as per `autoBrakeAngle`. Default 1.
	-autoPitch	boolean	Y	If true, enables automatic pitch for forward movements. Intended for constructs mainly controlled using manual control. Default false.
	-allowForwardToggle	boolean	Y	If true, middle mouse button toggles forward thrust. Best to keep disabled on constructs meant to act as elevators. Default false.
	-autoShutdownFloorDistance	number	Y	Sets the distance at which the system shuts down while in Hold-state, as measured by the 'FloorDetector' telemeter
	-atmoFuelTankHandling	integer	Y	Sets the atmospheric fuel tank handling talent level, 1-5
	-commChannel	string	Y	If set to anything but an empty string, this enables gate controls and defines the channel used to communicate with other constructs on. Must restart elevator when changed.
	-containerProficiency	integer	Y	Sets the container proficiency talent level, 1-5
	-dockingMode	number (1..3)	Y	Sets the docking mode. 1 = Manual (by default use ALT+T/Y dock/undock), 2 = Automatic, 3 = Automatic, but only own constructs.
	-engineWarmup	seconds	Y	Sets the engine warmup time (T50). Set this to that of the engine with longes warmup. Currently not used.
	-fuelTankOptimization	integer	Y	Sets the fuel tank optimization talent level, 1-5
	-globalMaxSpeed	number	Y	Sets the global max speed the construct will accelerate to. Default 0, meaning no limit. This overrides any route-specific settings and also applies to manual control.
	-rocketFuelTankHandling	integer	Y	Sets the rocket fuel tank handling talent level, 1-5
	-routeStartDistanceLimit	number	Y	Sets the maximum allowed activation distance between the construct and the closest point of a route
	-spaceFuelTankHandling	integer	Y	Sets the space fuel tank handling talent level, 1-5
	-showWidgetsOnStart	boolean	Y	If true, diagnostics widgets are shown on start up
	-throttleStep	number	Y	Sets the step size of the throttle in manual control mode in percent, default 10
	-turnAngle	degrees	Y	Sets the turn angle per key press for the manual control mode.
	-manualControlOnStartup	boolean	Y	If true, manual controls are activated on startup.
	-minimumPathCheckOffset	meter	Y	Sets the minimum allowed offset from the path during travel at which the construct will stop to and return to the path. Default 2m. This value is also used as a margin whenever the construct has gone off the path and is attempting to return to it.
	-openGateWaitDelay	number	Y	The number of seconds to wait on gates to be fully opened before starting any movement. Default 3 seconds. Reduce this if your gates are fully open in a shorter time.
	-openGateMaxDistance	number	Y	The elevator must be closer than this to a point in the route that has gate control activated for gate control to open gates. Default 10m. This is to avoid waiting on gates when activating a route in between two points.
	-pathAlignmentAngleLimit	degrees	Y	The threshold angle that determines if the construct will align to the flight path or the gravity vector. Default: 10 degrees. Set to 0 to disable path alignment.
	-pathAlignmentDistanceLimit	meter	Y	The threshold distance from the next and previous waypoint that determines if the construct will align to the flight path or the gravity vector. Default: 200m.
	-pathAlignmentDistanceLimitFromSurface	meter	Y	If the highest possible point of the surface of the nearest planet or moon is further than this distance, the construct will always align to the flight path to use the main engines (downward facing) for propulsion. Default 0 (disabled). Secondary to `pathAlignmentDistanceLimit`. Be careful of using too low distances; you may end up going top first into atmosphere and unable to turn around in time. Recommended reasonable safe values are > 200000. You will find that you need to increase `minimumPathCheckOffset`, significantly depending on the construct to avoid trigger the check while rotating. Use with caution.
	-parkMaxSpeed	km/h	Y	Sets the maximum speed during parking operations.
	-parkForwardDist	m	Y	Sets the longitudal distance to move when performing an undocking procedure activated by CTRL+SHIFT+G. Default 0.
	-parkUseGates	boolean	Y	If set to true, gate control is enabled for the dock/undock procedure.
	-parkVertDist	m	Y	Sets the vertical distance to move when performing an undocking procedure activated by CTRL+SHIFT+G. Default 0.
	-setWaypointAlongRoute	boolean	Y	If true, the next point in the route will become your waypoint.
	-showFloor	name of route	Y	If set, causes the named route to be displayed in floor-mode on startup. To disable, use '-' as the route name.
	-shutdownDelayForGate	number	Y	The number of seconds to wait in the at the final position after detecting a floor to land on before shutting down. Intended for when you have a gate above or beside the elevator that you want to close. Default 2 seconds.
	-yawAlignmentThrustLimiter	number	Y	Sets the alignment limit angle which yaw must be within before accelerating to the next waypoint. Default 3.
	-pitchAlignmentThrustLimiter	number	Y	Sets the alignment limit angle which pitch must be within before accelerating to the next waypoint. Default 5.
	-rollAlignmentThrustLimiter	number	Y	Sets the alignment limit angle which roll must be within before accelerating to the next waypoint. Default 5.
get	See `set`		Y	Prints the setting set with the `set` command, don't add the leading `-`.
get-all				Prints all current settings. Don't add the "-" before the argument. Example: `get turnAngle`.
reset-settings				Resets all settings to their defaults. (including those listed in the advanced section)
set-full-container-boosts				Sets all related talents for containers, atmospheric, space and rocket fuel tanks to level 5
strict-mode				Restores the settings to their defaults for use as a standard elevator. See table below.
free-mode				Adjusts settings for use as a mainly manually controlled construct. See table below.

Please note that deleting named waypoints do not update routes that reference them. You can create a new one with the same name as the one deleted, but until you do, any route that referenced it will not be usable.

Advanced Settings

Command	Parameters/options	Unit/type	Parameter Optional	Description
set
	-lightp	number	Y	The proportional value of the yaw/pitch/roll controller for constructs with a mass of less than 10T. Default: 10
	-lighti	number	Y	The integral value of the yaw/pitch/roll controller for constructs with a mass of less than 10T. Default: 0
	-lightd	number	Y	The derivative value of the yaw/pitch/roll controller for constructs with a mass of less than 10T. Default: 800
	-lighta	number	Y	The amortization value of the yaw/pitch/roll controller for constructs with a mass of less than 10T. Default: 0.1
	-heavyp	number	Y	The proportional value of the yaw/pitch/roll controller for constructs with a mass of more than than 10T. Default: 6
	-heavyi	number	Y	The integral value of the yaw/pitch/roll controller for constructs with a mass of more than than 10T. Default: 1
	-heavyd	number	Y	The derivative value of the yaw/pitch/roll controller for constructs with a mass of more than than 10T. Default: 1600
	-heavya	number	Y	The amortization value of the yaw/pitch/roll controller for constructs with a mass of more than than 10T. Default: 0.1

Note: Adjusting the values of the yaw/pitch/roll controller may allow you to get quicker responses, but also induce instability. If the construct behaves jerkish, try lowering the lightd/heavyd value.

Free and strict mode

The free-mode and strict-mode commands adjusts settings as follows:

Setting	free-mode	strict-mode
autoBrakeDelay	0	default value
autoPitch	true	default value
allowForwardToggle	true	default value
yawAlignmentThrustLimiter	360	default value
pitchAlignmentThrustLimiter	360	default value
rollAlignmentThrustLimiter	360	default value
manualControlOnStartup	true	default value
minimumPathCheckOffset	5000	default value
pathAlignmentDistanceLimitFromSurface	0	default value
turnAngle	8	default value

Parking

The parking feature works as follows:

When pressing G, the construct will move downward vertically in reference to the current gravity vector at the configured speed. When the telemeter detects something below (max range is 100m), a new waypoint is created and it will move to that position.

Autopark/undock

Note: This feature is EXPERIMENTAL

Pressing CTRL + SHIFT + G creates a three-point route, from the current position, with the mid point parkVertDist meters vertically and the final point at parkForwardDist in front of that. It then travels the route, stopping at the final point.

Pressing SHIFT + G activates an auto-return feature that will take you vertically from your current pos, then moves to the final point created as described above, then runs the route in reverse to take you back to the location you started at.

The auto return feature is meant to work in somewhat close vicinity of the saved position, don't attempt to use it from the other side of the planet etc.

Access Control

By default, the owner (a single player or all members of the owning organization) has administrative rights and can configure, start routes and take manual control of the construct. If you wish for non-owners to do the same, you can do so using the following commands in Lua chat. You can also disallow members of the owning organization administrator rights. If the construct is owned by a player, that player is always an administrator.

Command	Parameters/options	Unit/type	Parameter Optional	Description
allow-route	route name	string	N	Given the name of a route, adds it to the list of allowed routes non-owners may start.
disallow-route	route name	string	N	Given the name of a route, removes it from the list of allowed routes non-owners may start.
print-allowed-routes				Prints the list of allowed routes non-owners may start.
allow-manual-control				Enables manual control for non-owners.
disallow-manual-control				Disables manual control for non-owners.
add-admin	player name	string	N	Adds the named player to the admin list.
remove-admin	player name	string	N	Removes the named player from the admin list.
allow-org-admin				Makes all players of the owning organization an admin, this is the default.
disallow-org-admin				Makes all players of the owning organization no longer be an admin.
print-admins				Prints the current administrators.

Geofence

By enabling a geofence you can prevent the construct from being flown further away than the limit you specify, centered around a position of your choice. To enable the function, run the command like in this example

geofence ::pos{0,2,49.9273,160.4051,39.0299} -boundary 1000

This sets a boundary at 1000m from the given position. When the construct reaches the boundary, it will break and not allow acceleration unless the desired travel direction is within 90 degrees of the center position.

To disable the geofence, run the command disable-geofence

Note the boundary applies also when running a route.

Mass Overload

Each construct has a max cargo mass it is rated for. If you load the construct with more then one or more of the following may happen:

Event	Possible reasons
When taking off from planet, it will start, brake, start repeatedly.	Too little brake force to counter gravity for the current mass, which causes the math to say max speed of 0 km/h.
When reaching higher atmosphere it may slow down, stop, and start falling or just hold position.	Engines not being powerful enough, and/or the thin atmosphere causing too much reduction in power, or too heavy load.

Should you end up in these situations, it is easiest to just disable the controller (and the ECU), and let it fall back down a bit then activate it again. It will then attempt to hold the position it was at when it was started, i.e. brake and activate engines to counter the fall. You can repeat this until you're at an height the engines work again. Having said that, an overloaded ship is still overloaded and bad things are likely to happen.

Accuracy

The aim is 0.1m accuracy and this is also the default for the all movements. However, depending on various factors such as engine choice, mass (and thus acceleration), the construct may go off the path slightly. There is a failsafe that triggers if the nearest point on the path too far off (see setting minimumPathCheckOffset, or as defined by the next waypoint), in which case the construct will brake and return to the point at which it went off the path before continuing the route. If you want to override this behavior, you can reactivate the route again which will make the construct move to the closest point on the path from where where it is when you reactivate the route.

You may also increase the margin on specific waypoints to allow more wiggle room during travel, this may be especially useful on waypoints towards which the acceleration/speed is high or the path is diagonal relative to the gravity vector. Alternatively, you can set a maximum speed to reduce acceleration duration and speed.

The two settings pathAlignmentAngleLimit and pathAlignmentDistanceLimit control if/when the construct aligns itself to the current flight path. While doing so significantly increases the ability to stay on the path (especially during atmospheric descent), it may cause issues if the approach to the parking position is at an angle and it has been encapsulated. The alignment only happens if the distance to the next and previous waypoint is greater than pathAlignmentDistanceLimit and if the angle to the gravity vector is less than pathAlignmentAngleLimit. Should you wish to disable the alignment completely, set pathAlignmentAngleLimit to 0.

Custom / non-gravity aligned travel vectors

The further the distance is between the reference elevator and any additional one, the harder it is to stay exactly on the desired path, especially during strong (de)acceleration. The script will attempt to bring the elevator back to the path in time for the end position, but if this becomes a problem you can add an additional point in the route to force it back to the path prior to reaching the final point.

A note on non gravity-aligned atmospheric ascent/descent and angled flight paths

While it is possible to make routes that are not gravity aligned work, they may be somewhat unreliable. These are the main reasons:

Atmospheric brakes

Quote from NQ-support: The speed is projected on the horizontal plane of the construct. And we add a brake force in that plane in the opposite direction of that projected speed, which induces a vertical force when the ship has a pitch.

It is this horizontal force that causes the construct to be pushed off the path. The easiest way to work around this is to ensure that the entry to the planet is aligned with the gravity vector by adding an extra point in the route in space directly above the point inside the atmosphere (see pos-create-along-gravity). The downside is that this will be a position the construct has to stop at, which prolongs the travel time and increases fuel consumption due to extra acceleration.
Strong acceleration

Sideways engines are generally weaker than the main downward pointing engines so when accelerating, the weaker ones may have difficulties to keep the construct on the path.

Shifting gravity wells

As described in Accuracy, the script aligns either to gravity or the travel path. When gravity direction changes, such as near Thades' moonlets (where they appear to be the sum of the different gravity wells depending on the location of the construct), the script will adjust its alignment accordingly. The script keeps the main engines pointing against gravity, unless pathAlignmentDistanceLimitFromSurface has been configured to tell it to do otherwise.

This means that a route starting at the surface of Thades and ending among the moonlets will have different alignment directions along the travel path. As such, a space construct placed based on the elevator's alignment in space will not point exactly away from Thades, but clearly be at an angle to the planet. Please keep all this in mind when building your space construct.

A way to work around this is to add an extra point in the route within the distance of pathAlignmentDistanceLimit so that you force the alignment to be along gravity for the duration of the travel between the points.

Emergency Controller Unit

When running on an ECU, the script only do two things:

Attempts to hold the position it has when activated
Detect a floor, and if detected it shuts down.

The requirements for linking are the same as for when running on a controller.

Thanks

Special thanks goes out to these players:

Vargen - for our endless discussions and a fountain of ideas.
Zcrewball - for doing the industry supplying an endless number of sacrificial elements.
De Overheid - Helping out with the visual design.
Emma Roid, 2Bitter, Petra25, AceMan, Tobitege - for feedback

Files

README.md

Latest commit

History