kOS is a scriptable autopilot Mod for Kerbal Space Program. It allows you write small programs that automate specific tasks.
Like other mods, simply merge the contents of the zip file into your Kerbal Space Program folder.
Add the Compotronix SCS part to your vessel; it’s under the “Control” category in the Vehicle Assembly Building or Space Plane Hanger. After hitting launch, you can right-click on the part and select the “Open Terminal” option. This will give you access to the KerboScript interface where you can begin issuing commands and writing programs.
KerboScript is a programming language that is derived from the language of planet Kerbin, which sounds like gibberish to non-native speakers but for some reason is written exactly like English. As a result, KerboScript is very English-like in its syntax. For example, it uses periods as statement terminators.
The language is designed to be easily accessible to novice programmers, therefore it is case-insensitive, and types are cast automatically whenever possible.
A typical command in KerboScript might look like this:
PRINT “Hello World”.
KerboScript uses an expression evaluation system that allows you to perform math operations on variables. Some variables are defined by you. Others are defined by the system.
There are three basic types:
You can use mathematical operations on numbers, like this:
SET X TO 4 + 2.5.
PRINT X. // Outputs 6.5
The system follows the order of operations, but currently the implementation is imperfect. For example, multiplication will always be performed before division, regardless of the order they come in. This will be fixed in a future release.
ABS(1). // Returns absolute value of input. e.g. 1
MOD(21,6). // Returns remainder of an integer division. e.g. 3
FLOOR(1.887). // Rounds down to the nearest whole number. e.g. 1
CEILING(1.887). // Rounds up to the nearest whole number. e.g. 2
ROUND(1.887). // Rounds to the nearest whole number. e.g. 2
ROUND(1.887, 2). // Rounds to the nearest place value. e.g. 1.89
SQRT(7.89). // Returns square root. e.g. 2.80891438103763
SIN(6). // Returns sine of input. e.g. 0.10452846326
COS(6). // Returns cosine. e.g. 0.99452189536
TAN(6). // Returns tangent. e.g. 0.10510423526
ARCSIN(0.67). // Returns angle whose sine is input in degrees. e.g. 42.0670648
ARCCOS(0.67). // Returns angle whose cosine is input in degrees. e.g. 47.9329352
ARCTAN(0.67). // Returns angle whose tangent is input in degrees. e.g. 33.8220852
ARCTAN2(0.67, 0.89). // Returns the angle whose tangent is the quotient of two specified numbers in degrees. e.g. 36.9727625
Strings are pieces of text that are generally meant to be printed to the screen. For example:
PRINT “Hello World!”.
To concatenate strings, you can use the + operator. This works with mixtures of numbers and strings as well.
PRINT “4 plus 3 is: “ + (4+3).
Directions exist primarily to enable automated steering. You can initialize a direction using a vector or a rotation.
SET Direction TO V(0,1,0). // Set a direction by vector
SET Direction TO R(0,90,0). // Set by a rotation in degrees
You can use math operations on Directions as well. The next example uses a rotation of “UP” which is a system variable describing a vector directly away from the celestial body you are under the influence of.
SET Direction TO UP + R(0,-45,0). // Set direction 45 degress west of “UP”.
Adds a maneuver node to the flight plan.
Example: This statement adds a node that occurs 30 seconds from now, and has a delta-V of 100 m/s radial out, 0 m/s normal, and 200 m/s prograde.
ADD NODE(TIME + 30, 100, 0, 200).
Removes maneuver node from flight plan. Cannot remove bare nodes e.g. ADD NODE().
SET X TO NODE(0,0,0,0).
ADD X.
REMOVE X.
ADD NODE(0,0,0,0).
REMOVE. // Does not remove node.
Breaks out of a loop. Example:
SET X TO 1.
UNTIL 0 {
SET X TO X + 1.
IF X > 10 { BREAK. }. // Exits the loop when X is greater than 10
}.
Clears the screen and places the cursor at the top left. Example:
CLEARSCREEN.
Copies a file to or from another volume. Volumes can be referenced by their ID numbers or their names if they’ve been given one. See LIST, SWITCH and RENAME. Example:
SWITCH TO 1. // Makes volume 1 the active volume
COPY file1 FROM 0. // Copies a file called file1 from volume 0 to volume 1
COPY file2 TO 0. // Copies a file called file1 from volume 1 to volume 0
Deletes a file. You can delete a file from the current volume, or from a named volume. Example:
DELETE file1. // Deletes file1 from the active volume.
DELETE file1 FROM 1. // Deletes file1 from volume 1
Declares a variable at the current context level. Alternatively, a variable can be implicitly declared by a SET or LOCK statement. Example:
DECLARE X.
Declares variables to be used as a parameter. Example:
DECLARE PARAMETER X.
DECLARE PARAMETER X,y.
RUN MYPROG(X).
Edits a program on the currently selected volume. Example:
EDIT filename.
Checks if the expression supplied returns true. If it does, IF executes the following command block. Example:
SET X TO 1.
IF X = 1 { PRINT "X equals one.". }. // Prints "X equals one."
IF X > 10 { PRINT "X is greater than ten.". }. // Does nothing
If statements can make use of boolean operators. Example:
IF X = 1 AND Y > 4 { PRINT "Both conditions are true". }.
IF X = 1 OR Y > 4 { PRINT "At least one condition is true". }.
Lists the files on the current volume, or lists the currently available volumes. Lists files by default. Example:
LIST. // Lists files on the active volume
LIST FILES. // Lists files on the active volume
LIST VOLUMES. // Lists all volumes, with their numbers and names
LIST BODIES. // Lists celestial bodies and their distance
LIST TARGETS. // Lists target-able vessels in range
LIST RESOURCES. // List of resources by stage
LIST PARTS. // Lists parts in vessel
LIST ENGINES. // List of engines
Locks a variable to an expression. On each cycle, the target variable will be freshly updated with the latest value from expression. Example:
SET X TO 1.
LOCK Y TO X + 2.
PRINT Y. // Outputs 3
SET X TO 4.
PRINT Y. // Outputs 6
Awaits a change in a boolean variable, then runs the selected command. This command is best used to listen for action group activations. Example:
ON AG3 PRINT “Action Group 3 Activated!”.
ON SAS PRINT “SAS system has been toggled”.
Prints the selected text to the screen. Can print strings, or the result of an expression. Example:
PRINT “Hello”.
PRINT 4+1.
PRINT “4 times 8 is: “ + (4*8).
Prints the selected text to the screen at specified location. Can print strings, or the result of an expression. Example:
PRINT “Hello” at (0,10).
PRINT 4+1 at (0,10).
PRINT “4 times 8 is: “ + (4*8) at (0,10).
Logs the selected text to a file on the local volume. Can print strings, or the result of an expression. Example:
LOG “Hello” to mylog.
LOG 4+1 to mylog .
LOG “4 times 8 is: “ + (4*8) to mylog.
Renames a file or volume. Example:
RENAME VOLUME 1 TO AwesomeDisk
RENAME FILE MyFile TO AutoLaunch.
Removes a maneuver node. Example:
REMOVE NEXTNODE. // Removes the first maneuver node in the flight plan.
Runs the specified file as a program. Example:
RUN AutoLaunch.
Sets the value of a variable. Declares the variable if it doesn’t already exist. Example:
SET X TO 1.
Executes the stage action on the current vessel. Example:
STAGE.
Switches to the specified volume. Volumes can be specified by number, or it’s name (if it has one). See LIST and RENAME. Example:
SWITCH TO 0. // Switch to volume 0.
RENAME VOLUME 1 TO AwesomeDisk. // Name volume 1 as AwesomeDisk.
SWITCH TO AwesomeDisk. // Switch to volume 1.
Toggles a variable between true or false. If the variable in question starts out as a number, it will be converted to a boolean and then toggled. This is useful for setting action groups, which are activated whenever their values are inverted. Example:
TOGGLE AG1. // Fires action group 1.
TOGGLE SAS. // Toggles SAS on or off.
Releases a lock on a variable. See LOCK. Examples:
UNLOCK X. // Releases a lock on variable X.
UNLOCK ALL. // Releases ALL locks.
Performs a loop until a certain condition is met. Example:
SET X to 1.
UNTIL X > 10 { // Prints the numbers 1-10.
PRINT X.
SET X to X + 1.
}.
Halts execution for a specified amount of time, or until a specific set of criteria are met. Note that running a WAIT UNTIL statement can hang the machine forever if the criteria are never met. Examples:
WAIT 6.2. // Wait 6.2 seconds.
WAIT UNTIL X > 40. // Wait until X becomes greater than 40.
WAIT UNTIL APOAPSIS > 150000. // You can see where this is going.
Executes a command when a certain criteria are met. Unlike WAIT, WHEN does not halt execution. Example:
WHEN BCount < 99 THEN PRINT BCount + “ bottles of beer on the wall”.
Sets a variable to true. This is useful for the RCS and SAS bindings. Example:
RCS ON // Turns on the RCS
Sets a variable to false. This is useful for the RCS and SAS bindings. Example
RCS OFF // Turns off the RCS
Sets game warp to provided value(0-7).
SET WARP TO 5. // Sets warp to 1000x.
SET WARP TO 0. // Sets warp to 0x aka real time.
Reboots the kOS module.
Causes kOS module to shutdown.
You can get several useful vessel stats for your ships
VESSELNAME
ALTITUDE
ALT:RADAR // Your radar altitude
BODY // The current celestial body whose influence you are under
MISSIONTIME // The current mission time
VELOCITY // The current orbital velocity
VERTICALSPEED
SURFACESPEED
LATITUDE
LONGITUDE
STATUS // Current situation: LANDED, SPLASHED, PRELAUNCH, FLYING, SUB_ORBITAL, ORBITING, ESCAPING, or DOCKED
INLIGHT // Returns true if not blocked by celestial body, always false without solar panel.
INCOMMRANGE // returns true if in range
COMMRANGE // returns commrange
MASS
MAXTHRUST // Combined thrust of active engines at full throttle (kN)
Returns time in various formats.
TIME // Gets the current universal time
TIME:CLOCK // Universal time in H:M:S format(1:50:26)
TIME:CALENDAR // Year 1, day 134
TIME:YEAR // 1
TIME:DAY // 134
TIME:HOUR // 1
TIME:MINUTE // 50
TIME:SECOND // 26
These return a vector object, which can be used in conjuction with the LOCK command to set your vessel's steering.
PROGRADE
RETROGRADE
UP // Directly away from current body
These values can be polled either for their altitude, or the vessel's ETA in reaching them. By default, altitude is returned.
APOAPSIS // Altitude of apoapsis
ALT:APOAPSIS // Altitude of apoapsis
PERIAPSIS // Altitude of periapsis
ALT:PERIAPSIS // Altitude of periapsis
ETA:APOAPSIS // ETA to apoapsis
ETA:PERIAPSIS // ETA to periapsis
NODE // Direction of next maneuver node, can be used with LOCK STEERING
MAG:NODE // Delta-v magnitude of maneuver node
ETA:NODE // ETA to active maneuver node
ENCOUNTER // Returns celestial body of encounter
NEXTNODE // Next node in flight plan.
LIQUIDFUEL
OXIDIZER
ELECTRICCHARGE
MONOPROPELLANT
INTAKEAIR
SOLIDFUEL
STAGE:LIQUIDFUEL // Prints per stage liquid fuel.
STAGE:OXIDIZER
PRINT <LiquidFuel>. // Print the total liquid fuel in all tanks. DEPRECATED
PRINT SHIP:LIQUIDFUEL. // Print the total liquid fuel in all tanks.
PRINT VESSEL("kerbRoller2"):LIQUIDFUEL. // Print the total liquid fuel on kerbRoller2.
PRINT TARGET:LIQUIDFUEL. // Print the total liquid fuel on target.
These values can be SET, TOGGLED, or LOCKED. Some values such as THROTTLE and STEERING explicity require the use of lock.
SAS // For these five, use ON and OFF, example: SAS ON. RCS OFF.
GEAR
RCS
LIGHTS
BRAKES
LEGS
CHUTES // Cannot be un-deployed.
PANELS
ABORT
AGX // Where x = 1 through 10. Use toggle, example: TOGGLE AG1.
THROTTLE // Lock to a decimal value between 0 and 1.
STEERING // Lock to a direction.
WHEELTHROTTLE // Seperate throttle for wheels
WHEELSTEERING // Seperate steering system for wheels
Structures are variables that can contain more than one piece of information. Structures can be used with SET.. TO just like any other variable. Changing valves works only with V() and NODE() at this time, cannot be used with lock.
Their subelements can be accessed by using : along with the name of the subelement.
Represents a set of geo-coordinates.
SET X TO LATLNG(10, 20). // Initialize point at lattitude 10, longitude 20
PRINT X:LAT. // Print 10.
PRINT X:LNG. // Print 20.
PRINT X:DISTANCE. // Print distance from vessel to x (same altitude is presumed)
PRINT LATLNG(10,20):HEADING. // Print the heading to the point.
PRINT X:BEARING. // Print the heading to the point relative to vessel heading.
Represents a maneuver node.
SET X TO NODE(TIME+60, 0, 0, 100). // Creates a node 60 seconds from now with
// prograde=100 m/s
ADD X. // Adds the node to the flight plan.
PRINT X:PROGRADE. // Returns 100.
PRINT X:ETA. // Returns the ETA to the node.
PRINT X:DELTAV // Returns delta-v vector.
REMOVE X. // Remove node from the flight plan.
SET X TO NODE(0, 0, 0, 0). // Create a blank node.
ADD X. // Add Node to flight plan.
SET X:PROGRADE to 500. // Set nodes prograde to 500m/s deltav.
PRINT X:APOAPSIS. // Returns nodes apoapsis.
PRINT X:PERIAPSIS. // Returns nodes periapsis.
Represents a heading that's relative to the body of influence.
SET X TO HEADING(45, 10). // Create a rotation facing northeast, 10 degrees above horizon
Represents a rotation.
SET X TO PROGRADE + R(90,0,0). // Initializes a direction to prograde plus a relative pitch of 90
LOCK STEERING TO X. // Steer the vessel in the direction suggested by direction X.
Represents a vector.
SET varname TO V(100,5,0). // initializes a vector with x=100, y=5, z=0
varname:X. // Returns 100.
V(100,5,0):Y. // Returns 5.
V(100,5,0):Z. // Returns 0.
varname:MAG. // Returns the magnitude of the vector, in this case
SET varname:X TO 111. // Changes vector x value to 111.
SET varname:MAG to 10. // Changes magnitude of vector. e.g. V(9.98987,0.44999,0)
Represents a targetable vessel
SET X TO VESSEL("kerbRoller2"). // Initialize a reference to a vessel.
PRINT X:DISTANCE. // Print distance from current vessel to target.
PRINT X:HEADING. // Print the heading to the vessel.
PRINT X:BEARING. // Print the heading to the target vessel relative to vessel heading.
Represents currently selected ship
PRINT SHIP. // returns VESSEL("kerbRoller2")
PRINT SHIP:DISTANCE. // Print distance from current vessel to target.
PRINT SHIP:HEADING. // Print the heading to the vessel.
PRINT SHIP:BEARING. // Print the heading to the target vessel relative to vessel heading.
Represents targeted vessel or celestial body
SET TARGET TO "kerbRoller2". // target kerbRoller2
PRINT TARGET:DISTANCE. // Print distance from current vessel to target.
PRINT TARGET:HEADING. // Print the heading to the target vessel.
PRINT TARGET:BEARING. // Print the bearing to the target vessel relative to vessel heading.
Returns values about kOS and hardware
PRINT VERSION. // Returns operating system version number. 0.8.6
PRINT VERSION:MAJOR. // Returns major version number. e.g. 0
PRINT VERSION:MINOR. // Returns minor version number. e.g. 8
PRINT SESSIONTIME. // Returns amount of time, in seconds, from vessel load.