Raw Control

If you wish to have your kOS script manipulate a vessel’s flight controls directly in a raw way, rather than relying on kOS to handle the flying for you, then this is the type of structure you will need to use to do it. This is offered as an alternative to using the combination of LOCK STEERING and LOCK THROTTLE commands. To obtain the CONTROL variable for a vessel, use its :CONTROL suffix:

SET controlStick to SHIP:CONTROL.
SET controlStick:PITCH to 0.2.

Unlike with so-called “Cooked” steering, “raw” steering uses the SET command, not the LOCK command. Using LOCK with these controls won’t work. When controlling the ship in a raw way, you must decide how to move the controls in detail. Here is another example:

SET SHIP:CONTROL:YAW to 0.2.

This will start pushing the ship to rotate a bit faster to the right, like pushing the D key gently. All the following values are set between \(-1\) and \(+1\). Zero means the control is neutral. You can set to values smaller in magnitude than \(-1\) and \(+1\) for gentler control, (but be aware of the 5% null zone mentioned below):

print "Gently pushing forward for 3 seconds.".
SET SHIP:CONTROL:FORE TO 0.2.
SET now to time:seconds.
WAIT until time:seconds > now + 3.
SET SHIP:CONTROL:FORE to 0.0.

print "Gently Pushing leftward for 3 seconds.".
SET SHIP:CONTROL:STARBOARD TO -0.2.
SET now to time:seconds.
WAIT until time:seconds > now + 3.
SET SHIP:CONTROL:STARBOARD to 0.0.

print "Starting an upward rotation.".
SET SHIP:CONTROL:PITCH TO 0.2.
SET now to time:seconds.
WAIT until time:seconds > now + 0.5.
SET SHIP:CONTROL:PITCH to 0.0.

print "Giving control back to the player now.".
SET SHIP:CONTROL:NEUTRALIZE to True.

One can use SHIP:CONTROL:ROTATION and SHIP:CONTROL:TRANSLATION to see the ship’s current situation.

5% null zone

Warning

The stock raw controls enforce a null zone that kOS can’t seem to override (We’ve tried). Be aware that if you set a translation raw control to a value between -0.05 and +0.05, the stock game seems to ignore it and treat it as zero. (While this may seem to be related to the null zones on the game’s controls setttings page, which also default ot 5%, in reality this seems to happen regardless of what you change those settings to).

Raw Flight Controls Reference

These “Raw” controls allow you the direct control of flight parameters while the current program is running.

Note

The MAINTHROTTLE requires active engines and, of course, sufficient and appropriate fuel. The rotational controls YAW, PITCH and ROW require one of the following: active reaction wheels with sufficient energy, RCS to be ON with properly placed thrusters and appropriate fuel, or control surfaces with an atmosphere in which to operate. The translational controls FORE, STARBOARD and TOP only work with RCS, and require RCS to be ON with properly placed thrusters and appropriate fuel.

Suffix Type, Range Equivalent Key
MAINTHROTTLE scalar [0,1] LEFT-CTRL, LEFT-SHIFT
YAW scalar [-1,1] D, A
PITCH scalar [-1,1] W, S
ROLL scalar [-1,1] Q, E
ROTATION Vector (YAW,PITCH,ROLL)
YAWTRIM scalar [-1,1] ALT+D, ALT+A
PITCHTRIM scalar [-1,1] ALT+W, ALT+S
ROLLTRIM scalar [-1,1] ALT+Q, ALT+E
FORE scalar [-1,1] N, H
STARBOARD scalar [-1,1] L, J
TOP scalar [-1,1] I, K
TRANSLATION Vector (STARBOARD,TOP,FORE)
WHEELSTEER scalar [-1,1] A, D
WHEELTHROTTLE scalar [-1,1] W, S
WHEELSTEERTRIM scalar [-1,1] ALT+A, ALT+D
WHEELTHROTTLETRIM scalar [-1,1] ALT+W, ALT+S
NEUTRAL Boolean Is kOS Controlling?
NEUTRALIZE Boolean Releases Control
SHIP:CONTROL:MAINTHROTTLE

Set between 0 and 1 much like the cooked flying LOCK THROTTLE command.

SHIP:CONTROL:YAW

This is the rotation about the “up” vector as the pilot faces forward. Essentially left \((-1)\) or right \((+1)\).

SHIP:CONTROL:PITCH

Rotation about the starboard vector up \((+1)\) or down \((-1)\).

SHIP:CONTROL:ROLL

Rotation about the longitudinal axis of the ship left-wing-down \((-1)\) or left-wing-up \((+1)\).

SHIP:CONTROL:ROTATION

This is a Vector object containing (YAW, PITCH, ROLL) in that order.

SHIP:CONTROL:YAWTRIM

Controls the YAW of the rotational trim.

SHIP:CONTROL:PITCHTRIM

Controls the PITCH of the rotational trim.

SHIP:CONTROL:ROLLTRIM

Controls the ROLL of the rotational trim.

SHIP:CONTROL:FORE

Controls the translation of the ship forward \((+1)\) or backward \((-1)\). Note that this control has a game-enforced 5% null zone that kOS doesn’t seem to be able to change.

SHIP:CONTROL:STARBOARD

Controls the translation of the ship to the right \((+1)\) or left \((-1)\) from the pilot’s perspective. Note that this control has a game-enforced 5% null zone that kOS doesn’t seem to be able to change.

SHIP:CONTROL:TOP

Controls the translation of the ship up \((+1)\) or down \((-1)\) from the pilot’s perspective. Note that this control has a game-enforced 5% null zone that kOS doesn’t seem to be able to change.

SHIP:CONTROL:TRANSLATION

Controls the translation as a Vector (STARBOARD, TOP, FORE). Note that each axis of this this control vector has a game-enforced 5% null zone that kOS doesn’t seem to be able to change.

SHIP:CONTROL:WHEELSTEER

Turns the wheels left \((-1)\) or right \((+1)\).

SHIP:CONTROL:WHEELTHROTTLE

Controls the wheels to move the ship forward \((+1)\) or backward \((-1)\) while on the ground.

SHIP:CONTROL:WHEELSTEERTRIM

Controls the trim of the wheel steering.

SHIP:CONTROL:WHEELTHROTTLETRIM

Controls the trim of the wheel throttle.

SHIP:CONTROL:NEUTRAL

Returns true or false depending if kOS has any set controls. This is not settable.

SHIP:CONTROL:NEUTRALIZE

This causes manual control to let go. When set to true, kOS lets go of the controls and allows the player to manually control them again. This is not gettable.

Unlocking controls

Setting any one of SHIP:CONTROL values will prevent player from manipulating that specific control manually. Other controls will not be locked. To free any single control, set it back to zero. To give all controls back to the player you must execute:

SET SHIP:CONTROL:NEUTRALIZE to TRUE.

Advantages/Disadvantages

The control over RCS translation requires the use of Raw control. Also, with raw control you can choose how gentle to be with the controls and it can be possible to control wobbly craft better with raw control than with cooked control.