Cabal Common Library Doc Functions
Contents
- 1 Overview
- 2 Properties
- 3 API Methods
- 3.1 baseChange()
- 3.2 clamp()
- 3.3 getType()
- 3.4 msbPos()
- 3.5 nBitsUsed()
- 3.6 num2Prec()
- 3.7 pseudoRand()
- 3.8 rand()
- 3.9 randSpan()
- 3.10 strAddAlignedText()
- 3.11 strAddEdgeText()
- 3.12 strAddIndentedText()
- 3.13 strAdd2Columns()
- 3.14 strAdd3Columns()
- 3.15 strCompareVersion()
- 3.16 strDateFromMinutes()
- 3.17 strDecrypt()
- 3.18 strEncrypt()
- 3.19 strGetCRC()
- 3.20 strLZ()
- 3.21 strLZZ()
- 3.22 strNLZ()
- 3.23 strRandom()
- 3.24 strRandomInt()
- 3.25 strScreenSubString()
- 3.26 strScreenString()
- 3.27 strSplitToPhrases()
- 3.28 strToWidth()
- 3.29 strTrim()
- 3.30 arrDiff()
- 3.31 arrFlat()
- 3.32 arrRemoveByValue()
- 3.33 arrShuffle()
- 3.34 arrSortByProperty()
- 3.35 arrUnique()
- 3.36 objClone()
- 3.37 objFindKeyValue()
- 3.38 mapCoordsDirection()
- 3.39 oxpVersionTest()
- 3.40 oxpVersionTest2Array()
- 3.41 entModelView()
- 3.42 entFaceEntity()
- 3.43 entScreenCornerPos()
- 3.44 screenGCD()
- 3.45 screenAspect()
- 3.46 screenChecks()
- 4 Methods
- 5 Objects
Overview
This is the main class for the helper library with its members and part of the Cabal_Common_Library.
Scripts can instantiate a copy of the API, e.g.
this.myHelper = new worldScripts.Cabal_Common_Functions.Cabal_Common();
Versions before v1.6 have used this.myHelper = new Cabal_Common();
Added in v1.8
A convenience instance is created and can be used directly. This is specially useful if you only need a small part of the library.
worldScripts.Cabal_Common_Functions.helper.getType(obj);
The Profiler boxes will give you a quick overview about runtimes. Times are measured with the listed examples on a Core2Duo @2GHz.
Properties
internalVersion
Number. Property to give OXPs a chance to check the required lib min. version easily. This number will be raised with every release.
var a = worldScripts.Cabal_Common_Functions.internalVersion;
The property is available in the API as well.
var a = this.myHelper.internalVersion;
Current version is
15 |
API Methods
baseChange()
baseChange: function( n, to, from ) |
Profiler | |
---|---|
Native | 0.000038s |
Extension | 0.000012s |
JS | 0.000067s |
Changes the base of n.
Parameters:
- n
- Number. To be changed.
- to
- Number. Base which should be used to convert to. Usually 2,10 or 16.
- from
- Number. Optional. Base from which should be converted. Usually 2,10 or 16.
Returns:
- str
- String. Base changed.
var a = this.myHelper.baseChange(10, 16); // convert decimal 10 to hex var b = this.myHelper.baseChange(0xA, 2); // convert hex 0xA (10) to binary var c = this.myHelper.baseChange('a', 2, 16); // alternative convert hex 0xA to binary a -> 'a', b -> '1010', c -> '1010'
Author: Dr.J R Stockton.
clamp()
clamp: function( value, max, min ) |
Profiler | |
---|---|
Native | 0.000041s |
Extension | 0.000012s |
JS | 0.000069s |
Clamps value to max...min.
Paramaters:
- value
- Number. To be clamped.
- max
- Number. Maximum.
- min
- Number. Minimum.
Returns:
- n
- Number. Clamped.
var a = this.myHelper.clamp(Math.random(),0.6,0.2); a -> 0.2
getType()
getType: function( what ) Added in v1.8 |
Profiler | |
---|---|
Native | 0.000040s |
Extension | 0.000010s |
JS | 0.000062s |
Returns lowercase string with the type or null.
Parameters:
- what
- Object. To be evaluated.
Returns:
- type
- String or null. If String 'array', 'boolean', 'date', 'function', 'number', 'object', 'regexp', 'string', or 'undefined'
var a = this.myHelper.getType("A"); a -> "string"
msbPos()
msbPos: function( n ) |
Profiler | |
---|---|
Native | 0.000038s |
Extension | 0.000011s |
JS | 0.000063s |
Returns position of most significant bit of n.
Paramaters:
- n
- Number. To be evaluated.
Returns:
- n
- Number. The position of the most significant bit or 0 (zero).
var a = this.myHelper.msbPos(25); a -> 5
Author: Dr.J R Stockton.
nBitsUsed()
nBitsUsed: function( n ) |
Profiler | |
---|---|
Native | 0.000038s |
Extension | 0.000010s |
JS | 0.000062s |
Returns number of bits set in n. If n<0 a bitwise NOT will be applied before execution.
Parameters:
- n
- Number. To be evaluated.
Returns:
- e
- Number. The counted number of bits set to 1.
var a = this.myHelper.nBitsUsed(13); a -> 3
num2Prec()
num2Prec: function( x, p ) |
Profiler | |
---|---|
Native | 0.000041s |
Extension | 0.000010s |
JS | 0.000069s |
Returns rounded number with specified precision.
Parameters:
- x
- Number. To be rounded.
- p
- Number. Precision.
Returns:
- e
- Number. The rounded number.
var a = this.myHelper.num2Prec(25.06532123,3); a -> 25.065
pseudoRand()
pseudoRand: function( salt, mode ) |
Profiler | |
---|---|
Native | 0.000041s |
Extension | 0.000017s |
JS | 0.000106s |
LCG (Linear congruential generator) pseudo-random number generator with salt (and pepper). Can be used to generate deterministic unique values, e.g. to decide if a specific entity should be spawned.
Parameters:
- salt
- Number. This is used to generate a pseudo random number.
- mode
- Boolean. Optional. If specified and true the returned value is integer (Math.floor(n*100)).
Returns:
- n
- Number.
- No mode. In range 0...1,
- mode. In range 0...100.
var test = this.myHelper.pseudoRand(55); test -> 0.11969016003422439
var test = this.myHelper.pseudoRand(55,true); test -> 11
Author: Jens Ayrton (Ahruman).
rand()
rand: function( n ) |
Profiler | |
---|---|
Native | 0.000038s |
Extension | 0.000011s |
JS | 0.000066s |
Random number in range 0...n.
Parameters:
- n
- Number. Maximum value.
Returns:
- n
- Number. Returns the random Number.
var crc = this.myHelper.rand(35); crc -> 12
Author: Dr.J R Stockton.
randSpan()
randSpan: function( minN, maxN ) |
Profiler | |
---|---|
Native | 0.000037s |
Extension | 0.000012s |
JS | 0.000086s |
Random number in range minN...maxN.
Paramaters:
- minN
- Number. Minimum.
- maxN
- Number. Maximum.
Returns:
- n
- Number. The newly generated random Number.
var crc = this.myHelper.randSpan(35,88); crc -> 55
Author: Dr.J R Stockton.
strAddAlignedText()
strAddAlignedText: function( text, alignment ) Added in v1.6.1 |
Profiler | |
---|---|
Native | 0.000122s |
Extension | 0.000028s |
JS | 0.000082s |
Returns padded text for a single line.
Parameters:
- text
- String.
- alignment
- String. Optional. Either L, C or R. Default L.
Returns:
- str
- String. Padded text.
Author: Thargoid.
strAddEdgeText()
strAddEdgeText: function( leftText, rightText ) Added in v1.6.1 |
Profiler | |
---|---|
Native | 0.000159s |
Extension | 0.000040s |
JS | 0.000295s |
Returns two edge-aligned columns, one on the left and the other on the right for a single line.
Parameters:
- leftText
- String.
- rightText
- String.
Returns:
- str
- String. Aligned text.
Author: Thargoid.
strAddIndentedText()
strAddIndentedText: function( text, indent ) Added in v1.6.1 |
Profiler | |
---|---|
Native | 0.000112s |
Extension | 0.000028s |
JS | 0.000133s |
Returns indented line of text by the given distance (in ems) from the left.
Parameters:
- text
- String.
- indent
- Number. Value in ems.
Returns:
- str
- String. Indented text.
Author: Thargoid.
strAdd2Columns()
strAdd2Columns: function( leftText, leftIndent, rightText, rightIndent ) Added in v1.6.1 |
Profiler | |
---|---|
Native | 0.000137s |
Extension | 0.000057s |
JS | 0.000414s |
Returns single line text with two columns indented from the left margin by the given amount (in ems, 0-32).
Parameters:
- leftText
- String.
- leftIndent
- Number. Valöue in ems.
- rightText
- String.
- rightIndent
- Number. Value in ems.
Returns:
- str
- String. Text with 2 columns.
Author: Thargoid.
strAdd3Columns()
strAdd3Columns: function( leftText, leftIndent, centreText, centreIndent, rightText, rightIndent ) Added in v1.6.1 |
Profiler | |
---|---|
Native | 0.000041s |
Extension | 0.000013s |
JS | 0.000366s |
Returns single line text with three columns, left, centre and right.
Parameters:
- leftText
- String.
- leftIndent
- Number. Value in ems.
- centreText
- String.
- centreIndent
- Number. Value in ems.
- rightText
- String.
- rightIndent
- Number. Value in ems.
Returns:
- str
- String. Text with 3 columns.
Author: Thargoid.
strCompareVersion()
strCompareVersion: function( strA, strB ) |
Profiler | |
---|---|
Native | 0.000033s |
Extension | 0.000010s |
JS | 0.000080s |
Compares version strings (like “2.0.3”) against each other and returns number. It also strips pre/suffixes like “Build” or “Beta”. Subroutine from oxpVersionTest() and oxpVersionTest2Array(), but can also be used directly.
Parameters:
- strA
- String. Actual version.
- strB
- String. Version to be compared against.
Returns:
- 0 - Number. If strA < strB
- 1 - Number. If strA = strB
- 2 - Number. If strA > strB
var check = this.myHelper.strCompareVersion("Beta2.1","1.0.7"); check -> 2
strDateFromMinutes()
strDateFromMinutes: function( minutes ) |
Profiler | |
---|---|
Native | 0.000038s |
Extension | 0.000011s |
JS | 0.000067s |
Takes an integer number of minutes and converts it into a string. The returned string has the form 'd' days, 'h' hours and 'm' minutes, accomodating all cases of singular, plural, and 0.
Parameters:
- minutes
- Number. The time in minutes.
Returns:
- timeString
- String.
var str = this.myHelper.strDateFromMinutes(56566); str -> 39 days, 6 hours and 46 minutes var str = this.myHelper.strDateFromMinutes(-56566); str -> 39 days, 6 hours and 46 minutes ago
Author: Commander McLane.
strDecrypt()
strDecrypt: function( str, pwd ) |
Profiler | |
---|---|
Native | 0.000038s |
Extension | 0.000012s |
JS | 0.000148s |
Decrypts string.
Parameters:
- str
- String. To be decrypted. Minimum length 6 chars.
- pwd
- String. Password. Minimum length 4 chars.
Returns:
- dec_str
- String/Boolean. Decrypted string or false.
var test = this.myHelper.strDecrypt("6053cae17efb01230f4768046cac63","MYPASS"); test -> "Hello world"
Author: Terry Yuen.
strEncrypt()
strEncrypt: function( str, pwd ) |
Profiler | |
---|---|
Native | 0.000038s |
Extension | 0.000011s |
JS | 0.000137s |
Encrypts string.
Parameters:
- str
- String. To be encrypted. Minimum length 6 chars.
- pwd
- String. Password. Minimum length 4 chars.
Returns:
- enc_str
- String/Boolean. Encrypted string or false.
var test = this.myHelper.strEncrypt("Hello world","MYPASS"); test -> "6053cae17efb01230f4768046cac63"
Author: Terry Yuen.
strGetCRC()
strGetCRC: function( str ) |
Profiler | |
---|---|
Native | 0.000038s |
Extension | 0.000011s |
JS | 0.000062s |
Very simple CRC from string and does not create unique checksums. It uses Unicodes, but limits every char via &0xff and the output via &0x3fff.
Parameters:
- str
- String. Which should be used to create a CRC.
Returns:
- crc
- Number. The CRC.
var crc = this.myHelper.strGetCRC("Hello"); crc -> 500
strLZ()
strLZ: function( n ) |
Profiler | |
---|---|
Native | 0.000039s |
Extension | 0.000011s |
JS | 0.000060s |
Returns string with a leading zero if n<10.
Parameters:
- n
- Number. To be evaluated.
Returns:
- str
- String. With leading zero if necessary.
var a = this.myHelper.strLZ(3); a -> "03"
Author: Dr.J R Stockton.
strLZZ()
strLZZ: function( n ) |
Profiler | |
---|---|
Native | 0.000039s |
Extension | 0.000010s |
JS | 0.000095s |
Returns string with a leading zeros if n<100. Uses strLZ() as subfunction.
Parameters:
- n
- Number. To be evaluated.
Returns:
- str
- String. With leading zeros if necessary.
var a = this.myHelper.strLZZ(3); a -> "003"
Author: Dr.J R Stockton.
strNLZ()
strNLZ: function( n,len ) |
Profiler | |
---|---|
Native | 0.000039s |
Extension | 0.000011s |
JS | 0.000068s |
Returns string with length of len filled with leading zeros.
Parameters:
- n
- Number. To be evaluated.
- len
- Number. Length. Maximum is 10.
Returns:
- str
- String. Filled up with leading zeros.
var a = this.myHelper.strNLZ(3,4); a -> "0003"
strRandom()
strRandom: function( le ) |
Profiler | |
---|---|
Native | 0.000041s |
Extension | 0.000013s |
JS | 0.000094s |
Returns random string with length of le.
Parameters:
- le
- Number. Length.
- charSet
- String. Optional. Used set of chars.
Returns:
- str
- String with specified length.
var a = this.myHelper.strRandom(6); a -> "hsdoiv"
strRandomInt()
strRandomInt: function( le ) |
Profiler | |
---|---|
Native | 0.000048s |
Extension | 0.000011s |
JS | 0.000070s |
Returns random numbered string with length of l.
Parameters:
- le
- Number. Length in range of 1...9.
Returns:
- str
- String with specified length.
var a = this.myHelper.strRandomInt(6); a -> "524567"
strScreenSubString()
strScreenSubString: function( str, chrs ) |
Profiler | |
---|---|
Native | 0.000038s |
Extension | 0.000010s |
JS | 0.000067s |
Formats the string str into lines of at most chrs characters in length. Subfunction of strScreenString().
Parameters:
- str
- String. To be used.
- chrs
- Number. The length.
Returns:
- out
- String. With specified length.
var scr = this.myHelper.strScreenSubString("Iwantthisandnotthatandforsurenotsuch",16); scr -> "Iwantthisandnott\nhatandforsurenot\nsuch"
strScreenString()
strScreenString: function( str, mode, chrs ) |
Profiler | |
---|---|
Native | 0.000038s |
Extension | 0.000011s |
JS | 0.000076s |
Splits string in pieces of chrs, with intermediate linebreaks for missionscreens. The method splits the incoming string by spaces and loops over the elements, and tries to fill up the current line until the maximum length (chrs) is reached. If there are still remaining elements the next line will be used. The replacement (mode) is done via regexp and removes the following: ‘\t \r \f \n \v’. If splitting is not possible or a word is longer than chrs, strScreenSubString() will be used.
Parameters:
- str
- String. To be used.
- mode
- Boolean. Optional. If mode is false or not specified it replaces special signs like linebreaks with spaces.
- chrs
- Number. Optional. Length. If not specified default of 70 is used.
Returns:
- display
- String. With linebreaks.
var scr = this.myHelper.strScreenString("I want this and not that and for sure not such",1,16); scr -> "I want this and\nnot that and for\nsure not such"
strSplitToPhrases()
strSplitToPhrases: function( str, n ) |
Profiler | |
---|---|
Native | 0.000038s |
Extension | 0.000010s |
JS | 0.000097s |
Splits string into n words phrases.
Parameters:
- str
- String. To be used.
- n
- Number. Words.
Returns:
- out
- Array. Containing Strings with n words per element.
var cleanedArray = this.myHelper.strSplitToPhrases("My cat has a good time",3); cleanedArray -> ["My cat has","cat has a","has a good","a good time"]
strToWidth()
strToWidth: function( str, max, chr ) |
Profiler | |
---|---|
Native | 0.000086s |
Extension | 0.000040s |
JS | 0.000102s |
Returns string with specific length based on Oolites font size. If stringwidth > max it is truncated, otherwise filled up with space or specified chr.
Parameters:
- str
- String. To be used.
- max
- Number. Maximum width.
- chr
- String. Char to be used to fill up if stringwidth < max.
Returns:
- str
- String. With specified width.
var a = this.myHelper.strToWidth("MyveryOwnApproach",3); a -> "Myvery"
strTrim()
strTrim: function( str ) |
Profiler | |
---|---|
Native | 0.000036s |
Extension | 0.000011s |
JS | 0.000080s |
Returns trimmed string. The difference to SpiderMonkeys native .trim() is that it removes not only leading or trailing whitespaces. It replaces also control characters (\b\f\r\n\t\v) via Regexp.
Parameters:
- str
- String.
Returns:
- str
- String.
var a = this.myHelper.strTrim(" Myvery "); a -> "Myvery"
arrDiff()
arrDiff: function( ar1, ar2 ) |
Profiler | |
---|---|
Native | 0.000038s |
Extension | 0.000012s |
JS | 0.000096s |
Returns difference between two arrays.
Parameters:
- ar1
- Array. First.
- ar2
- Array. Second.
Returns:
- diff
- Array. Difference between two arrays.
var testA = ["AA","AB","AC"],testB = ["AB","AC","AD"]; var cleanedArray = this.myHelper.arrDiff(testA,testB); cleanedArray -> ["AA","AD"]
arrFlat()
arrFlat: function( arr ) Added in v1.8 |
Profiler | |
---|---|
Native | 0.000039s |
Extension | 0.000012s |
JS | 0.000259s |
Flattens multidimensional arrays.
Parameters:
- arr
- Array. To be flattened.
Returns:
- r
- Array.
var a = [ ["AA"],["AB"],[ ["AC"] ] ]; var b = this.myHelper.arrFlat(a); b -> ["AA","AB","AC"]
arrRemoveByValue()
arrRemoveByValue: function( arr, val ) |
Profiler | |
---|---|
Native | 0.000038s |
Extension | 0.000010s |
JS | 0.000070s |
Removes specific entry from array. The method works in-place.
Parameters:
- arr
- Array. From which things should be removed.
- val
- Object. Value that has to be removed.
Returns:
- arr
- Array. The cleaned array.
var testA = ["A","B","C"]; var cleanedArray = this.myHelper.arrRemoveByValue(testA,"B"); cleanedArray -> ["A","C"]
arrShuffle()
arrShuffle: function( arr ) |
Profiler | |
---|---|
Native | 0.000037s |
Extension | 0.000011s |
JS | 0.000191s |
Returns shuffled array.
Parameters:
- arr
- Array.
Returns:
- ar
- Array. Shuffled.
var Q = "ABCDEFGHIKJKLM".split(""); var shuffledArray = this.myHelper.arrShuffle(Q); shuffledArray -> ["B","I","M","A","K","C","F","H","K","J","D","E","L","G"]
Author: Ronald Fisher and Frank Yates
arrSortByProperty()
arrSortByProperty: function( arr, prop ) |
Profiler | |
---|---|
Native | 0.000034s |
Extension | 0.000010s |
JS | 0.000088s |
Sort array containing objects by specific property. Starting with v1.7.1 it uses a SelectionSort algorithm. The method works in-place.
Parameters:
- arr
- Array. To be sorted.
- prop
- String. Propertyname.
Returns:
- what
- Array. Sorted by specified property.
var objA = [{ID:2,Other:"TestA"},{ID:1,Other:"TestB"}]; var sorted = this.myHelper.arrSortByProperty(objA,"ID"); sorted -> [{ID:1,Other:"TestB"},{ID:2,Other:"TestA"}]
Author: Nicholas C. Zakas.
arrUnique()
arrUnique: function( arr ) |
Profiler | |
---|---|
Native | 0.000037s |
Extension | 0.000012s |
JS | 0.000072s |
Removes duplicates from array.
Parameters:
- arr
- Array. The input array, from which duplicates are to be removed.
Returns:
- r
- Array. The cleaned array.
var testArray = ["AB","AB","AB","AC","AC","AC"]; var cleanedArray = this.myHelper.arrUnique(testArray); cleanedArray -> ["AB","AC"]
objClone()
objClone: function( src ) Added in v1.8 |
Profiler | |
---|---|
Native | 0.000033s |
Extension | 0.000009s |
JS | 0.000146s |
Creates a clone of the input object.
Parameters:
- src
- Object. To be copied.
Returns:
- obj
- Object. Cloned object.
var dir = this.myHelper.objClone({a:["a","b"],b:["c","d"]});
objFindKeyValue()
objFindKeyValue: function( obj, key, value ) Added in v1.8 |
Profiler | |
---|---|
Native | 0.000040s |
Extension | 0.000011s |
JS | 0.000139s |
Returns all objects which match key===value.
Parameters:
- obj
- Object. To be checked.
- key
- String. Keyname.
- value
- Any.
Returns:
- result
- Array. All objects where key===value.
var x = {a:[{id:2},{id:4}],b:["c","d"]}; var y= this.myHelper.objClone(x,"id",4); -> {id:4}
mapCoordsDirection()
mapCoordsDirection: function( posA, posB ) |
Profiler | |
---|---|
Native | 0.000355s |
Extension | 0.000259s |
JS | 0.000140s |
Returns the general direction of the target coordinates compared to the current (or specified) system coordinates.
Parameters:
- posA
- Vector/ID. Map coordinates in LYs or simply a system.ID.
- posB
- Vector/ID. Optional. Map coordinates in LYs or simply a system.ID. Defaults to current system coordinates.
Returns:
- str
- String.
var dir = this.myHelper.mapCoordsDirection([27,33,0]); dir -> "north-west"
Author: Eric Walch.
oxpVersionTest()
oxpVersionTest: function( who, requires, quiet ) |
Profiler | |
---|---|
Native | 0.000456s |
Extension | 0.000061s |
JS | 0.000201s |
Checks required OXPs and versions. The array is expected to contain two elements for each script and version must be null for legacy scripts!
Checking requirements can be a pain as the version property often contains several numbers, such as Oolites own scripts (“1.74.2”), and checking for a minimum version is sometimes necessary. The method does exactly this and returns false if the requirments are not matched and logs where they are not fullfilled. It also strips pre/suffixes like “Build” or “Beta”. To use it you’ll need an array of required OXPs and their versions. This array can hold JS and Legacy worldScripts and the version can be set to null (required for Legacy), false or 0 (integer) to bypass the version test and only perform the check for existance. The method checks for a property ‘deactivated’ in OXPs to determine whether or not they are deactived.
Parameters:
- who
- String. Actual scriptname. It’s only used to log for which OXP the requirements are not fullfilled.
- requires
- Array. Holds for every required OXP the scriptname and version. To check only for existance set version to null.
- quiet
- Boolean. Optional. If true don't log, only check.
Returns:
- Boolean.
- false - If a requirement is not fullfilled or OXP is deactivated,
- true - Otherwise.
var requires = ["snoopers","2.0.8","vector","1.5","Cabal_Common_Keyboard","1.0"]; var checked = this.myHelper.oxpVersionTest(this.name,requires); checked -> true (or false)
oxpVersionTest2Array()
oxpVersionTest2Array: function( who, requires, quiet ) |
Profiler | |
---|---|
Native | 0.000299s |
Extension | 0.000061s |
JS | 0.000198s |
Checks required OXPs and versions. The array is expected to contain two elements for each script and version must be null for legacy scripts! See the description for oxpVersionTest() for more details.
Parameters:
- who
- String. Actual scriptname. It’s only used to log for which OXP the requirements are not fullfilled.
- requires
- Array. Holds for every required OXP the scriptname and version. To check only for existance set version to null.
- quiet
- Boolean. Optional. If true don't log, only check.
Returns:
- checked
- Array. With values for checked elements of requires.
- 2 - version is greater,
- 1 - version is equal,
- 0 - not installed,
- -1 - OXP is deactivated,
- -2 - version is lower.
var requires = ["snoopers","2.0.8","vector","1.5","Cabal_Common_Keyboard","1.0"]; var checked = this.myHelper.oxpVersionTest2Array(this.name,requires); checked -> [1,-2,1]
entModelView()
entModelView: function( which ) |
Profiler | |
---|---|
Native | 0s |
Extension | 0s |
JS | 0s |
Spawns or resets the modelview entity and returns it. Via JS we can set the orientation, position, etc. of the displayed model, but we can’t stop the rotation if spinModel is not explicitely set to false, because it is hardcoded for screen models and the AI of the model itself can’t do it, because AIs are not executed on missionscreens. That’s why we sometimes need a control entity to do the job.
The modelview entity scans for a specific role and if found sets its target and does the “safeScriptActionOnTarget: performTumble” on the missionscreen model. This overrides the hardcoded rotation with the specified settings in shipdata.plist for the model.
The model (for the missionscreen) has to declare
- role to be scanned via modelview entity - default for the library is ‘cabal_common_model’.
- max_flight_pitch (usually between 0..0.2)
- max_flight_roll (usually between 0..0.2)
Parameters:
- which
- String. Optional. Role to be used for modelview. If not specified defaults to ‘cabal_common_modelview’.
Returns:
- mv
- Entity. Returns modelview Entity or null.
var a = this.myHelper.entModelView(); a -> [Ship "cabal_common_modelview" position: (8846.43, 8857.51, -2544.76) scanClass: CLASS_NEUTRAL status: STATUS_IN_FLIGHT]
entFaceEntity()
entFaceEntity: function( ent1, ent2 ) |
Profiler | |
---|---|
Native | 0.000408s |
Extension | 0.000193s |
JS | 0.000164s |
This function causes ent1 to be reorientated such that it faces ent2. A common use-case is when spawning stations whose docking tunnel should face another entity, typically the main planet. Reorienting is instantly.
Parameters:
- ent1
- Entity. To be reoriented.
- ent2
- Entity. To which ent1 should be oriented.
Returns:
- nothing.
var a = player.ship.target; var b = system.mainPlanet; this.myHelper.entFaceEntity(a,b);
entScreenCornerPos()
entScreenCornerPos: function( level, signx, signy, further ) |
Profiler | |
---|---|
Native | 0.000811s |
Extension | 0.000335s |
JS | 0.000264s |
Missionscreen model corner positioning.
Parameters:
- level
- Number. Amount of moving to screen corner. (0.0 ... 1.0).
- signx
- Number. Used as sign mantissa and multiplier (-1...1) for X axis.
- signy
- Number. Used as sign mantissa and multiplier (-1...1) for Y axis.
- further
- Number. Multiplier for Z axis. Defaults to 1.3.
Returns: nothing.
var scr = this.myHelper.entScreenCornerPos(0.8,0.9,1.1,3.2);
screenGCD()
screenGCD: function( a, b ) |
Profiler | |
---|---|
Native | 0.000047s |
Extension | 0.000011s |
JS | 0.000095s |
Returns greatest common denominator. Subfunction of .screenChecks().
Parameters:
- a
- Number.
- b
- Number.
Returns:
- n
- Number.
var a = this.myHelper.screenGCD(25,5); a -> 5
screenAspect()
screenAspect: function( w, h ) |
Profiler | |
---|---|
Native | 0.000043s |
Extension | 0.000011s |
JS | 0.000117s |
Returns aspect ratio. Subfunction of .screenChecks().
Parameters:
- w
- Number. Width.
- h
- Number. Height.
Returns:
- n
- Number.
var a = this.myHelper.screenAspect(1024,768); a -> 1.3333333333
screenChecks()
screenChecks: function( w, h ) |
Profiler | |
---|---|
Native | 0.000348s |
Extension | 0.000104s |
JS | 0.000164s |
Returns array with width, height, gcd and aspect ratio.
Parameters:
- w
- Number. Width. Optional.
- h
- Number. Height. Optional.
Returns:
- a
- Array.
var a = this.myHelper.screenChecks(); a -> [1024,768,256,1.33333333]
Methods
findSystemsPredicate()
findSystemsPredicate( arr ) Added in v1.8 |
Profiler | |
---|---|
Native | 0.000043s |
Extension | 0.000011s |
JS | 0.001751s |
Returns array with system.IDs if the system data matches the passed conditions. The method uses the binary searchtree in galaxyStats, so it is available after startUp only.
Parameters:
- arr
- Array. Holds objects with the following members to compare system data against.
- Object:
- eco:Number. In range [0...7].
- gov:Number. In range [0...7].
- tec:Number. In range [0...15].
- All members above need also:
- c:Number. Required. In range [1...4] with 1=Equal, 2=Not equal, 3=Greaterthan, 4=Lessthan.
- Object:
Returns:
- result
- Array. Either empty or holding system.IDs.
var a = [{eco:0,c:1},{gov:7,c:1},{tec:12,c:3}]; var b = worldScripts.Cabal_Common_Functions.findSystemsPredicate(a);
updateGalaxyStats()
updateGalaxyStats( id ) Added in v1.8 |
Updates nodes in galaxyStats and lists ecos, govs, tecs and nova. If id is not specified current system.ID is used if player is not in interstellar space.
Parameters:
- id
- Number. Optional system.ID.
Returns:
- nothing.
Objects
moreInfo
Holds additional infos which can be useful for OXPs. The object holds several properties and methods. Scripts can gather the infos
var myInfo = worldScripts.Cabal_Common_Functions.moreInfo;
moreInfo Properties
- avgEnts
- Number. Average number of entities on
shipExitedWitchspace
in the first 30 jumps in a session. - avgEntsOXP
- Number. Delayed average number of entities (30 jumps).
- jumpCount
- Number of jumps the player has done in this session.
- lastJumpDiff
- Number. Time difference between
lastJumpTime
and current time. - lastJumpTime
- Number. Time when the last jump occured. Uses
clock.absoluteSeconds
moreInfo Objects
- ecos
- Added in v1.8 Array. Holds 8 arrays of system.IDs for the systems economy.
- govs
- Added in v1.8 Array. Holds 8 arrays of system.IDs for the systems governments.
- tecs
- Added in v1.8 Array. Holds 16 arrays of system.IDs for the systems techlevels. If the systems techlevel is >14, it is stored in tecs[15].
Profiler | |
---|---|
Native | 0.000050s |
Extension | 0.000016s |
JS | 0.000087s |
- galaxyStats
- Added in v1.7 Object. Binary search tree. The collected objects are holding only primitive values (= no references to System.infoForSystem) to keep it fast. coordinates, description, economy, government, ID, inhabitant, inhabitants, market, name, population, productivity, radius, sun (true, if sun_gone_nova false) and techlevel are stored.
- Scripts can access the data via
var myInfo = worldScripts.Cabal_Common_Functions.moreInfo.galaxyStats.contains(7);
- The returned object holds the above mentioned properties for the requested system.
- Building the search tree is costly though, so the script does it only on
startUp
andplayerEnteredNewGalaxy
. Accessing all systems eats >200 ms, but getting values from this search tree is ~10 times faster for every access than getting it directly via System.infoForSystem, so it is suitable for OXPs which need to access multiple system data sets.
- Building the search tree is costly though, so the script does it only on
- The nodes for the current system are updated on
shipWillEnterWitchspace
andshipWillExitWitchspace
.
- The nodes for the current system are updated on