Three kinds of rotation. Edit
R(): Euler Angles Edit
The Short Version: If the phrase "Euler Angle" is new to you, then just don't use R() rotations at all. Skip ahead to Q() or V() or HEADING BY.
The Long Version: When you picture a rotation, you probably picture that the entire coordinate space, including all three axes (XYZ) rotate as a fixed unit together. The type of rotation used in KOS by the R() tuples does NOT do this. They are a rotation called a Euler Angle, in which each "rotation" causes an axis to twist at the origin such that it is no longer orthogonal to the other two axes, and this causes the coordinate space to become skewed into a 'diagonal' shape for the next rotation. So when you rotate around two axes, for example, R(40,30,0), you end up with a rotation completely unlike what you expected. The quick and dirty advice is this: Do Not Use The R() Style Of Rotation Unless You Are Familiar With Euler Angles. Look them up on Wikipedia.
To illustrate the difference, if you start from a heading of due north on a compass heading of 0, pointed at the horizon with wings level, and then pitch up 30 degrees, and then roll right 90 degrees, most people will think of this as meaning that you are now still pointed north on a compass heading of 0, but now 30 degrees up from the horizon and banked all the way over in knife-edge flight. This is NOT what happens in Kerboscript if you do this. In Kerboscript you'd end up on the horizon, not pitched up anymore, at a compass heading 30 degrees off from north. This is because the roll to the right was still rolling around the axis the craft was originally oriented on, not the new one it had after pitching up 30 degrees.
Q(): Quaternions Edit
Quaternions are simply 4-tuples in which the first 3 values define a vector in 3D space from the origin to the the vector tip, and the 4th value defines an angle (in degrees in KOS) to rotate around that vector.
So, to rotate around the X axis, 45 degrees, you'd make a Quaternion like this:
To rotate around the Y axis, -20 degreees, you'd make a Quaternion like this:
Q(0,1,0, 0-20 ).
To rotate around the 45 degree line between X and Z, by an amount of 60 degrees, you'd do this:
V(): Vectors Edit
To set your direction by a Vector, you still have to start from a rotate operator (R(..) or Q(...) or UP or NORTH) and then multiply that by a vector. This makes the craft point toward the vector assuming the vector is expressed in the coordinate system in which that rotate operator defines the orientation of the coordinate system. Using a no-op rotation operator of R(0,0,0) means you're expressing the vector in KSP's native underlying XYZ coordaintes.
Here's an example: You want to point the craft along a velocity that goes 10 meters north for every 3 meters east for every 20 meters up:
set northWard to 10. set eastWard to 3. set upWard to 20. lock steering to up * V( 0 - eastWard, northWard, upWard ).
The reason for inverting the eastward direction is that the game natively uses left handed coordinates while east,north,up is a right-handed system.
Vectors in XYZ versus vectors in East,North,Up (ENU) Edit
Note that the vectors returned by KOS such as velocity, and velocity:surface are usually NOT expressed in east, north, up as shown above. They are usually expressed in the native XYZ coordinate system of KSP, which can be used directly like follows:
lock steering to R(0,0,0) * V(x,y,z).
// Set to surface prograde: lock steering to R(0,0,0) * velocity:surface.
// Set to surface retrograde: set vs to velocity:surface. lock steering to R(0,0,0) * V( 0-vs;x, 0-vs:y, 0-vs:z ).
In general, to use a vector expressed in the game's native XYZ system to steer by, you must multiply it by the non-rotation rotation operator R(0,0,0).
To use a vector expressed in the east,north,up frame of reference, you have to multiply it by the UP rotation operator, and invert the direction of the east component, as shown in the above example:
lock steering to up * V( 0 - eastWard, northWard, upWard ).
HEADING c BY pitch Edit
Starting in version 0.61, the following now also works:
set c to 310. // compass heading, i.e. 0=north,90=east,180=south,270=west. set p to 20. // pitch, i.e. -90=down,0=horizon,90=up. lock steering to heading c by p.
As an alternative to HEADING c BY pitch you can also use this command:
set c to 310. // compass heading, i.e. 0=north,90=east,180=south,270=west. set p to 20. // pitch, i.e. -90=down,0=horizon,90=up. lock steering to heading(c,p).