First example: Hello World¶

In the grand tradition of programming tutorials, the first example will be how to make a script that does nothing more than print the words “Hello World” on the screen. The purpose of this example is to show where you should put the files, how to move them about, and how to get one to run on the vessel.

Step 2: Make a vessel in the Vehicle Assembly Bay¶

Make the vessel contain any unmanned command core, a few hundred units of battery power, a means of recharging the battery such as a solar panel array, and the “Comptronix CX-4181 Scriptable Control System”. (From this point onward the CX-4181 Scriptable Control System part will be referred to by the acronym “SCS”.) The SCS part is located in the parts bin under the “Control” tab (the same place where RCS thrusters and Torque Wheels are found.)

Step 5: See what an interactive command is like¶

You should now see an old-school looking text terminal like the one shown below. Type the line:

CLEARSCREEN. PRINT "==HELLO WORLD==".

into the terminal (make sure to actually type the periods (”.”) as shown) and hit ENTER. Note that you can type it in uppercase or lowercase. kOS doesn’t care.

The terminal will respond by showing you this:

Step 6: Okay that’s great, but how can you make that happen in a program script instead?¶

Like so: Enter this command:

EDIT HELLO.

(Don’t forget the period (”.”). All commands in kOS are ended with a period. Again, you can type it in uppercase or lowercase. kOS doesn’t care.)

You should see an editor window appear, looking something like this (without the text inside because you’re starting a blank new file):

Type this text into the window:

PRINT "=========================================".
PRINT "      HELLO WORLD".
PRINT "THIS IS THE FIRST SCRIPT I WROTE IN kOS.".
PRINT "=========================================".

Click “Save” then “Exit” in the editor pop-up window.

• Side Note: The editor font - Experienced programmers may have noticed that the editor’s font is proportional width rather than monospaced and that this is not ideal for programming work. You are right, but there is little that can be done about it for a variety of technical reasons that are too complex to go into right now.

Then on the main text terminal Enter:

RUN HELLO.

And you will see the program run, showing the text on the screen like so.

Step 7: Okay, but where is this program?¶

To see where the “HELLO” program has been saved, Issue the command LIST FILES like this:

LIST FILES.

(Note, that the default for the LIST command is to list FILES, so you can leave the word “FILES” off if you like.)

It should look like this, showing you the HELLO program you just wrote:

This is a list of all the files on the currently selected VOLUME. By default, when you launch a new vessel, the currently selected VOLUME is called “1” and it’s the volume that’s stored on THAT SCS part that you are running all these commands in.

This is the local volume of that SCS part. Local volumes such at this tend to have very small limited storage, as you can see when you look at the space remaining in the list printout.

If you’re wondering where the file is stored physically on your computer, it’s represented by a section inside the persistence file for your saved game, as a piece of data associated with the SCS part. This is important because it means you can’t access the program from another vessel, and if this vessel ever crashes and the SCS part explodes, then you’ve lost the program.

SWITCH TO 0.
EDIT HELLO2. // Make a new file here that just says: PRINT "hi again".
LIST FILES.
RUN HELLO2.
SWITCH TO 1.
LIST FILES.
RUN HELLO.

Second Example: Doing something real¶

Okay that’s all basic setup stuff but you’re probably clamoring for a real example that actually does something nifty.

This example will show the crudest, most basic use of kOS just to get started. In this example we’ll make a program that will launch a vessel using progressively more and more complex checks. kOS can be used at any stage of a vessel’s flight - launching, circularizing, docking, landing,... and in fact launching is one of the simpler piloting tasks that you can do without much need of automation. Where kOS really shines is for writing scripts to do touchy sensitive tasks like landing or docking or hovering. These are the areas that can benefit from the faster reaction speed that a computer script can handle.

But in order to give you an example that you can start with from scratch, that’s easy to reload and retry from an initial point, we’ll use an example of launching.

Step 1: Make a vessel¶

This tutorial is designed to work with a very specific rocket design. You need to make the vessel you see here:

If you prefer, you can instead download the .craft file here

Step 2: Make the start of the script¶

Okay, so type the lines below in an external text editor of your choice (i.e. Notepad on Windows, or TextEdit on Mac, or whatever you fancy):

//hellolaunch

//First, we'll clear the terminal screen to make it look nice
CLEARSCREEN.

//This is our countdown loop, which cycles from 10 to 0
PRINT "Counting down:".
FROM {local countdown is 10.} UNTIL countdown = 0 STEP {SET countdown to countdown - 1.} DO {
    PRINT "..." + countdown.
    WAIT 1. // pauses the script here for 1 second.
}

See those things with the two slashes (“//”)? Those are comments in the kerboscript language and they’re just ways to write things in the program that don’t do anything - they’re there for humans like you to read so you understand what’s going on. In these examples you never actually have to type in the things you see after the slashes. They’re there for your benefit when reading this document but you can leave them out if you wish.

Save the file in your Ships/Script folder of your KSP installation under the filename “hellolaunch.ks”. DO NOT save it anywhere under GameData/kOS/. Do NOT. According to the KSP standard, normally KSP mods should put their files in GameData/[mod name], but kOS puts the archive outside the GameData folder because it represents content owned by you, the player, not content owned by the kOS mod.

By saving the file in Ships/Script, you have actually put it in your archive volume of kOS. kOS will see it there immediately without delay. You do not need to restart the game. If you do:

SWITCH TO 0.
LIST FILES.

after saving the file from your external text editor program, you will see a listing of your file “hellolaunch” right away. Okay, now copy it to your local drive and give it a try running it from there:

SWITCH TO 1.
COPY HELLOLAUNCH FROM 0.
RUN HELLOLAUNCH.

Okay so the program doesn’t actually DO anything yet other than just countdown from 10 to 0. A bit of a disappointment, but we haven’t written the rest of the program yet.

You’ll note that what you’ve done is switch to the local volume (1) and then copy the program from the archive (0) to the local volume (1) and then run it from the local volume. Technically you didn’t need to do this. You could have just run it directly from the archive. For those looking at the KSP game as a bit of a role-play experience, it makes sense to never run programs directly from the archive, and instead live with the limitation that software should be copied to the craft for it to be able to run it.

Step 3: Make the script actually do something¶

Okay now go back into your text editor of choice and append a few more lines to the hellolaunch.ks file so it now looks like this:

//hellolaunch

//First, we'll clear the terminal screen to make it look nice
CLEARSCREEN.

//Next, we'll lock our throttle to 100%.
LOCK THROTTLE TO 1.0.   // 1.0 is the max, 0.0 is idle.

//This is our countdown loop, which cycles from 10 to 0
PRINT "Counting down:".
FROM {local countdown is 10.} UNTIL countdown = 0 STEP {SET countdown to countdown - 1.} DO {
    PRINT "..." + countdown.
    WAIT 1. // pauses the script here for 1 second.
}

UNTIL SHIP:MAXTHRUST > 0 {
    WAIT 0.5. // pause half a second between stage attempts.
    PRINT "Stage activated.".
    STAGE. // same as hitting the spacebar.
}

WAIT UNTIL SHIP:ALTITUDE > 70000.

// NOTE that it is vital to not just let the script end right away
// here.  Once a kOS script just ends, it releases all the controls
// back to manual piloting so that you can fly the ship by hand again.
// If the program just ended here, then that would cause the throttle
// to turn back off again right away and nothing would happen.

Save this file to hellolaunch.ks again, and re-copy it to your vessel that should still be sitting on the launchpad, then run it, like so:

COPY HELLOLAUNCH FROM 0.
RUN HELLOLAUNCH.

Hey! It does something now! It fires the first stage engine and launches!

But.. but wait... It doesn’t control the steering and it just lets it go where ever it will.

Most likely you had a crash with this script because it didn’t do anything to affect the steering at all, so it probably allowed the rocket to tilt over.

Step 4: Make the script actually control steering¶

So to fix that problem, let’s add steering control to the script.

The easy way to control steering is to use the LOCK STEERING command.

Once you have mastered the basics of kOS, you should go and read the documentation on ship steering techniques, but that’s a more advanced topic for later.

The way to use the LOCK STEERING command is to set it to a thing called a Vector or a Direction. There are several Directions built-in to kOS, one of which is called “UP”. “UP” is a Direction that always aims directly toward the sky (the center of the blue part of the navball).

So to steer always UP, just do this:

LOCK STEERING TO UP.

So if you just add this one line to your script, you’ll get something that should keep the craft aimed straight up and not let it tip over. Add the line just after the line that sets the THROTTLE, like so:

//hellolaunch

//First, we'll clear the terminal screen to make it look nice
CLEARSCREEN.

//Next, we'll lock our throttle to 100%.
LOCK THROTTLE TO 1.0.   // 1.0 is the max, 0.0 is idle.

//This is our countdown loop, which cycles from 10 to 0
PRINT "Counting down:".
FROM {local countdown is 10.} UNTIL countdown = 0 STEP {SET countdown to countdown - 1.} DO {
    PRINT "..." + countdown.
    WAIT 1. // pauses the script here for 1 second.
}

//This is the line we added
LOCK STEERING TO UP.

UNTIL SHIP:MAXTHRUST > 0 {
    WAIT 0.5. // pause half a second between stage attempts.
    PRINT "Stage activated.".
    STAGE. // same as hitting the spacebar.
}

WAIT UNTIL SHIP:ALTITUDE > 70000.

// NOTE that it is vital to not just let the script end right away
// here.  Once a kOS script just ends, it releases all the controls
// back to manual piloting so that you can fly the ship by hand again.
// If the program just ended here, then that would cause the throttle
// to turn back off again right away and nothing would happen.

Again, copy this and run it, like before. If your craft crashed in the previous step, which it probably did, then revert to the VAB and re-launch it.:

SWITCH TO 1. // should be the default already, but just in case.
COPY HELLOLAUNCH FROM 0.
RUN HELLOLAUNCH.

Now you should see the same thing as before, but now your craft will stay pointed up.

But wait - it only does the first stage and then it stops without doing the next stage? how do I fix that?

Step 5: Add staging logic¶

The logic for how and when to stage can be an interesting and fun thing to write yourself. This example will keep it very simple, and this is the part where it’s important that you are using a vessel that only contains liquidfuel engines. If your vessel has some booster engines, then it would require a more sophisticated script to launch it correctly than this tutorial gives you.

To add the logic to check when to stage, we introduce a new concept called the WHEN trigger. To see full documentation on it when you finish the tutorial, look for it on the Flow Control page

The quick and dirty explanation is that a WHEN section is a short section of code that you set up to run LATER rather than right now. It creates a check in the background that will constantly look for some condition to occur, and when it happens, it interrupts whatever else the code is doing, and it will run the body of the WHEN code before continuing from where it left off in the main script.

There are some complex dangers with writing WHEN triggers that can cause KSP itself to hang or stutter if you are not careful, but explaining them is beyond the scope of this tutorial. But when you want to start using WHEN triggers yourself, you really should read the section on WHEN in the Flow Control page before you do so.

The WHEN trigger we are going to add to the launch script looks like this:

WHEN MAXTHRUST = 0 THEN {
    PRINT "Staging".
    STAGE.
    PRESERVE.
}.

It says, “Whenever the maximum thrust of our vehicle is zero, then activate the next stage.” The PRESERVE keyword says, “don’t stop checking this condition just because it’s been triggered once. It should still keep checking for it again in the future.” If this block of code is inserted into the script, then it will set up a constant background check that will always hit the next stage as soon as the current stage has no thrust. UNLIKE with all the previous edits this tutorial has asked you to make to the script, this time you’re going to be asked to delete something and replace it. The new WHEN section above should actually REPLACE the existing “UNTIL SHIP:MAXTHRUST > 0” loop that you had before.

Now your script should look like this:

//hellolaunch

//First, we'll clear the terminal screen to make it look nice
CLEARSCREEN.

//Next, we'll lock our throttle to 100%.
LOCK THROTTLE TO 1.0.   // 1.0 is the max, 0.0 is idle.

//This is our countdown loop, which cycles from 10 to 0
PRINT "Counting down:".
FROM {local countdown is 10.} UNTIL countdown = 0 STEP {SET countdown to countdown - 1.} DO {
    PRINT "..." + countdown.
    WAIT 1. // pauses the script here for 1 second.
}

//This is a trigger that constantly checks to see if our thrust is zero.
//If it is, it will attempt to stage and then return to where the script
//left off. The PRESERVE keyword keeps the trigger active even after it
//has been triggered.
WHEN MAXTHRUST = 0 THEN {
    PRINT "Staging".
    STAGE.
    PRESERVE.
}.

LOCK STEERING TO UP.

WAIT UNTIL ALTITUDE > 70000.

// NOTE that it is vital to not just let the script end right away
// here.  Once a kOS script just ends, it releases all the controls
// back to manual piloting so that you can fly the ship by hand again.
// If the program just ended here, then that would cause the throttle
// to turn back off again right away and nothing would happen.

Again, relaunch the ship, copy the script as before, and run it again. This time you should see it activate your later upper stages correctly.

Step 6: Now to make it turn¶

Okay that’s fine but it still just goes straight up! What about a gravity turn?

Well, a true and proper gravity turn is a very complex bit of math that is best left as an exercise for the reader, given that the goal of kOS is to let you write your OWN autopilot, not to write it for you. But to give some basic examples of commands, lets just make a crude gravity turn approximation that simply flies the ship like a lot of new KSP pilots learn to do it for the first time:

• Fly straight up until your velocity is 100m/s.
• Pitch ten degrees towards the East.
• Continue to pitch 10 degrees down for each 100m/s of velocity.

To make this work, we introduce a new way to make a Direction, called the HEADING function. Whenever you call the function HEADING(a,b), it makes a Direction oriented as follows on the navball:

• Point at the compass heading A.
• Pitch up a number of degrees from the horizon = to B.

So for example, HEADING(45,10) would aim northeast, 10 degrees above the horizon. We can use this to easily set our orientation. For example:

//This locks our steering to due east, pitched 45 degrees above the horizon.
LOCK STEERING TO HEADING(90,45).

Instead of using WAIT UNTIL to pause the script and keep it from exiting, we can use an UNTIL loop to constantly perform actions until a certain condition is met. For example:

UNTIL APOAPSIS > 100000 {
    LOCK STEERING TO HEADING(90,90). //90 degrees east and pitched up 90 degrees (straight up)
    PRINT ROUND(SHIP:APOAPSIS,0) AT (0,16). // prints new number, rounded to the nearest integer.
    //We use the PRINT AT() command here to keep from printing the same thing over and
    //over on a new line every time the loop iterates. Instead, this will always print
    //the apoapsis at the same point on the screen.
}.

This loop will continue to execute all of its instructions until the apoapsis reaches 100km. Once the apoapsis is past 100km, the loop exits and the rest of the code continues.

We can combine this with IF statements in order to have one main loop that only executes certain chunks of its code under certain conditions. For example:

UNTIL SHIP:APOAPSIS > 100000 { //Remember, all altitudes will be in meters, not kilometers

    //For the initial ascent, we want our steering to be straight
    //up and rolled due east
    IF SHIP:VELOCITY:SURFACE:MAG < 100 {
        //This sets our steering 90 degrees up and yawed to the compass
        //heading of 90 degrees (east)
        LOCK STEERING TO HEADING(90,90).

    //Once we pass 100m/s, we want to pitch down ten degrees
    } ELSE IF SHIP:VELOCITY:SURFACE:MAG >= 100 AND SHIP:VELOCITY:SURFACE:MAG < 200 {
        LOCK STEERING TO HEADING(90,80).
        PRINT "Pitching to 80 degrees" AT(0,15).
        PRINT ROUND(SHIP:APOAPSIS,0) AT (0,16).
    }.
}.

Each time this loop iterates, it will check the surface velocity. If the velocity is below 100m/s, it will continuously execute the first block of instructions. Once the velocity reaches 100m/s, it will stop executing the first block and start executing the second block, which will pitch the nose down to 80 degrees above the horizon.

Putting this into your script, it should look like this:

//hellolaunch

//First, we'll clear the terminal screen to make it look nice
CLEARSCREEN.

//Next, we'll lock our throttle to 100%.
LOCK THROTTLE TO 1.0.   // 1.0 is the max, 0.0 is idle.

//This is our countdown loop, which cycles from 10 to 0
PRINT "Counting down:".
FROM {local countdown is 10.} UNTIL countdown = 0 STEP {SET countdown to countdown - 1.} DO {
    PRINT "..." + countdown.
    WAIT 1. // pauses the script here for 1 second.
}

//This is a trigger that constantly checks to see if our thrust is zero.
//If it is, it will attempt to stage and then return to where the script
//left off. The PRESERVE keyword keeps the trigger active even after it
//has been triggered.
WHEN MAXTHRUST = 0 THEN {
    PRINT "Staging".
    STAGE.
    PRESERVE.
}.

//This will be our main control loop for the ascent. It will
//cycle through continuously until our apoapsis is greater
//than 100km. Each cycle, it will check each of the IF
//statements inside and perform them if their conditions
//are met
UNTIL SHIP:APOAPSIS > 100000 { //Remember, all altitudes will be in meters, not kilometers

    //For the initial ascent, we want our steering to be straight
    //up and rolled due east
    IF SHIP:VELOCITY:SURFACE:MAG < 100 {
        //This sets our steering 90 degrees up and yawed to the compass
        //heading of 90 degrees (east)
        LOCK STEERING TO HEADING(90,90).

    //Once we pass 100m/s, we want to pitch down ten degrees
    } ELSE IF SHIP:VELOCITY:SURFACE:MAG >= 100 {
        LOCK STEERING TO HEADING(90,80).
        PRINT "Pitching to 80 degrees" AT(0,15).
        PRINT ROUND(SHIP:APOAPSIS,0) AT (0,16).
    }.
}.

Again, copy this into your script and run it. You should see your countdown occur, then it will launch. Once the ship passes 100m/s surface velocity, it will pitch down to 80 degrees and continuously print the apoapsis until the apoapsis reaches 100km, staging if necessary. The script will then end.

Step 7: Putting it all together¶

We now have every element of the script necessary to do a proper (albeit simple) gravity turn. We just need to extend it all the way through the ascent.

Adding additional IF statements inside our main loop will allow us to perform further actions based on our velocity. Each IF statement you see in the script below covers a 100m/s block of velocity, and will adjust the pitch 10 degrees farther down than the previous block.

You can see that with the AND statement, we can check multiple conditions and only execute that block when all of those conditions are true. We can carefully set up the conditions for each IF statement to allow a block of code to be executed no matter what our surface velocity is.

Copy this into your script and run it. It should take you nearly to orbit:

//hellolaunch

//First, we'll clear the terminal screen to make it look nice
CLEARSCREEN.

//Next, we'll lock our throttle to 100%.
LOCK THROTTLE TO 1.0.   // 1.0 is the max, 0.0 is idle.

//This is our countdown loop, which cycles from 10 to 0
PRINT "Counting down:".
FROM {local countdown is 10.} UNTIL countdown = 0 STEP {SET countdown to countdown - 1.} DO {
    PRINT "..." + countdown.
    WAIT 1. // pauses the script here for 1 second.
}

//This is a trigger that constantly checks to see if our thrust is zero.
//If it is, it will attempt to stage and then return to where the script
//left off. The PRESERVE keyword keeps the trigger active even after it
//has been triggered.
WHEN MAXTHRUST = 0 THEN {
    PRINT "Staging".
    STAGE.
    PRESERVE.
}.

//This will be our main control loop for the ascent. It will
//cycle through continuously until our apoapsis is greater
//than 100km. Each cycle, it will check each of the IF
//statements inside and perform them if their conditions
//are met
UNTIL SHIP:APOAPSIS > 100000 { //Remember, all altitudes will be in meters, not kilometers

    //For the initial ascent, we want our steering to be straight
    //up and rolled due east
    IF SHIP:VELOCITY:SURFACE:MAG < 100 {
        //This sets our steering 90 degrees up and yawed to the compass
        //heading of 90 degrees (east)
        LOCK STEERING TO HEADING(90,90).

    //Once we pass 100m/s, we want to pitch down ten degrees
    } ELSE IF SHIP:VELOCITY:SURFACE:MAG >= 100 AND SHIP:VELOCITY:SURFACE:MAG < 200 {
        LOCK STEERING TO HEADING(90,80).
        PRINT "Pitching to 80 degrees" AT(0,15).
        PRINT ROUND(SHIP:APOAPSIS,0) AT (0,16).

    //Each successive IF statement checks to see if our velocity
    //is within a 100m/s block and adjusts our heading down another
    //ten degrees if so
    } ELSE IF SHIP:VELOCITY:SURFACE:MAG >= 200 AND SHIP:VELOCITY:SURFACE:MAG < 300 {
        LOCK STEERING TO HEADING(90,70).
        PRINT "Pitching to 70 degrees" AT(0,15).
        PRINT ROUND(SHIP:APOAPSIS,0) AT (0,16).

    } ELSE IF SHIP:VELOCITY:SURFACE:MAG >= 300 AND SHIP:VELOCITY:SURFACE:MAG < 400 {
        LOCK STEERING TO HEADING(90,60).
        PRINT "Pitching to 60 degrees" AT(0,15).
        PRINT ROUND(SHIP:APOAPSIS,0) AT (0,16).

    } ELSE IF SHIP:VELOCITY:SURFACE:MAG >= 400 AND SHIP:VELOCITY:SURFACE:MAG < 500 {
        LOCK STEERING TO HEADING(90,50).
        PRINT "Pitching to 50 degrees" AT(0,15).
        PRINT ROUND(SHIP:APOAPSIS,0) AT (0,16).

    } ELSE IF SHIP:VELOCITY:SURFACE:MAG >= 500 AND SHIP:VELOCITY:SURFACE:MAG < 600 {
        LOCK STEERING TO HEADING(90,40).
        PRINT "Pitching to 40 degrees" AT(0,15).
        PRINT ROUND(SHIP:APOAPSIS,0) AT (0,16).

    } ELSE IF SHIP:VELOCITY:SURFACE:MAG >= 600 AND SHIP:VELOCITY:SURFACE:MAG < 700 {
        LOCK STEERING TO HEADING(90,30).
        PRINT "Pitching to 30 degrees" AT(0,15).
        PRINT ROUND(SHIP:APOAPSIS,0) AT (0,16).

    } ELSE IF SHIP:VELOCITY:SURFACE:MAG >= 700 AND SHIP:VELOCITY:SURFACE:MAG < 800 {
        LOCK STEERING TO HEADING(90,11).
        PRINT "Pitching to 20 degrees" AT(0,15).
        PRINT ROUND(SHIP:APOAPSIS,0) AT (0,16).

    //Beyond 800m/s, we can keep facing towards 10 degrees above the horizon and wait
    //for the main loop to recognize that our apoapsis is above 100km
    } ELSE IF SHIP:VELOCITY:SURFACE:MAG >= 800 {
        LOCK STEERING TO HEADING(90,10).
        PRINT "Pitching to 10 degrees" AT(0,15).
        PRINT ROUND(SHIP:APOAPSIS,0) AT (0,16).

    }.

}.

PRINT "100km apoapsis reached, cutting throttle".

//At this point, our apoapsis is above 100km and our main loop has ended. Next
//we'll make sure our throttle is zero and that we're pointed prograde
LOCK THROTTLE TO 0.

//This sets the user's throttle setting to zero to prevent the throttle
//from returning to the position it was at before the script was run.
SET SHIP:CONTROL:PILOTMAINTHROTTLE TO 0.

And here is it in action:

And toward the end:

This script should, in principle, work to get you to the point of leaving the atmosphere. It will probably still fall back down, because this script makes no attempt to ensure that the craft is going fast enough to maintain the orbit.

As you can probably see, it would still have a long way to go before it would become a really GOOD launching autopilot. Think about the following features you could add yourself as you become more familiar with kOS:

• You could change the steering logic to make a more smooth gravity turn by constantly adjusting the pitch in the HEADING according to some math formula. The example shown here tends to create a “too high” launch that’s a bit inefficient. In addition, this method relies on velocity to determine pitch angle, which could result in some very firey launches for other ships with a higher TWR profile.
• This script just stupidly leaves the throttle at max the whole way. You could make it more sophisticated by adjusting the throttle as necessary to avoid velocities that result in high atmospheric heating.
• This script does not attempt to circularize. With some simple checks of the time to apoapsis and the orbital velocity, you can execute a burn that circularizes your orbit.
• With even more sophisticated checks, the script could be made to work with fancy staging methods like asaparagus.
• Using the PRINT AT command, you can make fancier status readouts in the terminal window as the script runs.

The Major Design Patterns of kOS Control Programs¶

The design of a program is usually determined by the flow-control statements used. I.e., the WHEN/THEN, ON, WAIT, UNTIL, IF and FOR constructs. Here is a list of the major styles of control programs that can be written in kOS:

1. Sequential
2. Loops with Condition Checking
3. Loops with Triggers

Of course, one style does not fit all scenarios and the programmer will typically want to use a combination of these all at once. Also, there may be other design patterns not listed here which can be perfectly valid, but this is a start.

LOCK STEERING TO HEADING(0,90).
LOCK THROTTLE TO 1.
STAGE.
WAIT UNTIL SHIP:ALTITUDE > 10000.
LOCK STEERING TO HEADING(0,90) + R(0,-45,0).
WAIT UNTIL STAGE:LIQUIDFUEL < 0.1.
STAGE.
WAIT UNTIL SHIP:ALTITUDE > 20000.
LOCK THROTTLE TO 0.
WAIT UNTIL FALSE. // CTRL+C to break out

LOCK STEERING TO R(0,0,-90) + HEADING(90,90).
LOCK THROTTLE TO 1.
STAGE.
UNTIL SHIP:ALTITUDE > 20000 {
    IF SHIP:ALTITUDE > 10000 {
        LOCK STEERING TO R(0,0,-90) + HEADING(90,45).
    }
    IF STAGE:LIQUIDFUEL < 0.1 {
        STAGE.
    }
}
LOCK THROTTLE TO 0.
WAIT UNTIL FALSE.

LOCK STEERING TO R(0,0,-90) + HEADING(90,90).
LOCK THROTTLE TO 1.
STAGE.
WHEN SHIP:ALTITUDE > 10000 THEN {
    LOCK STEERING TO R(0,0,-90) + HEADING(90,45).
}
UNTIL SHIP:ALTITUDE > 20000 {
    IF STAGE:LIQUIDFUEL < 0.1 {
        STAGE.
    }
}
LOCK THROTTLE TO 0.
WAIT UNTIL FALSE.

WHEN STAGE:LIQUIDFUEL < 0.1 THEN {
    STAGE.
    PRESERVE.
}
LOCK STEERING TO R(0,0,-90) + HEADING(90,90).
LOCK THROTTLE TO 1.
STAGE.
WHEN SHIP:ALTITUDE > 10000 THEN {
    LOCK STEERING TO R(0,0,-90) + HEADING(90,45).
}
WAIT UNTIL SHIP:ALTITUDE > 20000.
LOCK THROTTLE TO 0.
WAIT UNTIL FALSE.

General Guidelines for kOS Scripts¶

This section discusses two general guidelines to follow when starting out with more complicated kOS scripts. These are not meant to be absolute and there will certainly be cases when they can be stretched, though one should never totally ignore them.

SET thrott TO 1.
LOCK THROTTLE TO thrott.
LOCK STEERING TO R(0,0,-90) + HEADING(90,90).
STAGE.
WHEN SHIP:ALTITUDE > 1000 THEN {
    SET g TO KERBIN:MU / KERBIN:RADIUS^2.
    LOCK accvec TO SHIP:SENSORS:ACC - SHIP:SENSORS:GRAV.
    LOCK gforce TO accvec:MAG / g.
    LOCK dthrott TO 0.05 * (1.2 - gforce).

    UNTIL SHIP:ALTITUDE > 40000 {
        WHEN STAGE:LIQUIDFUEL < 0.1 THEN {
            STAGE.
            PRESERVE.
        }
        SET thrott to thrott + dthrott.
        WAIT 0.1.
    }
}

WHEN STAGE:LIQUIDFUEL < 0.1 THEN {
    STAGE.
    PRESERVE.
}
SET thrott TO 1.
SET dthrott TO 0.
LOCK THROTTLE TO thrott.
LOCK STEERING TO R(0,0,-90) + HEADING(90,90).
STAGE.
WHEN SHIP:ALTITUDE > 1000 THEN {
    SET g TO KERBIN:MU / KERBIN:RADIUS^2.
    LOCK accvec TO SHIP:SENSORS:ACC - SHIP:SENSORS:GRAV.
    LOCK gforce TO accvec:MAG / g.
    LOCK dthrott TO 0.05 * (1.2 - gforce).
}
UNTIL SHIP:ALTITUDE > 40000 {
    SET thrott to thrott + dthrott.
    WAIT 0.1.
}

WHEN STAGE:LIQUIDFUEL < 0.1 THEN {
    STAGE.
    PRESERVE.
}
SET thrott TO 1.
SET dthrott TO 0.
LOCK THROTTLE TO thrott.
LOCK STEERING TO R(0,0,-90) + HEADING(90,90).
STAGE.
WHEN SHIP:ALTITUDE > 1000 THEN {
    SET g TO KERBIN:MU / KERBIN:RADIUS^2.
    LOCK accvec TO SHIP:SENSORS:ACC - SHIP:SENSORS:GRAV.
    LOCK gforce TO accvec:MAG / g.
    LOCK dthrott TO 0.05 * (1.2 - gforce).
}
WHEN SHIP:ALTITUDE > 10000 THEN {
    LOCK dthrott TO 0.05 * (2.0 - gforce).
}
WHEN SHIP:ALTITUDE > 20000 THEN {
    LOCK dthrott TO 0.05 * (4.0 - gforce).
}
WHEN SHIP:ALTITUDE > 30000 THEN {
    LOCK dthrott TO 0.05 * (5.0 - gforce).
}
UNTIL SHIP:ALTITUDE > 40000 {
    SET thrott to thrott + dthrott.
    WAIT 0.1.
}

WHEN STAGE:LIQUIDFUEL < 0.1 THEN {
    STAGE.
    PRESERVE.
}
SET thrott TO 1.
SET dthrott TO 0.
LOCK THROTTLE TO thrott.
LOCK STEERING TO R(0,0,-90) + HEADING(90,90).
STAGE.
WHEN SHIP:ALTITUDE > 1000 THEN {
    SET g TO KERBIN:MU / KERBIN:RADIUS^2.
    LOCK accvec TO SHIP:SENSORS:ACC - SHIP:SENSORS:GRAV.
    LOCK gforce TO accvec:MAG / g.
    LOCK dthrott TO 0.05 * (1.2 - gforce).

    WHEN SHIP:ALTITUDE > 10000 THEN {
        LOCK dthrott TO 0.05 * (2.0 - gforce).

        WHEN SHIP:ALTITUDE > 20000 THEN {
            LOCK dthrott TO 0.05 * (4.0 - gforce).

            WHEN SHIP:ALTITUDE > 30000 THEN {
                LOCK dthrott TO 0.05 * (5.0 - gforce).
            }
        }
    }
}
UNTIL SHIP:ALTITUDE > 40000 {
    SET thrott to thrott + dthrott.
    WAIT 0.1.
}

Proportional Feedback Loop (P-loop)¶

The example code from the Design Patterns Tutorial, with some slight modifications looks like the following:

// staging, throttle, steering, go
WHEN STAGE:LIQUIDFUEL < 0.1 THEN {
    STAGE.
    PRESERVE.
}
LOCK THROTTLE TO 1.
LOCK STEERING TO R(0,0,-90) + HEADING(90,90).
STAGE.
WAIT UNTIL SHIP:ALTITUDE > 1000.

// P-loop setup
SET g TO KERBIN:MU / KERBIN:RADIUS^2.
LOCK accvec TO SHIP:SENSORS:ACC - SHIP:SENSORS:GRAV.
LOCK gforce TO accvec:MAG / g.
LOCK dthrott TO 0.05 * (1.2 - gforce).

SET thrott TO 1.
LOCK THROTTLE to thrott.

UNTIL SHIP:ALTITUDE > 40000 {
    SET thrott to thrott + dthrott.
    WAIT 0.1.
}

The first several lines sets up a simple staging condition, puts the throttle to maximum, steers the rocket straight up and launches. The rocket is assumed to use only liquid fuel engines. After the rocket hits 1km, the script sets up the LOCK used in the P-loop which is updated every 0.1 seconds in the UNTIL loop. The use of LOCK variables makes this code fairly clean. When the script comes up to the first line in the UNTIL loop, i.e. “SET thrott TO thrott + dthrott.”, the variable dthrott is evaluated which causes the LOCK on gforce to be evaluated which in-turn causes accvec to be evaluated.

The input to this feedback loop is the acceleration experienced by the ship (gforce) in terms of Kerbin’s gravitational acceleration at sea level (g). The variable accvec is the total acceleration vector and is obtained by the accelerometer and gravioli detectors, both of which must be on the ship for this to work. The variable dthrott is the change in throttle that should be applied in a single iteration of the feedback loop.

In terms of a PID loop, the factor 1.2 is called the setpoint, gforce is the process variable and 0.05 is called the proportional gain. The setpoint and gain factors can be promoted to their own variables with names. Also, the code up to and including the “WAIT UNTIL SHIP:ALTITUDE > 1000.” will be implied for the next few examples of code:

// P-loop
SET g TO KERBIN:MU / KERBIN:RADIUS^2.
LOCK accvec TO SHIP:SENSORS:ACC - SHIP:SENSORS:GRAV.
LOCK gforce TO accvec:MAG / g.

SET gforce_setpoint TO 1.2.
SET Kp TO 0.05.
LOCK dthrott TO Kp * (gforce_setpoint - gforce).

SET thrott TO 1.
LOCK THROTTLE to thrott.

UNTIL SHIP:ALTITUDE > 40000 {
    SET thrott to thrott + dthrott.
    WAIT 0.1.
}

This is not a big change, but it will set us up to include the integral and derivative terms in the next section.

Proportional-Integral Feedback Loop (PI-loop)¶

Adding the integral term requires us to keep track of time. This is done by introducing a variable (t0) to store the time of the last iteration. Now, the throttle is changed only on iterations where some time has elapsed so the WAIT time in the UNTIL can be brought to 0.001. The offset of the gforce has been set to the variable P, and the integral gain to Ki.

// PI-loop
SET g TO KERBIN:MU / KERBIN:RADIUS^2.
LOCK accvec TO SHIP:SENSORS:ACC - SHIP:SENSORS:GRAV.
LOCK gforce TO accvec:MAG / g.

SET gforce_setpoint TO 1.2.

LOCK P TO gforce_setpoint - gforce.
SET I TO 0.

SET Kp TO 0.01.
SET Ki TO 0.006.

LOCK dthrott TO Kp * P + Ki * I.

SET thrott TO 1.
LOCK THROTTLE to thrott.

SET t0 TO TIME:SECONDS.
UNTIL SHIP:ALTITUDE > 40000 {
    SET dt TO TIME:SECONDS - t0.
    IF dt > 0 {
        SET I TO I + P * dt.
        SET thrott to thrott + dthrott.
        SET t0 TO TIME:SECONDS.
    }
    WAIT 0.001.
}

Adding the integral term has the general effect of stabilizing the feedback loop, making it less prone to oscillating due to rapid changes in the process variable (gforce, in this case). This is usually at the expense of a longer settling time.

Proportional-Integral-Derivative Feedback Loop (PID-loop)¶

Incorporating the derivative term (D) and derivative gain (Kd) requires an additional variable (P0) to keep track of the previous value of the proportional term (P).

// PID-loop
SET g TO KERBIN:MU / KERBIN:RADIUS^2.
LOCK accvec TO SHIP:SENSORS:ACC - SHIP:SENSORS:GRAV.
LOCK gforce TO accvec:MAG / g.

SET gforce_setpoint TO 1.2.

LOCK P TO gforce_setpoint - gforce.
SET I TO 0.
SET D TO 0.
SET P0 TO P.

SET Kp TO 0.01.
SET Ki TO 0.006.
SET Kd TO 0.006.

LOCK dthrott TO Kp * P + Ki * I + Kd * D.

SET thrott TO 1.
LOCK THROTTLE to thrott.

SET t0 TO TIME:SECONDS.
UNTIL SHIP:ALTITUDE > 40000 {
    SET dt TO TIME:SECONDS - t0.
    IF dt > 0 {
        SET I TO I + P * dt.
        SET D TO (P - P0) / dt.
        SET thrott to thrott + dthrott.
        SET P0 TO P.
        SET t0 TO TIME:SECONDS.
    }
    WAIT 0.001.
}

When tuned properly, the derivative term will cause the PID-loop to act quickly without causing problematic oscillations. Later in this tutorial, we will cover a way to tune a PID-loop using only the proportional term called the Zieger-Nichols method.

Final Touches¶

There are a few modifications that can make PID loops very robust. The following code example adds three range limits:

1. bounds on the Integral term which addresses possible integral windup
2. bounds on the throttle since it must stay in the range 0 to 1
3. a deadband to avoid changing the throttle due to small fluctuations

Of course, KSP is a simulator and small fluctuations are not observed in this particular loop. Indeed, the P-loop is sufficient in this example, but all these features are included here for illustration purposes and they could become useful for unstable aircraft or untested scenarios.

// PID-loop
SET g TO KERBIN:MU / KERBIN:RADIUS^2.
LOCK accvec TO SHIP:SENSORS:ACC - SHIP:SENSORS:GRAV.
LOCK gforce TO accvec:MAG / g.

SET gforce_setpoint TO 1.2.

LOCK P TO gforce_setpoint - gforce.
SET I TO 0.
SET D TO 0.
SET P0 TO P.

LOCK in_deadband TO ABS(P) < 0.01.

SET Kp TO 0.01.
SET Ki TO 0.006.
SET Kd TO 0.006.

LOCK dthrott TO Kp * P + Ki * I + Kd * D.

SET thrott TO 1.
LOCK THROTTLE to thrott.

SET t0 TO TIME:SECONDS.
UNTIL SHIP:ALTITUDE > 40000 {
    SET dt TO TIME:SECONDS - t0.
    IF dt > 0 {
        IF NOT in_deadband {
            SET I TO I + P * dt.
            SET D TO (P - P0) / dt.

            // If Ki is non-zero, then limit Ki*I to [-1,1]
            IF Ki > 0 {
                SET I TO MIN(1.0/Ki, MAX(-1.0/Ki, I)).
            }

            // set throttle but keep in range [0,1]
            SET thrott to MIN(1, MAX(0, thrott + dthrott)).

            SET P0 TO P.
            SET t0 TO TIME:SECONDS.
        }
    }
    WAIT 0.001.
}

Tuning a PID-loop¶

We are going to start with the same rocket design we have been using so far and actually tune the PID-loop using the Ziegler-Nichols method. This is where we turn off the integral and derivative terms in the loop and bring the proportional gain (Kp) up from zero to the point where the loop causes a steady oscillation with a measured period (Tu). At this point, the proportional gain is called the “ultimate gain” (Ku) and the actual gains (Kp, Ki and Kd) are set according to this table taken from wikipedia:

An immediate problem to overcome with this method is that it assumes a steady state can be achieved. With rockets, there is never a steady state: fuel is being consumed, altitude and therefore gravity and atmosphere is changing, staging can cause major upsets in the feedback loop. So, this tuning method will be some approximation which should come as no surprise since it will come from experimental observation. All we need is enough of a steady state that we can measure the oscillations - both the change in amplitude and the period.

The script we’ll use to tune the highly overpowered rocket shown will launch the rocket straight up (using SAS) and will log data to an output file until it reaches 30km at which point the log file will be copied to the archive and the program will terminate. Also, this time the feedback loop will be based on the more realistic “atmospheric efficiency.” The log file will contain three columns: time since launch, offset of atmospheric efficiency from the ideal (in this case, 1.0) and the ship’s maximum thrust. The maximum thrust will increase monotonically with time (this rocket has only one stage) and we’ll use both as the x-axis when plotting the offset on the y-axis.

DECLARE PARAMETER Kp.

LOCK g TO SHIP:BODY:MU / (SHIP:BODY:RADIUS + SHIP:ALTITUDE)^2.
LOCK maxtwr TO SHIP:MAXTHRUST / (g * SHIP:MASS).

// feedback based on atmospheric efficiency
LOCK surfspeed TO SHIP:VELOCITY:SURFACE:MAG.
LOCK atmoeff TO surfspeed / SHIP:TERMVELOCITY.
LOCK P TO 1.0 - atmoeff.

SET t0 TO TIME:SECONDS.
LOCK dthrott TO Kp*P.
SET start_time TO t0.

LOG "# Throttle PID Tuning" TO throttle_log.
LOG "# Kp: " + Kp TO throttle_log.
LOG "# t P maxtwr" TO throttle_log.

LOCK logline TO (TIME:SECONDS - start_time)
        + " " + P
        + " " + maxtwr.

SET thrott TO 1.
LOCK THROTTLE TO thrott.
SAS ON.
STAGE.
WAIT 3.

UNTIL SHIP:ALTITUDE > 30000 {
    SET dt TO TIME:SECONDS - t0.
    IF dt > 0 {
        SET thrott TO MIN(1,MAX(0,thrott + dthrott)).
        SET t0 TO TIME:SECONDS.
        LOG logline TO throttle_log.
    }
    WAIT 0.001.
}
COPY throttle_log TO 0.

Give this script a short name, something like “tune.txt” so that running is simple:

copy tune from 0.
run tune(0.5).

After every launch completes, you’ll have to go into the archive directory and rename the output logfile. Something like “throttle_log.txt” –> “throttle.01.log” will help if you increment the index number each time. To analyze the data, plot the offset (P) as a function of time (t). Here, we show the results for three values of Kp: 0.002, 0.016 and 0.160, including the maximum TWR when Kp = 0.002 as the top x-axis. The maximum TWR dependence on time is different for the three values of Kp, but not by a lot.

The value of 0.002 is obviously too low. The settling time is well over 20 seconds and the loop can’t keep up with the increase in terminal velocity at the higher altitudes reached after one minute. When Kp = 0.016, the behavior is far more well behaved, and though some oscillation exists, it’s damped and slow with a period of about 10 seconds. At Kp = 0.160, the oscillations are prominent and we can start to measure the change in amplitude along with the period of the oscillations. This plot shows the data for Kp = 0.160 from 20 to 40 seconds after ignition. The peaks are found and are fit to a line.

This is done for each value of Kp and the slopes of the fitted lines are plotted as a function of Kp in the following plot:

The period of oscillation was averaged over the interval and plotted on top of the amplitude change over time. Notice the turn over that occurs when Kp reaches approximately 0.26. This will mark the “ultimate gain” and 3.1 seconds will be used as the associated period of oscillation. It is left as an exercise for the reader to implement a full PID-loop using the classic PID values (see table above): Kp = 0.156, Ki = 0.101, Kd = 0.060, producing this behavior:

As soon as the PID-loop was activated at 3 seconds after ignition, the throttle was cut. At approximately 7 seconds, the atmospheric efficiency dropped below 100% and the integral term started to climb back to zero. At 11 seconds, the engine was reignited and the feedback loop settled after about 20 seconds. The inset plot has the same axes as the parent and shows the long-term stability of the final PID-loop.

Final Thoughts¶

The classic PID values used above are fairly aggressive and there is some overshoot at the beginning. This can be dealt with in many ways and is discussed on the wikipedia page about PID controllers. For example, one might consider trying to implement a switch to a PD-loop when the integral term hits some limit, switching back once P crosses zero. The PID behavior should look like the following:

Finally, Controlling the throttle of a rocket is perhaps the easiest thing to implement as a PID loop in KSP using kOS. The steering was largely ignored and the orientation was always up. When writing an autopilot for horizontal atmospheric flight, one will have to deal with the direction the ship is traveling using SHIP:HEADING as well as it’s orientation with SHIP:FACING. Additionally, there are the SHIP:ROTATION and SHIP:TRANSLATION vectors which can tell you the rate of change of the ship’s facing and heading respectively. The controls in this case are six-dimensional using SHIP:CONTROL with YAW, PITCH, ROLL, FORE, STARBOARD, TOP and MAINTHROTTLE.

The PID gain parameters are dependent on the characteristics of the ship being controlled. The size, shape, turning capability and maximum TWR should be considered when tuning a PID loop. Turning RCS on can also have an effect and you might consider changing the PID loop’s gain parameters every time to switch them on or off.

NAMED VESSELS AND BODIES¶

SHIP:

TARGET:

Alias shortcuts for SHIP fields¶

The following are all alias shortcuts for accessing the fields of the SHIP vessel. To see their definition, please consult the Vessel page, as they are all just instances of the standard vessel suffixes.

Constants (pi, e, etc)¶

Get-only.

The variable constant provides a way to access a few basic math and physics constants, such as Pi, Euler’s number, and so on.

Example:

print "Kerbin's circumference: " + (2*constant:pi*Kerbin:radius) + "meters.".

The full list is here: constants page.

Terminal¶

Get-only. terminal returns a terminal structure describing the attributes of the current terminal screen associated with the CPU this script is running on.

Core¶

Get-only. core returns a core structure referring to the CPU you are running on.

Stage¶

Get-only. stage returns a stage structure used to count resources in the current stage. Not to be confused with the COMMAND stage which triggers the next stage.

NextNode¶

Get-only. nextnode returns the next planned manuever node in the SHIP’s flight plan. Bombs out if no such node exists.

Resource Types¶

Any time there is a resource on the ship it can be queried. The resources are the values that appear when you click on the upper-right corner of the screen in the KSP window.

LIQUIDFUEL
OXIDIZER
ELECTRICCHARGE
MONOPROPELLANT
INTAKEAIR
SOLIDFUEL

All of the above resources can be queried using either the prefix SHIP or STAGE, depending on whether you are trying to query how much is left in the current stage or the entire ship:

How much liquid fuel is left in the entire ship:

PRINT "There is " + SHIP:LIQUIDFUEL + " liquid fuel on the ship.".

How much liquid fuel is left in just the current stage:

PRINT "There is " + STAGE:LIQUIDFUEL + " liquid fuel in this stage.".

How much liquid fuel is left in the target vessel:

PRINT "There is " + TARGET:LIQUIDFUEL + " liquid fuel in the target ship.".

Any other resources that you have added using other mods should be query-able this way, provided that you spell the term exactly as it appears in the resources window.

You can also get a list of all resources, either in SHIP: or STAGE: with the :RESOURCES suffix.

ALT ALIAS¶

The special variable ALT gives you access to a few altitude predictions:

ALT:APOAPSIS

ALT:PERIAPSIS

ALT:RADAR

Further details are found on the ALT page .

ETA ALIAS¶

The special variable ETA gives you access to a few time predictions:

ETA:APOAPSIS

ETA:PERIAPSIS

ETA:TRANSITION

Further details are found on the ETA page .

ENCOUNTER¶

The orbit patch describing the next encounter with a body the current vessel will enter. If there is no such encounter coming, it will return the special string “None”. If there is an encounter coming, it will return an object of type Orbit. (i.e. to obtain the name of the planet the encounter is with, you can do: print ENCOUNTER:BODY:NAME., for example.).

BOOLEAN TOGGLE FIELDS:¶

These are variables that behave like boolean flags. They can be True or False, and can be set or toggled using the “ON” and “OFF” and “TOGGLE” commands. Many of these are for action group flags. NOTE ABOUT ACTION GROUP FLAGS: If the boolean flag is for an action group, be aware that each time the user presses the action group keypress, it toggles the action group, so you might need to check for both the change in state from false to true AND the change in state from true to false to see if the key was hit.

Flight Control¶

There are bound variables used in controlling the flight of a ship, which can be found at the following links:

If you want to let kOS do a lot of the work of aligning to a desired heading for you, use Cooked Control.

If you want your script to manipulate the controls directly (as in “set yaw axis halfway left for a few seconds (using the ‘A’ key)”, then use Raw Control.

If you want to be able to READ what the player is attempting to do while your script is running, and perhaps respond to it, then use Reading the Pilot’s Control settings (i.e reading what the manual input is attempting) (By default your script will override manual piloting attempts, but you can read what the pilot’s controls are set at and make your autopilot take them under advisement - sort of like how a fly-by-wire plane works.)

THROTTLE            // Lock to a decimal value between 0 and 1.
STEERING            // Lock to a direction, either a Vector or a Direction.
WHEELTHROTTLE       // Separate throttle for wheels
WHEELSTEERING       // Separate steering system for wheels

Time¶

Time is the simulated amount of time that passed since the beginning of the game’s universe epoch. (A brand new campaign that just started begins at TIME zero.)

TIME is a useful system variable for calculating the passage of time between taking physical measurements (i.e. to calculate how fast a phenomenon is changing in a loop). It returns the KSP simulated time, rather than the actual realtime sitting in the chair playing the game. If everything is running smoothly on a fast computer, one second of simulated time will match one second of real time, but if anything is causing the game to stutter or lag a bit, then the simulated time will be a bit slower than the real time. For any script program trying to calculate physical properties of the KSP universe, the time that matters is the simulated time, which is what TIME returns.

It’s important to be aware of the frozen update nature of the kOS computer when reading TIME.

System Variables¶

This section is about variables that describe the things that are slightly outside the simulated universe of the game and are more about the game’s user interface or the kOS mod itself. They represent things that slightly “break the fourth wall” and let your script access something entirely outside the in-character experience.

PRINT VERSION.            // Returns operating system version number. e.g. 0.8.6
PRINT VERSION:MAJOR.      // Returns major version number. e.g. 0
PRINT VERSION:MINOR.      // Returns minor version number. e.g. 8
PRINT VERSION:BUILD.      // Returns build version number. e.g. 6
PRINT SESSIONTIME.        // Returns amount of time, in seconds, from vessel load.

NOTE the following important difference:

SESSIONTIME is the time since the last time this vessel was loaded from on-rails into full physics.

TIME is the time since the entire saved game campaign started, in the kerbal universe’s time. i.e. TIME = 0 means a brand new campaign was just started.

SOLARPRIMEVECTOR¶

Gives the Prime Meridian Vector for the Solar System itself, in current Ship-Raw XYZ coordinates.

Both the Orbit:LONGITUDEOFASCENDINGNODE orbit suffix and the Body:ROTATIONANGLE body suffix are expressed in terms of degree offsets from this Prime Meridian Reference Vector.

Addons¶

Get-only. addons is a special variable used to access various extensions to kOS that are designed to support the features introduced by some other mods. More info can be found on the addons page.

Colors¶

There are several bound variables associated with hardcoded colors such as WHITE, BLACK, RED, etc. See the linked page for the full list.

Update Ticks and Physics Ticks¶

Kerbal Space Program simulates the universe by running the universe in small incremental time intervals that for the purpose of this document, we will call “physics ticks”. The exact length of time for a physics tick varies as the program runs. One physics tick might take 0.09 seconds while the next one might take 0.085 seconds. (The default setting for the rate of physics ticks is 25 ticks per second, just to give a ballpark figure, but you must not write any scripts that depend on this assumption because it’s a setting the user can change, and it can also vary a bit during play depending on system load. The setting is a target goal for the game to try to achieve, not a guarantee. If it’s a fast computer with a speedy animation frame rate, it will try to run physics ticks less often than it runs animation frame updates, to try to make the physics tick rate match this setting. On the other hand, If it’s a slow computer, it will try to sacrifice animation frame rate to archive this number (meaning physics get calculated faster than you can see the effects.)

When calculating physics formulas, you need to actually measure elapsed time in the TIME:SECONDS variable in your scripts.

The entire simulated universe is utterly frozen during the duration of a physics tick. For example, if one physics tick occurs at timestamp 10.51 seconds, and the next physics tick occurs 0.08 seconds later at timestamp 10.59 seconds, then during the entire intervening time, at timestamp 10.52 seconds, 10.53 seconds, and so on, nothing moves. The clock is frozen at 10.51 seconds, and the fuel isn’t being consumed, and the vessel is at the same position. On the next physics tick at 10.59 seconds, then all the numbers are updated. The full details of the physics ticks system are more complex than that, but that quick description is enough to describe what you need to know about how kOS’s CPU works.

There is another kind of time tick called an Update tick. It is similar to, but different from, a physics tick. Update ticks often occur a bit more often than physics ticks. Update ticks are exactly the same thing as your game’s Frame Rate. Each time your game renders another animation frame, it performs another Update tick. On a good gaming computer with fast speed and a good graphics card, It is typical to have about 2 or even 3 Update ticks happen within the time it takes to have one physics tick happen. On a slower computer, it is also possible to go the other way and have Update ticks happening less frequently than physics tics. Basically, look at your frame rate. Is it higher than 25 fps? If so, then your update ticks happen faster than your physics ticks, otherwise its the other way around.

On each physics tick, each kOS CPU that’s within physics range (i.e. 2.5 km), wakes up and performs the following steps, in this order:

1. Run the conditional checks of all TRIGGERS (see below)
2. For any TRIGGERS who’s conditional checks are true, execute the entire body of the trigger.
3. If there’s a pending WAIT statement, check if it’s done. If so wake up.
4. If awake, then execute the next Config:IPU number of instructions of the main program.

Note that the number of instructions being executed (CONFIG:IPU) are NOT lines of code or kerboscript statements, but rather the smaller instruction opcodes that they are compiled into behind the scenes. A single kerboscript statement might become anywhere from one to ten or so instructions when compiled.

Triggers¶

There are multiple things within kerboscript that run “in the background” always updating, while the main script continues on. The way these work is a bit like a real computer’s multithreading, but not quite. Collectively all of these things are called “triggers”.

Triggers are all of the following:

• LOCKS which are attached to flight controls (THROTTLE, STEERING, etc), but not other LOCKS.
• ON condition { some commands }.
• WHEN condition THEN { some commands }.

The way these work is that once per physics tick, all the LOCK expressions which directly affect flight control are re-executed, and then each conditional trigger’s condition is checked, and if true, then the entire body of the trigger is executed all the way to the bottom *before any more instructions of the main body are executed*. This means that execution of a trigger never gets interleaved with the main code. Once a trigger happens, the entire trigger occurs all in one go before the rest of the main body continues.

WAIT 0.001.

WAIT UNTIL TRUE.

The Frozen Universe¶

Each physics tick, the kOS mod wakes up and runs through all the currently loaded CPU parts that are in “physics range” (i.e. 2.5 km), and executes a batch of instructions from your script code that’s on them. It is important to note that during the running of this batch of instructions, because no physics ticks are happening during it, none of the values that you might query from the KSP system will change. The clock time returned from the TIME variable will keep the same value throughout. The amount of fuel left will remain fixed throughout. The position and velocity of the vessel will remaining fixed throughout. It’s not until the next physics tick occurs that those values will change to new numbers. It’s typical that several lines of your kerboscript code will run during a single physics tick.

Effectively, as far as the simulated universe can tell, it’s as if your script runs several instructions in literally zero amount of time, and then pauses for a fraction of a second, and then runs more instructions in literally zero amount of time, then pauses for a fraction of a second, and so on, rather than running the program in a smoothed out continuous way.

This is a vital difference between how a kOS CPU behaves versus how a real world computer behaves. In a real world computer, you would know for certain that time will pass, even if it’s just a few picoseconds, between the execution of one statement and the next.

Telnet clients¶

The telnet server for kOS requires the use of a telnet client program. We recommend the following programs, although you can use others:

For Windows

We recommend Putty, the free terminal emulator for Windows, although any good terminal emulator should do the job, provided it is capable of operating in an “XTERM - compatible” mode.

For Mac

You shouldn’t have to install anything. There should be a telnet client already installed, which you can access by opening up your command terminal, and then running it as a command-line tool. To see how to use it, read below in the section titled “HOWTO: Command-line client”. The built-in Terminal.app for OSX understands the XTERM command sequences that kOS uses and in fact identifies itself as a type of XTERM when used with a telnet client.

For Linux

You shouldn’t have to install anything. There should be a telnet client already installed, and an xterm program already installed in most any Linux distribution. Open an xterm window, and in that window type the telnet command, as described by the section titled “HOWTO: Command-line client“

Using it¶

1. Turn on the telnet server by going into the app control panel and clicking on the green circle next to the word “Telnet”. Alternatively, you can issue the command:

   SET CONFIG:TELNET TO TRUE.
   

   from any terminal window in kOS.

2. The very first time you do this, you will get a warning message, as per SQUAD’s rule number 5 about mods that run network services. After accepting and clicking “yes”, the server will be running on loopback 127.0.0.1 (if you want to make it run on the non-loopback address, you will get a secondary warning message about that too.

3. Launch your telnet client (there is a list of telnet clients that are known to work listed below.

4. When you first log in to the server you should see the “Welcome menu”, which is a screen looking like this:

   Terminal: type = XTERM, size = 80x24
   ________________________________________________________________________________
                 Menu GUI   Other
                 Pick Open Telnets  Vessel Name (CPU tagname)
                 ---- ---- -------  --------------------------------
                  [1]   no    0     Randy Viewer (CX-4181())
                  [2]   no    0     Randy Viewer (CX-4181())
                  [3]   no    0     Randy Viewer (CX-4181())
                  [4]   no    0     Randy Viewer (CX-4181())
                  [5]   no    0     Randy Viewer (CX-4181())
                  [6]   no    0     Randy Viewer (CX-4181())
   --------------------------------------------------------------------------------
   Choose a CPU to attach to by typing a selection number and pressing
   return/enter. Or enter [Q] to quit terminal server.
   
   (After attaching, you can (D)etach and return to this menu by pressing Control-D
   as the first character on a new command line.)
   --------------------------------------------------------------------------------
   >_
   

   Or, if there are no CPU’s within range, it will look like this:

   Terminal: type = XTERM, size = 80x24
   ________________________________________________________________________________
                 Menu GUI   Other
                 Pick Open Telnets  Vessel Name (CPU tagname)
                 ---- ---- -------  --------------------------------
                                         <NONE>
   

   At any moment you can force a redraw of the menu by entering any gibberish non- numeric data and hitting enter.

   This menu should match 1:1 with the list of CPU’s you see on the kOS applauncher control panel.

The welcome menu, shown here in a Mac OSX terminal.

5. Pick a CPU. Pick one of the CPU’s listed by typing its number and hitting enter.
6. Your telnet is now connected to the server and should behave as the terminal for that CPU. You can type commands and do what you like, the same as if you had been directly on its window.
7. See the section labeled Special Keys to see how to use the keyboard from your telnet client.
8. It is possible to have multiple terminals hooked up to the same in-game CPU. They will all behave as clones of each other, each being an equal “first citizen”. (For example a pair of people could execute the “stage.” command by having one of them type “st”, then the other types “age”, followed by the first person typing ”.” and the return key.) All the keyboards and all the screens are slaved together to be equal. You can view the in-game gui terminal while somebody is typing on a telnet temrinal.
9. In order to make the terminals act as clones of each other, the game will attempt to keep them all the same size. If you resize your telnet client window, it should cause the in-game window to change size to match. (If your terminal type is XTERM, then the same thing works in reverse. If it’s VT100 then it doesn’t.)

SET TERMINAL:WIDTH TO 50.

10. At any time you may disconnect your telnet client from the terminal by hitting control-D as the first character of a new line. This will bring you back to the telnet welcome menu again.

Special Keys¶

The following keys have special meaning in the telnet session:

Control-L

Force refresh Pressing Control-L forces the kOS telnet server to redraw your whole screen for you from scratch. This is useful if you encounter strange line noise, interrupted messages, or for just any occasion where you suspect the screen isn’t being drawn correctly. Pressing control-L will ensure your display gets fully re-synced with what’s in the buffer in memory for the terminal.

Control-C

interrupt process This is the same meaning as control-C in the normal GUI terminal - it breaks the program execution. The reason it gets a special mention here is that it also causes a flush of all the pending input you may have typed ahead in the queue. If you’ve been typing blindly ahead, and then hit Control-C, it will erase your typed-ahead keys as it sends the interrupt to the server. This is deliberate, and typical practice for an interrupt character sent over a remote shell setting.

Control-D

detach If you hit control-D as the first character of a new line, it will detach your telnet session from the CPU and return you to the welcome menu.

Cursor Keys

should be mapped If your terminal has identified itself as one of the known types that kOS supports, it should understand your arrow keys as arrow keys. If you see the text “[A” when you type up-arrow, or “[C” when you type right-arrow, this is a clue that kOS didn’t recognize your terminal type properly.

Other Keys

might be mapped Some keys like the Del (to the right), Home, and End keys are often not mapped correctly in some terminal emulator programs. If you have trouble using HOME and END, you can try Control-A and Control-E as alternates for Home and End.

Control-A

home This is an alternate way to press the “home” key, just in case your terminal emulation isn’t sending the officially understood terminal code for it.

Control-E

end This is an alternate way to press the “end” key, just in case your terminal emulation isn’t sending the officially understood terminal code for it.

Control-H

backspace This is an alternate way to press the “backspace” key, just in case your terminal emulation isn’t sending the officially understood terminal code for it.

Control-M

Return This is an alternate way to press the “enter” or “return” key, just in case your terminal emulation isn’t sending the officially understood terminal code for it.

HOWTO: Putty client¶

(These instructions assume you use the default kOS Telnet server settings, of the loopback address 127.0.0.1, and port number 5410. If you’ve changed those settings then alter the numbers you see here accordingly.)

1. Run KSP, and get it into a scene where there exists a vessel with at least one kOS CPU loaded into it.
2. Run Putty.
3. On the first dialog you see, click the Telnet radio-button selection.
4. Type in the number 127.0.0.1 in the large blank above the radio buttons that is labeled “Host Name (or IP address)”.
5. Type in the number 5410 in the smaller blank to the right of it that is labeled “Port”.
6. At the bottom of the screen, select the radio button labeled “Never” under “Close window on exit”.
7. Click the Open button to connect to the server.

(You can also save these settings under a name for later re-use.)

Step 6 is important. Without it, Putty would just make the window disappear any time there’s a problem, making it very hard to diagnose because you can’t see what message the server was sending back to you just before the window went away.

HOWTO: Command-line client¶

Showing the use of telnet in an x-term window.

Showing the use of telnet in a Mac OSX terminal.

(These instructions assume you use the default kOS Telnet server settings, of the loopback address 127.0.0.1, and port number 5410. If you’ve changed those settings then alter the numbers you see here accordingly.)

1. Run KSP, and get it into a scene where there exists a vessel with at least one kOS CPU loaded into it.

2. Open a command shell window that either IS xterm, or emulates xterm. For OSX, the default command shell should work fine. For Linux, you should actually have the xterm program itself installed that you can use.

3. At the shell prompt in that window, enter the command:

   telnet 127.0.0.1 5410
   

HOWTO: Other client¶

1. Set the IP address to 127.0.0.1 using whatever means the program has for it.
2. Set the port number to 5410 using whatever means the program has for it.
3. Set the terminal to XTERM emulation mode if it has it, or VT100 mode as a less good, but still perhaps workable option.
4. Run the terminal.

Security¶

The telnet protocol performs no encryption of its data, and as such any attempt at securing the system using a name/password combination would have been utterly pointless. Rather than provide a false sense of security that’s not really there, we decided to make it obvious that there’s no security by not even implementing a name and password for connecting to the kOS telnet server.

The purpose is to make it clear that if you want to open up your kOS telnet server, you need to be careful about how you do it.

The default settings that kOS ships with restricts your kOS telnet server to only operating on the loopback address (127.0.0.1) so that you won’t accidentally open anything up to the public without thinking about it and making a conscious decision to do so. If you don’t know what that means, it means this: Any server that runs on the magic special address 127.0.0.1, known as “loopback”, is incapable of taking connections from other computers besides itself.

In order to allow your kOS telnet server to take connections from other computers, you will typically need to do one of two things:

Either turn off the CONFIG:LOOPBACK option in your kOS install and then restart your telnet server (turn it off and on again using the button on the control panel), or (much better), set up a remote ssh tunnel that will map from your current machine’s loopback address on the port number of your server to some remote other computer you want to connect from, to a port on it. The ssh tunnel is the preferred method, but describing how to set one up is beyond the scope of this document. You can read more For windows or For UNIX (both Mac and Linux).

Example: Let’s say you have a remote Unix machine you’d like to enable logins from, from there and nowhere else. You can forward from your own machine’s 127.0.0.1, port 5410, to the remote machine’s, oh let’s say 127.0.0.1, port 54100. Then anyone on the remote machine could telnet to ITS 127.0.0.1, port 54100 and end up talking to your machine’s port 5410 on its loopback address.

Port forwarding

If you opt to turn off the loopback-only mode on your kOS telnet server, then you will probably also, if you have a typical home network setup, need to enable port forwarding on your router if you want people from outside your house to connect to it. (Again, think about the implications of doing so before you do it). This is a topic beyond the scope of this document, but help can be found out on the web for it. Search for “port forward home router”. (It is probably also a good idea to include the make & model number of your router device in your search terms, to get a nicely narrowed result that’s exactly what you need.)

Why not ssh?

The original plan for kOS was to include an ssh server instead of a telnet server. However this proved problematic as open source solutions in C# for the server-side of ssh were hard to come by (there’s several for the client side only, and plenty of server-side code that’s not in C#), and implementing the entire server side of the ssh protocol from scratch is a daunting task that would have taken too much time away from other development of kOS. (While implementing from scratch the server side of the older, simpler telnet protocol, while still work, was more doable).

Homemade telnet clients¶

This section is only of interest to hobbyists making Kerbal console hardware rigs and software developers trying to make interface mods that pretend to be kOS terminals. If you are neither of those two, then don’t worry if this section looks like gibberish to you. It can be skipped.

TELNET PROTOCOL

If you wish to make your own homemade telnet client and connect it up to the kOS telnet server, the following is the required subset of the telnet protocol that your telnet client must speak, and the terminal requirements it must fulfill:

1. It must suppress local character echoing, and enter character-at-a-time mode, by implementing both the ECHO negotiation described by RFC857, and the SUPPRESS GO AHEAD negotiation described by RFC858. These are used in the following way: Your client must NOT ECHo (letting the server do it), and your client must suppress go-ahead messages (allowing real-time back-and-forth).
2. It must implement the underlying DO/DONT and WILL/WONT, and SB/SE infrastructure of the main telnet RFC854. It must send break (ctrl-C) as the IP interrupt process command (byte 255 followed by 244). kOS does not use much of the negotiations of the protocol mentioned on RFC854, other than those that are necessary to enable the other ones mentioned here.
3. It must implement the Terminal-Type option described by RFC1091. Furthermore, as of this writing, kOS only knows how to understand two terminal types, “XTERM”, and “VT100”. If your terminal type is identified as anything else, kOS may deny your connection, or at the very least just not work right. Even terminals that are capable of emulating XTERM or VT100 commands won’t work right if they don’t identify themselves as XTERM or VT100. kOS does not know how to guess what emulation mode to enter if it doesn’t recognize your terminal type string.
4. It must implement the NAWS, Negotiate About Terminal Size option, as described by RFC1073. kOS uses this to decide how to size its mental image of your terminal to match your terminal’s real size. Note that this negotiation is one-way. Your client can use it to tell the server about its size, but the server can’t use it to tell your client to change its size. Instead if your client can respond to changing sizes at the behest of the server, it must do so through terminal escape code characters sent back to it on the stream, above the telnet protocol layer itself. (For example, if you identify as XTERM, you will be sent the XTERM escape code pattern ESC [ 8 ; height ; width t, which is the XTERM escape code for setting the terminal size.) This is because the telnet protocol was never written to accommodate the concept of server-initiated resizes.

Making a telnet client from scratch that actually follows protocol may be a complex enough task that the smarter solution is to just use an existing telnet program, if you are trying to create some sort of hardware rig. These days a small cheap mini-hardware implementation of Linux should be doable, and could include the telnet client installed in it for very little storage cost.

TERMINAL EMULATION

As of right now, the terminal emulation of kOS only really supports XTERM or VT100 well, however the infrastructure is in place to support modifications to map to other terminal types. If you want to try a hand at adding the terminal emulation for a currently unsupported terminal, you’d do it by subclassing the kOS.UserIO.TerminalUnicodeMapper class. You can look at kOS.UserIO.TerminalXtermMapper as a sample to see what you need to do.

If you have a project where you want to just work with the terminal codes already supported, then these are the subset you need to support:

ASCII

The following terms should have their normal ASCII meaning:

0x08 (control-H)

backspace key

0x0d (control-M)

Return key. On output it means go to left edge but don’t go down a line. A typical eoln needs to occur using its ASCII standard of both a return character 0x0d AND a linefeed character 0x0a

0x0a (control-J)

On output it means go to go down a line but don’t go to the left edge A typical eoln needs to occur using its ASCII standard of both a return character 0x0d AND a linefeed character 0x0a

Terminal codes: The following terms should have their VT100/XTERM meaning

Left-Arrow

ESC [ D – both on input and on output

Right-Arrow

ESC [ C – both on input and on output

Up-Arrow

ESC [ A – both on input and on output

Down-Arrow

ESC [ B – both on input and on output

Home-key

ESC [ 1 ~ – input only

End-key

ESC [ 4 ~ – input only

Delete-to-the-right-key

ESC [ 3 ~ – input only

PageUp-key

ESC [ 5 ~ – input only

PageDown-key

ESC [ 6 ~ – input only

Move-to-home-of-screen-upper-left

ESC [ H – output only

Move-to-end-of-line

ESC [ F – output only

Teleport-cursor-to-coordinate

ESC [ row ; col H – output only: rows and cols start counting at 1, not 0

Clearscreen

ESC [ 2 J – output only

Scroll-screen-up-one-line-keeping-cursor-where-it-is

ESC [ S – output only

Scroll-screen-down-one-line-keeping-cursor-where-it-is

ESC [ T – output only

Delete-to-the-left-of-cursor-ie-backspace

ESC [ K – output only

Delete-at-the-cursor-toward-the-right

ESC [ 1 K – output only

XTERM codes: The following codes are for the XTERM emulation only

Server-telling-client-to-resize-screen

ESC [ 8 ; newheight ; newwidth t – The height/width are in chars

Server-telling-client-to-change-window-title

ESC ] 2 ; title string BEL – where BEL is the character normally used to mean beep: control-G or 0x07. But in this context it just marks the end of the title and shouldn’t cause a beep. Note this is NOT a typo that it uses a right-square-bracket (“]”) here where all the other codes used a left-square-bracket (“[”). That’s actually how the xterm control sequence for this really looks.

Any value not mentioned in the list above might still get sent, but you should be able to capture and ignore it.

Script Files¶

There is one file per program. You can use the words “file” and “program” interchangeably in your thinking for the most part. Files are stored in volumes and there can be more than one file in a volume provided there’s enough room. Volumes have small storage and there’s no way to span a file across two volumes, so the limit to the size of a volume is also effectively a limit to the size of a program.

File Storage Behind the Scenes¶

In the Archive:

• If a file is stored on the volume called “Archive” (or volume number zero to put it another way), then behind the scenes it’s really stored as an actual file, with the extension .ks, on your computer (As of right now it’s located in Ships/Script but that location is likely to change to somewhere in GameData in a future version.) Each program is a simple text file you can edit with any text editor, and your edits will be seen immediately by KOS the next time it tries running that program from the archive volume.
• Historical note: older versions of kOS (0.14 and earlier) used the directory Plugins/PluginData/Archive for the archive.

In any other volume besides Archive:

• If a file is stored on any volume other than archive, then behind the scenes it’s stored actually inside the saved game’s persistence file in the section for the KOS part on the vessel. What’s a Volume

A Volume is a small unit of disk storage that contains a single hard drive with very limited storage capacity. It can store more than one program on it. To simulate the sense that this game takes place at the dawn of the space race with 1960’s and 1970’s technology, the storage capacity of a volume is very limited.

For example, the CX-4181 Scriptable Control System part defaults to only allowing 1000 bytes of storage.

The byte count of a program is just the count of the characters in the source code text. Writing programs with short cryptic variable names instead of long descriptive ones does save space, although you can also save space by compiling your programs to KSM files where the variable names are only stored once in the file, but that’s another topic for another page.

Each of the computer parts that kOS supports have their own different default storage capacity limits for their local volume. As you get better parts higher up the tech tree, they come with bigger default size limits.

You can get more space by paying extra cost in money and mass¶

If you wish to have more disk space on your local volume, and are willing to pay a little extra cost in money and in mass, you can use the disk space slider in the vehicle assembly building to increase the limit.

Every part comes with 3 different multiplier options:

• 1x default size,
• 2x default size,
• 4x default size

The higher the multiplier the more mass it will cost you, to represent that you’re using old storage technology, so it costs a lot of mass to have more storage.

The disk size is only settable like this in the assembly building. Once you launch a vessel, its volume size is stuck the way it was when you launched it.

Multiple Volumes on One Vessel¶

Each kOS CX-4181 Scriptable Control System part contains ‘’‘one’‘’ such volume inside it.

If you have multiple CX-4181 parts on the same craft, they are assumed to be networked together on the same system, and capable of reading each other’s hard drives. Their disk drives each have a different Volume, and by default they are simply numbered 1,2,3, … unless you rename them with the RENAME command.

For example, if you have two CX-4181’s on the same craft, called 1 and 2, with volumes on them called 1 and 2, respectively, it is possible for CPU 1 to run code stored on volume 2 by just having CPU number 1 issue the command ‘’SWITCH TO 2.’‘

Naming Volumes¶

It’s important to note that if you have multiple volumes on the same vessel, the numbering conventions for the volumes will differ on different CPUs. The same volume which was called ‘2’ when one CPU was looking at it might instead be called ‘1’ when a different CPU is looking at it. Each CPU thinks of its OWN volume as number ‘1’.

Therefore using the RENAME command on the volumes is useful when dealing with multiple CX-4181’s on the same vessel, so they all will refer to the volumes using the same names.

If a kOS processor has a name tag set, then that processor’s volume will have its name initially set to the value of the name tag.

Archive¶

The “archive” is a special volume that behaves much like any other volume but with the following exceptions:

• It is globally the same even across save games.
• The archive represents the large bank of disk storage back at mission control’s mainframe, rather than the storage on an indivdual craft. While “Volume 1” on one vessel might be a different disk than “Volume 1” on another vessel, there is only volume called “archive” in the entire solar system. Also, there’s only one “archive” across all saved universes. If you play a new campaign from scratch, your archive in that new game will still have all the files in it from your previous saved game. This is because behid the scenes it’s stored in the plugin’s directory, not the save game directory.
• It is infinitely large.
• Unlike the other volumes, the archive volume does not have a byte limit. This is because the mainframe back at home base can store a lot more than the special drives sent on the vessels - so much so that it may as well be infinite by comparison.
• Files saved there do not revert when you “revert flight”.
• When you revert a flight, you are going back to a previous saved state of the game, and therefore any disk data on the vessels themselves also reverts to what it was at the time of the saved game. Because the archive is saved outside the normal game save, changes made there are retained even when reverting a flight.
• It’s not always reachable if you are out in space, unless you have antennae.
• Once a vessel is more than 100,000 meters away from mission control, by default it cannot access the files on the archive. Commands such as SWITCH TO , and COPY FROM will fail to work when trying to access the archive volume while out of range. This can be changed by putting antennae on the vessel. With enough antennae it becomes possible to reach the archive drive from farther away. Using this method it is possible to alter the software stored on a vessel after launch.
• Files in Archive are editable with a text editor directly and they will have the .ks extension.
• Files in the Archive are stored on your computer in the subdirectory: Ships/Script. You can pull them up in a text editor of your choice and edit them directly, and the KOS Mod will see those changes in its archive immediately. Files stored in other volumes, on the other hand, are stored inside the vessel’s data in the persistence file of the saved game and are quite a bit bit harder to edit there. Editing the files in the Archive directory is allowed and in fact is an officially accepted way to use the plugin. Editing the section in a persistence file, on the other hand, is a bad idea and probably constitutes a form of cheating similar to any other edit of the persistence file.

Compiling to a KSM File¶

When you run your Kerboscript programs, behind the scenes they get compiled into a form in memory that runs much smoother but at the same time is quite hard for a Kerbal to read and understand. The actual computer hardware built by your friends at Compotronix incorporated actually run the program using these tiny instructions called “opcodes”. In the early days of room-sized computers before we were able to get them down to the compact size of just a meter or so across, all programmers had to use this difficult system, referred to as “machine language”. Ah, those were heady days, but they were hard.

The commands you actually write when you say something like SET X TO 1.0. are really a euphemism for these “machine language” opcodes under the surface.

When you try to “RUN” your script, the first thing that kOS does is transform your script into this ancient and arcane “machine language” form, storing it in its memory, and from then on it runs using that.

This process of transforming your script into Machine Language, or “ML” is called “Compiling”.

The “RUN” command does this silently, without telling you. This is why you may have noticed the universe slightly stutter for a moment when you first run your program. Compiling is hard work for the universe to do.

How to Use KSM Files¶

Let’s say that you have 3 programs your probe needs, called:

• myprog1.ks
• myprog2.ks
• myprog3.ks

And that myprog1 calls myprog2 and myprog3, and you normall would call the progam this way:

SWITCH TO 1.
COPY myprog1 from ARCHIVE.
COPY myprog2 from ARCHIVE.
COPY myprog3 from ARCHIVE.
RUN myprog1(1,2,"hello").

Then you can put just the compiled KSM versions of them on your vessel and run it this way:

SWITCH TO ARCHIVE.

COMPILE myprog1.ks to myprog1.ksm.
COPY myprog1.ksm to 1.

COMPILE myprog2. // If you leave the arguments off, it assumes you are going from .ks to .ksm
COPY myprog2.ksm to 1.

COMPILE myprog3. // If you leave the arguments off, it assumes you are going from .ks to .ksm
COPY myprog2.ksm to 1.

SWITCH TO 1.
RUN myprog1(1,2,"hello").

Default File Naming Conventions¶

When you have both a .ks and a .ksm file, the RUN command allows you to specify which one you meant explicitly, like so:

RUN myprog1.ks.
RUM myprog1.ksm.

But if you just leave the file extension off, and do this:

RUN myprog1.

Then the RUN command will first try to run a file called “myprog1.ksm” and if it cannot find such a file, then it will try to run one called “myprog1.ks”.

In this way, if you decide to take the plunge and attempt the use of KSM files, you shouldn’t have to change the way any of your scripts call each other, provided you just used versions of the filenames without mentioning the file extensions.

Downsides to Using KSM Files¶

1. Be aware that if you use this feature, you do lose the ability to have the line of code printed out for you when the kOS computer finds an error in your program. It will still tell you what line number the error happened on, but it cannot show you the line of code. Just the number.
2. Know that you cannot view the program inside the in-game editor anymore when you do this. A KSM file will not appear right in the editor. It requires a magic tool called a “hex editor” to properly see what’s happening inside the file.
3. The file isn’t always smaller. There’s a threshold at which the KSM file is actually bigger than the source KS file. For large KS files, the KSM file will be smaller, but for short KS files, the KSM file will be bigger, because there’s a small amount of overhead they have to store that is only efficient if the data was large enough.

More Reading and Fiddling with Your Bits¶

So, if you are intrigued by all this and want to see how it all REALLY works under the hood, Computronix has deciced to make internal document MLfile-zx1/a on the basic plan of the ML file system open for public viewing, if you are one of those rare Kerbals that enjoys fiddling with your bits. No, not THOSE kind of bits, the computery kind!

Giving a Part a Name¶

1. Right click on any part. **You can do this in either the editor VAB/SPH, or during flight.** It is more useful to do beforehand when making the craft, but you can do it in the midst of a flight, which is useful for experimenting and testing.
2. Click the “change name tag” button. A small text pop-up will appear with the ability to type a name for the part. Type any value you like. In the example picture here, the value “the big tank” was typed in.
3. From now on this part can be retrieved using either the :PARTSDUBBED or the :PARTSTAGGED methods of the vessel, as described on the Vessel Page

Cloning with Symmetry¶

If you name a part in the editor first, and then remove it from the vessel and place it again with symmetry, all the symmetry copies of the part will get the same nametag cloned to them. This is not an error. It is allowed to give the same nametag to more than one part. If you do this, it just means that the :PARTSTAGGED or :PARTSDUBBED methods will return lists containing more than one part.

If you want each part in a symmetrical group to get a unique nametag, you can change their names one at a time after you’ve placed the parts.

Where is it saved?¶

If you add a nametag to a part in the editor (VAB or SPH), then that nametag will get saved inside the craft file for that vessel design. All new instances of that craft design that you launch will get the same nametag configuration on them.

On the other hand, if you added a nametag to a part after the vessel was launched, during flight or on the launchpad, then that nametag will only be attached to that part on that one instance of the vessel. Other copies of the same design won’t have the name. In this case the name is saved inside the saved game’s persistence file, but not in the editor’s craft design file.

Examples of Using the Name¶

// Only if you expected to get
// exactly 1 such part, no more, no less.
SET myPart TO SHIP:PARTSDUBBED("my nametag here")[0].

// OR

// Only if you expected to get
// exactly 1 such part, no more, no less.
SET myPart TO SHIP:PARTSTAGGED("my nametag here")[0].

// Handling the case of more than
// one part with the same nametag,
// or the case of zero parts with
// the name:
SET allSuchParts TO SHIP:PARTSDUBBED("my nametag here").

// OR

SET allSuchParts TO SHIP:PARTSTAGGED("my nametag here").

// Followed by using the list returned:
FOR onePart IN allSuchParts {
  // do something with onePart here.
}

For more details on how this system works see the Parts and PartModules Section.

Tutorial¶

If you prefer the tutorial approach to learning, the following links will walk you through a specific pair of tasks to introduce you to this system. If you prefer a methodical reference approach, skip the tutorials and read on, then come back to the tutorials afterward.

TODO: PUT LINKS POINTING TO A TUTORIAL WALKING THROUGH WHAT THIS IS TEACHING.

THERE NEEDS TO BE TWO TUTORIALS MINIMUM:

1. A Tuturial made on an ONLY STOCK (other than kOS of course) install, using only STOCK parts to do something interesting.
2. A Tutorial more complex showing that this can be used with mods too, probably the Leg Leveller example from the teaser video, but with the code updated to use the newer part query methods.

Parts¶

Accessing the parts by various naming systems¶

Any time you have a vessel variable, you can use these suffixes to get lists of parts on it by their names using several different naming schemes:

Part Tag: A part’s tag is whatever custom name you have given it using the nametag system described here. This is probably the best naming convention to use because it lets you make up whatever name you like for the part and use it to pick the parts you want to deal with in your script.

Part Title: A part’s title is the name it has inside the GUI interface on the screen that you see as the user.

Part Name: A part’s name is the name it is given behind the scenes in KSP. It never appears in the normal GUI for the user to see, but it is used in places like Part.cfg files, the saved game persistence file, the ModuleManager mod, and so on.

Assuming you’ve done one of these:

SET somevessel to SHIP.
//    Or this:
SET somevessel to VESSEL("some vessel's name").
//    Or this:
SET somevessel to TARGET. // assuming TARGET is a vessel and not a body or docking port.

Then you can do one of these to query based on any of the above schemes:

// --------- :PARTSTAGGED -----------
// Finds all parts that have a nametag (Part:Tag suffix) matching the value given:
SET partlist to somevessel:PARTSTAGGED(nametag_of_part)

// --------- :PARTSTITLED -----------
// Finds all parts that have a title (Part:Title suffix) matching the value given:
SET partlist to somevessel:PARTSTITLED(title_of_part)

// --------- :PARTSNAMED -----------
// Finds all parts that have a name (Part:Name suffix) matching the value given:
SET partlist to somevessel:PARTSNAMED(name_of_part)

// --------- :PARTSDUBBED -----------
// Finds all parts matching the string in any naming scheme, without caring what kind of naming scheme it is
// This is essentially the combination of all the above three searches.
SET partlist to somevessel:PARTSDUBBED(any_of_the_above)

In all cases the checks are performed case-insensitively.

These are different styles of naming parts, all slightly different, and you can use any of them you like to get access to the part or parts you’re interested in.

They all return a List of Parts rather than just one single part. This is because any name could have more than one hit. If you expect to get just one single hit, you can just look at the zero-th value of the list, like so:

SET onePart TO somevessel:PARTSDUBBED("my favorite engine")[0].

If the name does not exist, you can tell by seeing if the list returned has a length of zero:

IF somevessel:PARTSDUBBED("my favorite engine"):LENGTH = 0 {
  PRINT "There is no part named 'my favorite engine'.".
}.

Examples:

// Change the altitude at which all the drouge chutes will deploy:
FOR somechute IN somevessel:PARTSNAMED("parachuteDrogue") {
  somechute:GETMODULE("ModuleParachute"):SETFIELD("DEPLOYALTITUDE", 1500).
}.

SET ves TO SHIP. // or Target or Vessel("ship name").
SET PLIST TO ves:PARTSNAMED("someNameHere").

SET ves TO SHIP. // or Target or Vessel("ship name").
SET PLIST TO ves:PARTSINGROUP(AG1).

PartModules and the right-click menu:¶

Each Part, in turn has a list of what are called PartModules on it. A PartModule is a collection of variables and executable program hooks that gives the part some of its behaviors and properties. Without a PartModule, a part is really nothing more than a passive bit of structure that has nothing more than a shape, a look, and a strength to it. Some of the parts in the “structure” tab of the parts bin, like pure I-beams and girders, are like this - they have no PartModules on them. But all of the interesting parts you might want to do something with will have a PartModule on them. Through PartModules, **kOS will now allow you to manipulate or query anything that any KSP programmer, stock or mod, has added to the rightclick menu**, or action group actions, for a part.

What a PartModule means to a kOS script¶

There are 3 ways that a kOS script may interface with a PartModule.

TODO - TAKE SOME SCREENSHOTS TO PUT ALONGSIDE THIS TEXT, SHOWING EXAMPLES OF THESE THINGS IN THE USER INTERFACE. WE NEED A SCREENSHOT THAT SHOWS BOTH A KSPFIELD AND A KSPEVENT IN A PART’S RMB CONTEXT MENU, A SCREENSHOT THAT SHOWS FIELDS COMING FROM MULTIPLE PARTMODULES, AND A SCREENSHOT SHOWING THE KSPACTIONS IN THE VAB ACTION EDITOR.

Exploring what’s there to find Field/Event/Action Names:¶

Okay, so you understand all that, but you’re still thinking “but how do I KNOW what the names of part modules are, or what the names of the fields on them are? I didn’t write all that C# source code for all the modules.”

There are some additional suffixes that are designed to help you explore what’s available so you can learn the answers to these questions. Also, some of the questions can be answered by other means:

// Example snippet from a Part.cfg file:
MODULE
{
    name = ModuleCommand

FOR P IN SHIP:PARTS {
  LOG ("MODULES FOR PART NAMED " + P:NAME) TO MODLIST.
  LOG P:MODULES TO MODLIST.
}.

SET MOD TO P:GETMODULE("some name here").
LOG ("These are all the things that I can currently USE GETFIELD AND SETFIELD ON IN " + MOD:NAME + ":") TO NAMELIST.
LOG MOD:ALLFIELDS TO NAMELIST.
LOG ("These are all the things that I can currently USE DOEVENT ON IN " +  MOD:NAME + ":") TO NAMELIST.
LOG MOD:ALLEVENTS TO NAMELIST.
LOG ("These are all the things that I can currently USE DOACTION ON IN " +  MOD:NAME + ":") TO NAMELIST.
LOG MOD:ALLACTIONS TO NAMELIST.

SomeModule:DOEVENT("Activate").

The rules being enforced¶

These are rules inherited from the stock KSP game that kOS is simply adhering to:

• If your tracking center is not upgraded far enough, then you cannot see future orbit patches.
• If your mission control center AND tracking center are not upgraded enough, then you cannot add manuever nodes.

The following are rules invented by kOS that are thematically very similar to stock KSP, intended to be as close to the meaning of the stock game’s rules as possible:

• In order to be allowed to execute the PartModule :DOACTION method, either your VAB or your SPH must be upgraded to the point where it will allow access to custom action groups. This is because otherwise the :DOACTION method would be a backdoor “cheat” past the restricted access to the action group feaures of various PartModules that the game is meant to have.
• In order to be allowed to add a nametag to parts inside the editor so they get saved to the craft file, you must have upgraded your current editor building (VAB or SPH, depending) to the point where it allows at least stock action groups. This is because name tags are a sort of semi-advanced feature.

You can see some of these settings by reading the values of the Career() global object, for example:

::

print Career():PATCHLIMIT. print Career():CANDOACTIONS.

Structure¶

structure Career¶

Members¶

Suffix	Type	Get	Set
CANTRACKOBJECTS	boolean	yes	no
PATCHLIMIT	number	yes	no
CANMAKENODES	boolean	yes	no
CANDOACTIONS	boolean	yes	no

Career:CANTRACKOBJECTS¶

Type:	boolean
Access:	Get

If your tracking center allows the tracking of unnamed objects (asteroids, mainly) then this will return true.

Career:PATCHLIMIT¶

Type:	number
Access:	Get

If your tracking center allows some patched conics predictions, then this number will be greater than zero. The number represents how many patches beyond the current one that you are allowed to see. It influences attempts to call SHIP:PATCHES and SHIP:OBT:NEXTPATCH.

Career:CANMAKENODES¶

Type:	boolean
Access:	Get

If your tracking center and mission control buildings are both upgraded enough, then the game allows you to make manuever nodes (which the game calls “flight planning”). This will return true if you can make maneuver nodes.

Career:CANDOACTIONS¶

Type:	boolean
Access:	Get

If your VAB or SPH are upgraded enough to allow custom action groups, then you will also be allowed to execute the :DOACTION method of PartModules. Otherwise you can’t. This will return a boolean letting you know if the condition has been met.

Case Insensitivity¶

Everything in KerboScript is case-insensitive, including your own variable names and filenames. The only exception is when you perform a string comparison, ("Hello"="HELLO" will return false.)

Most of the examples here will show the syntax in all-uppercase to help make it stand out from the explanatory text.

Expressions¶

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 four basic types:

SET X TO 4 + 2.5.
PRINT X.             // Outputs 6.5

PRINT "Hello World!".

PRINT "4 plus 3 is: " + (4+3).

PRINT "The Mun's periapsis altitude is: " + MUN:PERIAPSIS.
PRINT "The ship's surface velocity is: " + SHIP:VELOCITY:SURFACE.

SET VEC TO V(10,10,10).  // A vector with x,y,z components
                         // all set to 10.
SET VEC:X to VEC:X * 4.  // multiply just the X part of VEC by 4.
PRINT VEC.               // Results in V(40,10,10).

SET PLIST TO SHIP:PARTSDUBBED("my engines"). // calling a suffix
                                             // method with one
                                             // argument that
                                             // returns a list.
PLIST:REMOVE(0). // calling a suffix method with one argument that
                 // doesn't return anything.
PRINT PLIST:SUBLIST(0,4). // calling a suffix method with 2
                          // arguments that returns a list.

Short-circuiting booleans¶

Further reading: https://en.wikipedia.org/wiki/Short-circuit_evaluation

When performing any boolean operation involving the use of the AND or the OR operator, kerboscript will short-circuit the boolean check. What this means is that if it gets to a point in the expression where it already knows the result is a forgone conclusion, it doesn’t bother calculating the rest of the expression and just quits there.

Example:

set x to true.
if x or y+2 > 10 {
    print "yes".
} else {
    print "no".
}.

In this case, the fact that x is true means that when evaluating the boolean expression x or y+2 > 10 it never even bothers trying to add y and 2 to find out if it’s greater than 10. It already knew as soon as it got to the x or whatever that given that x is true, the whatever doesn’t matter one bit. Once one side of an OR is true, the other side can either be true or false and it won’t change the fact that the whole expression will be true anyway.

A similar short circuiting happens with AND. Once the left side of the AND operator is false, then the entire AND expression is guaranteed to be false regardless of what’s on the right side, so kerboscript doesn’t bother calculating the righthand side once the lefthand side is false.

Read the link above for implications of why this matters in programming.

Late Typing¶

Kerboscript is a language in which there is only one type of variable and it just generically holds any sort of object of any kind. If you attempt to assign, for example, a string into a variable that is currently holding an integer, this does not generate an error. It simply causes the variable to change its type and no longer be an integer, becoming a string now.

In other words, the type of a variable changes dynamically at runtime depending on what you assign into it.

Lazy Globals (variable declarations optional)¶

Kerboscript is a language in which variables need not be declared ahead of time. If you simply set a variable to a value, that just “magically” makes the variable exist if it didn’t already. When you do this, the variable will necessarily be global in scope. kerboscript refers to these variables created implicitly this way as “lazy globals”. It’s a system designed to make kerboscript easy to use for people new to programming.

But if you are an experienced programmer you might not like this behavior, and there are good arguments for why you might want to disable it. If you wish to do so, a syntax exists to do so called :ref:NOLAZYGLOBAL.

User Functions¶

Kerboscript supports user functions which you can write yourself and call from your own scripts. These are not structure methods (which as of this writing are a feature which only works for the built-in kOS types, and are not yet supported by the kerboscript language for user functions you write yourself).

Example:

DECLARE FUNCTION DEGREES_TO_RADIANS {
  DECLARE PARAMETER DEG.

  RETURN CONSTANT():PI * DEG/180.
}.

SET ALPHA TO 45.
PRINT ALPHA + " degrees is " + DEGREES_TO_RADIANS(ALPHA) + " radians.".

For a more detailed description of how to declare your own user functions, see the Language Syntax Constructs, User Functions section.

Structures¶

Structures, introduced above, are variable types that contain more than one piece of information. All structures contain sub-values or methods that can be accessed with a colon (:) operator. Multiple structures can be chained together with more than one colon (:) operator:

SET myCraft TO SHIP.
SET myMass TO myCraft:MASS.
SET myVel TO myCraft:VELOCITY:ORBIT.

These terms are referred to as “suffixes”. For example Velocity is a suffix of Vessel. It is possible to set some suffixes as well. The second line in the following example sets the ETA of a NODE 500 seconds into the future:

SET n TO Node( TIME:SECONDS + 60, 0, 10, 10).
SET n:ETA to 500.

The full list of available suffixes for each type can be found here.

General Rules¶

Whitespace consisting of consecutive spaces, tabs, and line breaks are all considered identical to each other. Because of this, indentation is up to you. You may indent however you like.

The following are reserved command keywords and special operator symbols:

Arithmetic Operators:

+  -  *  /  ^  e  (  )

Logic Operators:

not  and  or  true  false  <>  >=  <=  =  >  <

Instructions and keywords:

add all at batch break clearscreen compile copy declare delete
deploy do do edit else file for from from function global if
in list local lock log off on once parameter preserve print reboot
remove rename run set shutdown stage step switch then to toggle
unlock unset until volume wait when

Other symbols:

{  }  [  ]  ,  :  //

Comments consist of everything from a “//” symbol to the end of the line:

set x to 1. // this is a comment.

Identifiers: Identifiers consist of: a string of (letter, digit, or underscore). The first character must be a letter. The rest may be letters, digits or underscores. Identifiers are case-insensitive. The following are identical identifiers:

My_Variable  my_varible  MY_VARAIBLE

case-insensitivity

The same case-insensitivity applies throughout the entire language, with all keywords except when comparing literal strings. The values inside the strings are still case-sensitive, for example, the following will print “unequal”:

if "hello" = "HELLO" {
    print "equal".
} else {
    print "unequal".
}

Suffixes

Some variable types are structures that contain sub-portions. The separator between the main variable and the item inside it is a colon character (:). When this symbol is used, the part on the right-hand side of the colon is called the “suffix”:

list parts in mylist.
print mylist:length. // length is a suffix of mylist

Suffixes can be chained together, as in this example:

print ship:velocity:orbit:x.

In the above example you’d say “velocity is a suffix of ship”, and “orbit is a suffix of ship:velocity”, and “x is a suffix of ship:velocity:orbit”.

Braces (statement blocks)¶

Anywhere you feel like, you may insert braces around a list of statements to get the language to treat them all as a single statement block.

For example: the IF statement expects one statement as its body, like so:

if x = 1
  print "it's 1".

But you can put multiple statements there as its body by surrounding them with braces, like so:

if x = 1 { print "it's 1".  print "yippieee.".  }

(Although this is usually preferred to be indented as follows):

if x = 1 {
  print "it's 1".
  print "yippieee.".
}

or:

if x = 1
{
  print "it's 1".
  print "yippieee.".
}

Kerboscript does not require proper indentation of the brace sections, but it is a good idea to make things clear.

You are allowed to just insert braces anywhere you feel like even when the language does not require it, as shown below:

declare x to 3.
print "x here is " + x.
{
  declare x to 5.
  print "x here is " + x.
  {
    declare x to 7.
    print "x here is " + x.
  }
}

The usual reason for doing this is to create a local scope section for yourself. In the above example, there are actually 3 different variables called ‘x’ - each with a different scope.

Functions (built-in)¶

There exist a number of built-in functions you can call using their names. When you do so, you can do it like so:

functionName( *arguments with commas between them* ).

For example, the ROUND function takes 2 arguments:

print ROUND(1230.12312, 2).

The SIN function takes 1 argument:

print SIN(45).

When a function requires zero arguments, it is legal to call it using the parentheses or not using them. You can pick either way:

// These both work:
CLEARSCREEN.
CLEARSCREEN().

Suffixes as Functions (Methods)¶

Some suffixes are actually functions you can call. When that is the case, these suffixes are called “method suffixes”. Here are some examples:

set x to ship:partsnamed("rtg").
print x:length().
x:remove(0).
x:clear().

User Functions¶

Help for the new user - What is a Function?

In programming terminology, there is a commonly used feature of many programming languages that works as follows:

• 1. Create a chunk of program instructions that you don’t intend to execute YET.
• 2. Later, when executing other parts of the program, do the following:

  • 2.A. Remember the current location in the program.
  • 2.B. Jump to the previously created chunk of code from (1) above.
  • 2.C. Run the instructions there.
  • 2.D. Return to where you remembered from (2.A) and continue from there.

This feature goes by many different names, with slightly different precise meanings: Subroutines, Procedures, Functions, etc. For the purposes of kerboscript, we will refer to all uses of this feature with the term Function, whether it technically fits the mathematical definition of a “function” or not.

In kerboscript, you can make your own user functions using the DECLARE FUNCTION command, which is structured as follows:

declare function identifier { statements } optional dot (.)

Functions are a long enough topic as to require a separate documentation page, here.

Built-In Special Variable Names¶

Some variable names have special meaning and will not work as identifiers. Understanding this list is crucial to using kOS effectively, as these special variables are the usual way to query flight state information. The full list of reserved variable names is on its own page.

What does not exist (yet?)¶

Concepts that many other languages have, that are missing from KerboScript, are listed below. Many of these are things that could be supported some day, but at the moment with the limited amount of developer time available they haven’t become essential enough to spend the time on supporting them.

user-made structures or classes

Several of the built-in variables of kOS are essentially “classes” with methods and fields, however there’s currently no way for user code to create its own classes or structures. Supporting this would open up a large can of worms, as it would then make the kOS system more complex.

BREAK¶

Breaks out of a loop:

SET X TO 1.
UNTIL 0 {
    SET X TO X + 1.
    IF X > 10 { BREAK. } // Exits the loop when
                         // X is greater than 10
}

IF / ELSE¶

Checks if the expression supplied returns true. If it does, IF executes the following command block. Can also have an optional ELSE to execute when the IF condition is not true. ELSE can have another IF after it, to make a chain of IF/ELSE conditions:

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-ELSE structure:
IF X > 10 { PRINT "X is large".  } ELSE { PRINT "X is small".  }

// An if-else ladder:
IF X = 0 {
    PRINT "zero".
} ELSE IF X < 0 {
    PRINT "negative".
} ELSE {
    PRINT "positive".
}

// both of these lines are fine
IF TRUE { PRINT "Hello". }
IF TRUE { PRINT "Hello". }.

// works:
IF X > 10 { PRINT "Large". }  ELSE { PRINT "Small". }.

// syntax error - ELSE without IF.
IF X > 10 { PRINT "Large". }. ELSE { PRINT "Small". }.

LOCK¶

Locks an identifier to an expression. Each time the identifier is used in an expression, its value will be re-calculated on the fly:

SET X TO 1.
LOCK Y TO X + 2.
PRINT Y.         // Outputs 3
SET X TO 4.
PRINT Y.         // Outputs 6

LOCK follows the same scoping rules as the SET command. If the variable name used already exists in local scope, then the lock command creates a lock function that only lasts as long as the current scope and then becomes unreachable after that. If the variable name used does not exist in local scope, then LOCK will create it as a global variable, unless @NOLAZYGLOBAL is set to off, in which case it will be an error.

Note that a LOCK expression is extremely similar to a user function. Every time you read the value of the “variable”, it executes the expression again.

UNLOCK¶

Releases a lock on a variable. See LOCK:

UNLOCK X.    // Releases a lock on variable X
UNLOCK ALL.  // Releases ALL locks

UNTIL loop¶

Performs a loop until a certain condition is met:

SET X to 1.
UNTIL X > 10 {      // Prints the numbers 1-10
    PRINT X.
    SET X to X + 1.
}

Note that if you are creating a loop in which you are watching a physical value that you expect to change each iteration, it’s vital that you insert a small WAIT at the bottom of the loop like so:

SET PREV_TIME to TIME:SECONDS.
SET PREV_VEL to SHIP:VELOCITY.
SET ACCEL to V(9999,9999,9999).
PRINT "Waiting for accellerations to stop.".
UNTIL ACCEL:MAG < 0.5 {
    SET ACCEL TO (SHIP:VELOCITY - PREV_VEL) / (TIME:SECONDS - PREV_TIME).
    SET PREV_TIME to TIME:SECONDS.
    SET PREV_VEL to SHIP:VELOCITY.

    WAIT 0.001.  // This line is Vitally Important.
}

The full explanation why is in the CPU hardware description page.