lib_util

LIB_UTIL Utilities Library

The lib_utillibrary contains functions that can be useful in a variety of situations. This page lists and explains they.

To use any of those functions in your own scripts, add the line RunOncePath("lib_util"). in the begin of your own file.

utilFaceBurn

Parameters:

Name	Type	Default Value	Description
DIRTOSTEER	Direction	-	The desired direction

Some crafts, specially shuttles and space planes, may have engines thrust vector offset from the craft longitudinal axis. This will lead to some inaccuracies when burning a maneuver node pointing the craft nose to it.

The function utilFaceBurn tries to compensate for that, pointing the craft in a way the true acceleration vector matches the desired direction, not the ship nose.

How it works

The function uses data from Double-C Seismic Accelerometer and GRAVMAX Negative Gravioli Detector to compute the real acceleration of the craft and make the corrections as needed.

The function will not compute any corrections for crafts without the required sensors installed.

This function will save a file called oss.json in the same directory it ran. That file contains all persistent data the function computes. It's safe to delete the file, the only effect is a reduced precision in next time the function is used, for few seconds, until it computes new data.

How to use this function in your own scripts

Make sure to include the command run once lib_util.ks before trying to use it. Then change any LOCK STEERING statement to use the function, example:

LOCK STEERING TO utilFaceBurn(PROGRADE).

utilRCSCancelVelocity

Parameters:

Name	Type	Default Value	Description
CancelVec	Delegate	-	The delegate of a function or lock that returns a vector
residualSpeed	Scalar	0.01	Maximum admissible residual speed.
MaximumTime	Scalar	15	Maximum Time to achieve results.

This function intends to use the ship's RCS system to zero the magnitude of a vector, usually a maneuver node vector or a relative speed vector.

To be able to do that, the function must be able to keep track of such vector while it's running. Usually passing a vector as a parameter to a function, for example:

function myFun {
  parameter SomeVector.
  //do something...
}

lock myVec to someNode:deltaV.
myFun(myVec).

Makes a copy of myVec with the value it had the moment the function was called. So, every time the function checks the value of SomeVector parameter, it will be the same, regardless what happens.

To solve that, usually, the value should be passed by reference to the function. That is not an option in KerboScript.

But we can exploit how the lock keyword works under the hood. Every time we lock a variable to something, for example:

lock myVal to SHIP:ALTITUDE * 2. Under the hood KerboScript compiler do something like this:

function myVal {
    return SHIP:ALTITUDE * 2.
}

This means we can handle locked variables as functions (because they are indeed functions!) and, for example, use parenthesis, like myVal() to access that locked variable from within other script file, or use at sign like myVal@ to get a delegate to that function.

This means that if we pass myVal@ as a parameter to a function, it will be able to use that delegate (also called handle or pointer in other languages) to access the updated return value of myVal.

So, in order to properly use utilRCSCancelVelocity we first must lock some variable to the desired vector we want utilRCSCancelVelocity to Cancel:

lock ndDeltaV to -nodeNd:deltav.

Then we can call utilRCSCancelVelocity with a delegate to that variable:

utilRCSCancelVelocity(ndDeltaV@,0.1,15).

The other two parameters are optional and are respectively the maximum amount of velocity is tolerable (note that 0 is, in pratice, impossible. There will be ever some very small error) and the maximum time the script should keep trying to zero that speed. The default values are respectively 0.1m/s and 15s.

utilIsShipFacing

Parameters:

Name	Type	Default Value	Description
FaceVec	Vector	-	The vector you want to know if ship is facing to.
maxDeviationDegrees	Scalar	8	Maximum angle from ship's facing and FaceVec
maxAngularVelocity	Scalar	0.01	Maximum ship's angular velocity.

Evaluates if the ship is facing to a vector. It returns true if:

• Ship is facing the FaceVec whiting a tolerance of maxDeviationDegrees and
• Ship have an Angular velocity less than maxAngularVelocity.

utilLongitudeTo360

Parameters:

Name	Type	Default Value	Description
lng	Scalar	-	The longitude you want to convert.

Converts longitudes from -180 to +180 into a 0-360 degrees.

Imagine you start from Greenwich to East, and instead of stop a 180º, keep until reach Greenwich again at 360º. i.e.:

• 10 ==> 10
• 170 ==> 170
• 180 ==> 180
• -10 ==> 350
• -170 ==> 190
• -180 ==> 180

utilReduceTo360

Parameters:

Name	Type	Default Value	Description
ang	Scalar	-	The angle you want to convert.

Converts angles that are more than 360 to 0-360. i.e:

• 720 ==> 0
• 730 ==> 10
• 400 ==> 40

utilCompassHeading

Parameters:

• None.

Returns the same HDG number that Kerbal shows in bottom of Navball.