NAV Autopilot

Autopilot in-game script that will fully steer and fly your ship
from point A to point B (and C, and D, and...).

Coordinates and other instructions are easily given without editing code.

Supports multiple waypoints, as well as patrolling (i.e. continuously
looping over a series of waypoints). Can also limit ship speed.

Gives feedback via antenna/beacon (or any named block), both for status
as well as error reporting (such as if a required block is missing).

Will automatically shutdown and stop ship if problems are detected
during flight.

Note: While flying your ship, this program will make several stops along
the way. This is normal, and is done to ensure that it won't overshoot
the destination, even if you are using a speed mod and your ship can't
slow down very fast.



Ship requirements

Note: Block naming is changeable by editing the script.

ONE named orientation block. This should usually be a remote control block.

Orientation Block: "Miner Remote Control" If named block is not found, the first remote control is used. If no remote control, the first ship contoller is used.

Group called "NAV Thrusters", containing all rear-facing
thrusters that the program should use to move the ship forward

Programmable block, named "NAV Program" (name is optional)

Timer block, named "NAV Timer"
Single action set to run NAV Program
NOTE: DO NOT have it retrigger itself.

One of the following for instruction blocks:

• Named block, name starting with "NAV:" followed by instructions
  See below for instruction list
  
  
• Text Panel or LCD Panel, named "NAV Instructions"
  Public text contains instructions
  See below for instruction list

(Optional) Named block, named "NAV Status"
Used to report navigation status or error messages
If the "NAV Status" block is a Text Panel or LCD Panel, the status
messages are written to the public text rather than the block name

NOTE: All gyros must be mounted on the floor, facing forward
The front of the gyro contains a round knob and/or control panel

(Optional) Group called "NAV Gyros", containing all gyros that the
program should use to steer the ship. Useful when docked with
another ship that doesn't have proper gyro orientation. If group
doesn't exist, all gyros are used.

(Optional) Named block, named "NAV Enable"
Used as a kill switch. If block exists, and is powered off, autopilot
will shutdown and stop ship. Useful to bind to the toolbar
when you are riding within the ship.

Keep inertia dampeners ON at all times.


Navigation instructions

Multiple instructions can be given in a sequence, separated by semi-colon
or new line. A space is required between the instruction letter and any
parameters you pass to it.
There is currently an arbitrary limit of 32 instructions.

C <text>
Comment, to help label your instructions.
Has no effect on the program. Does not count towards instruction limit.

D <distance>
Sets the arrival distance (how close to get to the destination), in meters,
for the next waypoint.
Distance can be a single number, which the ship will try to reach, or it
can be two numbers separated by a comma, representing the minimum and
maximum distances allowed (i.e. 50,100). Because min/max ranges are less
precise, the ship is often able to arrive at the waypoint with fewer
stops along the way.
Distance is measured from the "NAV Center" block, so if that block is in
the back of your ship, you'll need to increase the arrival distance by at
least the length of your ship (in meters, not blocks).
Also note that this value is an estimate, as the program doesn't know
exactly how fast your ship can decelerate, so giving yourself 50-100m
additional padding is a good idea until you get a feel for it.
Default value is 50,100 (50m min and 100m max).

L
Loops back to the first instruction. All instructions before this one
will be repeated indefinitely. All instructions after this one will be
ignored.

P <seconds>
Pauses the script for the specified number of seconds. The script will
still be running and in control of the ship, but it will sit idle until
the specified number of seconds have passed. After the time has passed,
it will continue on to the next instruction.

Q
Toggles quick waypoint transitions.
By default, when the ship arrives at a waypoint, it will come to a
complete stop before turning to face the next waypoint. Enabling
quick transitions will make the ship start turning to the next waypoint
immediately on arrival, without waiting to stop. This speeds up
waypoint traversal, but makes the followed path less precise, which
may be a problem for large slow ships near obstacles.
This instruction can be used multiple times to toggle on or off for
specific waypoints. Toggled setting will apply to the end of the next
waypoint.
Default value is off.

R <coordinates>
Like W, but coordinates are relative to current ship position (or
relative to the last waypoint, if there was one). For example,
coordinates 100,0,0 would move the ship 100 meters along the X axis from
it's current position.

S <number>
Sets the maximum ship speed, in meters. If set to 0, no limit is enforced.
Because the game doesn't provide a reliable way to measure ship speed,
it has to be estimated. Therefore, the actual speed that the ship limits
itself to may be up to 20% lower than what you set, and depends on server
load and simulation speed.
Default value is 0.

W <coordinates>
Adds a waypoint, at the specified coordinates. Coordinates are a set of
three numbers, separated by commas (i.e. 123,456,-78) or colons
(i.e. 123:456:-78). The last waypoint given (or only waypoint, if only
one given) is the final destination.

+ <group>
Turns on the specified group.

- <group>
Turns off the specified group.

Added by Wico:

O <coordinates>
Orients the FRONT of the ship towards the coordinates.

r <coordinates>
Rotates the ship so the TOP faces the coordinates.

V Orient front to captured location

! Capture current location

NOTE: Front and Top and determined by the orientation of the main orientation block.

EXAMPLE:
To have your ship patrol back and forth between coordinates 100,200,300 and
-1100,700,-123 and try to stop 200m from each point before going to the next,
your instructions would look something like this:

NAV: D 200 ; W 100,200,300 ; W -1100,700,-123 ; L

You can add comments, and you can even set a different speed or distance for
each waypoint:

NAV: C This is a test;S 200;D 500;W 100,200,300;S 100;D 0;W -1100,700,-123

Capture location and then orient. Will face rear in direction of travel.
NAV: !;V

NEW
Commands can be issued through Programmable Block arguments


Instruction List:
D Distance D min[,max]
C Comment C [text]
L Loop Loop back to first instruction L
O Orient O [x,y,z|x;y;z]
P Pause P <seconds>
Q Toggle quick waypoint transition Q
R Relative R [x,y,z|x;y;z]
r Roll r [x,y,z|x;y;z]
S Speed S <max mps>
W Waypoint W [x,y,z|x;y;z]
+ Turn on named group + <group>
- turn off named group - <group>
! Capture current location
V orient front to captured location. This mean rear will now face direction of travel