Difference between revisions of "Cabal Common Library Doc OXPStrength"

From Elite Wiki
m (added deprecated marks)
m (→‎grabSTDValue())
 
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Overview ==
  
== Overview ==
  +
{{OXPNote|The calculations will change for v1.7.1, resulting in more precise and higher values and faster processing time. The documentation reflects the current status of changes. By the time of writing only 1 OXP is affected (Vector). The values below are subject to change}}
  +
  +
 
This is the main class for the OXPStrength with its members and part of the [[Cabal_Common_Library]].
  
This is the main class for the OXPStrength with its members and part of the [[Cabal_Common_Library]].
   
−
It is a helper tool specially for mission OXPs to check the environment and helps to determine the players strength.
 +
It is a helper tool specially for mission OXPs to check the environment and helps to determine the players strength. The script is meant for OXP developers only and does nothing on it's own. It's main purpose is to help OXPs to decide if specific options should/can be offered to the player or if super strong entities may affect the mission.
   
−
The underlaying API calculates a checksum (coef) for entities. This checksum can be gathered by scripts for specific entities (Player and NPCs). Factors are:
 +
The underlaying API calculates a checksum (coef) for entities in relation to the hotspots (main station, witchpoint and lanes witchpoint->planet, planet->sun, witchpoint->sun). This checksum can be gathered by scripts for specific entities (Player and NPCs) and for all NPCs. Factors are:
   
−
* accuracy (v1.7.1)
 +
* Accuracy (v1.7.1)
−
* distance to the hotspots (MainStation,WP and lanes WP,WS,PS)
 +
* Distance to the hotspots (Main Station, WP and lanes WP, PS, WS)
−
* EQs
 +
* Equipment
−
* escorts / defense ships
 +
* Escorts / Defense ships
−
* laser
 +
* Laser
−
* mass (v1.7.1)
 +
* Mass (v1.7.1)
−
* maxEnergy
 +
* MaxEnergy
−
* maxSpeed
 +
* MaxPitch (v1.7.1)
−
* maxThrust
 +
* MaxRoll (v1.7.1)
−
* missiles
 +
* MaxSpeed
−
* primaryRole
 +
* MaxThrust
−
* shieldRechargeRates
 +
* Missiles
−
* subent laser
 +
* PrimaryRole
−
* turrets
 +
* ShieldRechargeRates
  +
* Subent laser
  +
* Turrets
   
−
The script can set a missionVariable to be used for strong entities. <sup>Deprecated in favour of condition scripts.</sup>
  
−
{{CodeEx|codeex=missionVariables.CCL_OXPStrength}}
  
−
Main purpose is to prevent the spawning by the populator. These entities can define conditions in <tt>shipdata.plist</tt>. Default is 9. Suggested classes:
  
   
−
* 1 = coef < 100
  
  +
== Functions ==
−
* 2 = coef < 120
  
  +
All profiled times are only for gathering infos for a fully equipped player ship.
−
* 3 = coef < 150
  
  +
=== checkPower() ===
−
* 4 = coef < 180
  
  +
{{CodeEx|codeex=worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.checkPower( entity, logging, coef, location ); }}
−
* 5 = coef < 200
  
  +
{{CodeExTime|native=0.001295|extension=0.000488|js=0.000807}}
−
* 6 = coef < 300
  
  +
Checks entities and returns the gathered coefficient. This is the main entry point for OXPs.
−
* 7 = coef < 500
  
−
* 8 = coef < 1000
  
−
* 9 = otherwise, default.
  
−
{{CodeEx|codeex=conditions = ("mission_CCL_OXPStrength greaterthan 3"); }}
  
−
Starting with v1.7.1 this is replaced by a property
  
−
{{CodeEx|codeex=worldScripts.Cabal_Common_OXPStrength.CCL_OXPStrength}}
  
   
  +
Player ships:
  +
All standard player ships are starting with ~100 if equipped with only a Pulse Laser and based on the installed equipment ramp up to <600 (only native equipment). Stronger OXP ships will get easily >3,000.
   
−
Missionships should use a script_info key that excludes the entity from cleaning to avoid breaking other missions. <sup>Deprecated.</sup>
  
  +
NPCs:
−
{{CodeEx|codeex=script_info = {ccl_missionShip = true;} }}
  
  +
The standard range is <500, but OXP entities can have a lot higher value based on their settings. Multilaser ships and/or turreted ships are getting easily >3,000. Everything beyond 1,000 may affect missions. The highest value I've seen was beyond 40,000,000!
   
  +
'''Parameters:'''
  +
:;entity:Entity. If specified only this entity will be checked, otherwise all entities in the system (except the player).
  +
::Optional.
  +
:;logging:Boolean. If true a verbose list will be logged to <tt>Latest.log</tt>. This is useful while writing OXPs.
  +
::Optional. Default false.
  +
:;coef:Number. If specified the minimum threshold for returned coef. Unused if <tt>entity</tt> is specified.
  +
::Optional. Default 400.
  +
:;location:Number - Bitmask. If used distance calculations are based on set bits.
  +
::Optional. Default 7.
  +
:::Values:
  +
:::*1 - Main Station, default
  +
:::*2 - Witchpoint, default
  +
:::*4 - Lane W->P, default
  +
:::*8 - Lane P->S
  +
:::*16 - Lane W->S
   
−
Additionally a property with the same effect can be set for a specific entity. <sup>Deprecated.</sup>
  
  +
'''Returns:'''
−
{{CodeEx|codeex=this.ccl_missionShip = true; }}
  
  +
:;coef:Number. Calculated coefficient.
  +
::If <tt>entity</tt> was specified the value for this specific entity, otherwise the highest value in the system.
   
  +
*See [[#checkSpaceLane()|checkSpaceLane()]], [[#Table of Player Ships|Table of Player Ships]].
   
−
A third way is to exclude names of entities. This must be done in your own startUp. <sup>Deprecated. Cleaning is removed in v1.7.1.</sup>
  
−
{{CodeEx|codeex=worldScripts.Cabal_Common_OXPStrength.ccl_strengthExclEntByName.push("name1"); }}
  
   
  +
=== checkEQs() ===
  +
{{CodeEx|codeex=worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.checkEQs( entity ); }}
  +
{{CodeExTime|native=0.000423|extension=0.000032|js=0.000083}}
  +
Returns weighted sum of installed equipment.
   
−
== Functions ==
  
  +
'''Paramerters:'''
−
=== checkPower() ===
  
  +
:;entity:Entity.
−
{{CodeEx|codeex=worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.checkPower(entity); }}
  
−
Checks the specified entity and returns the gathered coefficient.
  
   
−
For NPCs the standard range is <100 (except some Vipers), but OXP entities can have a lot higher value based on their settings.
  
  +
'''Returns:'''
−
Playerships are treated different and are getting higher values. A standard Cobra MkIII has a value of 86 in the beginning and gets up to 293 if fully equipped with standard weaponry, missiles and other equipment. The Boa Class Cruiser even gets 304.
  
  +
:;value:Number. Summed value for all installed equipment.
  +
::Every equipment adds based on tokens
  +
:::* 35 - naval, military, jammer, laser
  +
:::* 30 - energy, shield, boost, cloak
  +
:::* 25 - turret, missile, mine
  +
:::* 20 - hide, eeu, rack
  +
:::* 10 - ecm, target
  +
  +
  +
=== checkMissiles() ===
  +
{{CodeEx|codeex=worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.checkMissiles( entity ); }}
  +
{{CodeExTime|native=0.000168|extension=0.000064|js=0.000124}}
  +
Returns weighted sum of pylon mounted weapons.
   
 
'''Parameters:'''
  
'''Parameters:'''
Line 63: Line 88:
   
 
'''Returns:'''
  
'''Returns:'''
−
:;coef:Number. Calculated sum.
  
  +
:;value:Number. Summed value for all mounted pylons.
  +
::Every pylon mounted missile or mine adds based on tokens
  +
:::* 5 - naval, boost, military, cascade
  +
:::* 4 - harpoon, intercept, nuke, law, frag, bomb
  +
:::* 3 - mine, stun, override, jammer, drone, guard, field
  +
:::* 2 - hard, ecm, rack, launcher, ams
  +
:::* 1 - otherwise
   
   
−
=== registerLocation() ===
 +
=== checkSpaceLane() ===
−
{{CodeEx|codeex=worldScripts.Cabal_Common_OXPStrength.registerLocation(obj); }}
 +
{{CodeEx|codeex=worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.checkSpaceLane( entity, location ); }}
−
Scripts can specify systems where logging should happen. Only one object with a few properties has to be passed.
 +
{{CodeExTime|native=0.000286|extension=0.000151|js=0.000319}}
  +
Returns array with distances to the main station, witchpoint and lanes (witchpoint->planet, planet->sun, witchpoint->sun).
   
−
'''Properties of obj:'''
 +
'''Parameters:'''
−
:;CSS:String. Required. worldScriptname.
 +
:;entity:Entity.
−
:;CSP:String. Required. Propertyname to be checked. If true start logging.
 +
:;location:Number.
−
:;Gal:Number. Required. Galaxy.
 +
::Optional. Default 7.
−
:;ID:Number. Required. System ID.
  
−
:;ISS:Boolean. Required. Interstellar (if used activation on leaving ID && misjump).
  
−
:;GJump:Array. galacticHyperspaceFixedCoordsInLY for galactic jumps, e.g. [6.4,51,0].
  
−
:;Strength:Number. Strength for missionVariables.CCL_OXPStrength. <sup>Deprecated.</sup>
  
−
:;checkC:Number. Threshold for logging.
  
−
:;checkK:Number. Threshold for cleaning. The script checks the distance to the player and used handlers. <sup>Deprecated.</sup>
  
−
:;delay:Number. Timer delay for logging.
  
−
:;locate:Number. Only for hotspot 0=all, 1=MainStation, 2=WP, 3=LaneWP, 4=LaneWS, 5=LanePS.
  
−
:;repeat:Number. Repeat logging n times.
  
−
:;logging:Boolean. Log actions. <sup>Deprecated.</sup>
  
−
:;Permanent:Boolean. Flag to keep the entry. If player leaves the specified system and Permanent is not set, the entry will be deleted.
  
−
:;Suspend:Array. Names of worldScripts to be suspended. Following Oktis approach, e.g. ["OXPA","OXPB"]. <sup>Deprecated - unused by OXPs.</sup>
  
   
  +
'''Returns:'''
  +
:;array:Array with the format [ID,distMS,distWP,distLWP,distLPS,distLWS]. Distances >50000 will be -1.
  +
::ID is
  +
:::*-2 - Nova system
  +
:::*-1 - Interstellar space
  +
:::*0 - standard system
  +
:::*1 - interstellar space, entities close to [0,0,0]
  +
:::*2 - standard system, entities close to checked locations
   
−
----
  
  +
*See [[#checkPower()|checkPower()]].
   
  +
  +
=== checkWeapons() ===
  +
{{CodeEx|codeex=worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.checkWeapons(entity); }}
  +
{{CodeExTime|native=0.000144|extension=0.000061|js=0.000139}}
  +
Returns array with values for weapons in standard weapon slots (forward, aft, port, starboard).
  +
  +
'''Parameters:'''
  +
:;entity:Entity.
  +
  +
'''Returns:'''
  +
:;array:Array with the format [number of slots, sum, typestring]. typestring is concatenated string of sum (e.g. "5311").
  +
::sum is the sum of all weapons
  +
:::* 1 - Pulse Laser
  +
:::* 3 - Beam Laser
  +
:::* 4 - Mining Laser, Twin Plasma Cannon
  +
:::* 5 - Military Laser
  +
:::* 8 - Thargoid Laser
  +
  +
  +
=== checkSubWeapons() ===
  +
{{CodeEx|codeex=worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.checkSubWeapons( entity ); }}
  +
{{CodeExTime|native=0.000180|extension=0.000077|js=0.000132}}
  +
Returns array with values for weapons in subEntites.
  +
  +
'''Parameters:'''
  +
:;entity:Entity.
  +
  +
'''Returns:'''
  +
:;array:Array with the format [Number of Turrets, Number of slots, sum, typestring]. typestring is concatenated string of sum, but exclusive turrets (e.g. "1111").
  +
  +
* See [[#checkWeapons()|checkWeapons()]].
  +
  +
  +
=== grabSTDValue() ===
  +
{{CodeEx|codeex=worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.grabSTDValue( mass, name ); }}
  +
{{CodeExTime|native=0.000274|extension=0.000022|js=0.000142}}
  +
Returns calculated value based peak value for the Boa Class Cruiser. Values degrade linear to minimum value. Usecase is to compare the derieved value from [[#checkPower()|checkPower()]] against a list of 'native' values. If name is passed the script will return the standard value for native ships instead if it matches the native names.
  +
  +
'''Parameters:'''
  +
:;mass:Number. E.g. player.ship.mass.
  +
:;name:String.
  +
::Optional.
  +
  +
'''Returns:'''
  +
:;value:Number.
  +
  +
* See [[#checkPower()|checkPower()]], [[#Table of Player Ships|Table of Player Ships]].
  +
  +
== Properties ==
  +
=== CCL_OXPStrength ===
  +
The script can set a property to be used for strong entities.
  +
{{CodeEx|codeex=worldScripts.Cabal_Common_OXPStrength.CCL_OXPStrength = 5;}}
  +
Main purpose is to prevent the spawning by the populator. OXPs can use it in condition scripts. Default is 9.
  +
  +
Suggested classes:
  +
  +
* 1 = coef < 300
  +
* 2 = coef < 400 - This is the default threshold for entities if <tt>logging</tt> is used.
  +
* 3 = coef < 600
  +
* 4 = coef < 800
  +
* 5 = coef < 1,000
  +
* 6 = coef < 1,500
  +
* 7 = coef < 3,000
  +
* 8 = coef < 5,000
  +
* 9 = otherwise, default setting for <tt>CCL_OXPStrength</tt>.
  +
  +
  +
== scriptInfo ==
  +
=== ccl_missionShip ===
  +
Missionships can also use a script_info key to indicate that this entity has to be handled with care by other scripts.
  +
{{CodeEx|codeex=script_info = {ccl_missionShip = true;} }}
  +
  +
  +
== Table of Player Ships ==
  +
A short overview about the values for native Oolite player-ships if fully equipped. OXP equipment and weaponry may add to the values and changed native ships (like in replacement sets) may change these values as well. The table is meant as rough orientation if OXPs want to base decisions on players strength.
  +
  +
{| class="wikitable sortable" border="1" style="border: 1px solid #cfcfbf; background-color: #f0f0ff; color: #000000; vertical-align: top; text-align: left;"
  +
|-valign="top" bgcolor="#e7e7ff"
  +
! valign="center" style="width: 150px;"|Ship
  +
! valign="center" style="width: 150px;"|Standard (only Pulse Laser)
  +
! valign="center" style="width: 150px;"|Hardheads
  +
! valign="center" style="width: 150px;"|QC-Mines
  +
|-
  +
|Adder
  +
|108
  +
|375
  +
|380
  +
|-
  +
|Anaconda
  +
|44
  +
|335
  +
|417
  +
|-
  +
|Asp Mark II
  +
|107
  +
|400
  +
|404
  +
|-
  +
|Boa
  +
|114
  +
|428
  +
|479
  +
|-
  +
|Boa Class Cruiser
  +
|122
  +
|516
  +
|590
  +
|-
  +
|Cobra Mark I
  +
|88
  +
|298
  +
|306
  +
|-
  +
|Cobra Mark III
  +
|105
  +
|470
  +
|517
  +
|-
  +
|Fer-de-lance
  +
|116
  +
|482
  +
|499
  +
|-
  +
|Moray Medical
  +
|112
  +
|384
  +
|400
  +
|-
  +
|Moray Star Boat
  +
|112
  +
|467
  +
|483
  +
|-
  +
|Python
  +
|85
  +
|343
  +
|357
  +
|}
  +
  +
----
 
[[Category:OXPDoc]]
  
[[Category:OXPDoc]]

Latest revision as of 17:38, 12 February 2013

Overview

Mr Gimlet.png

Please note:   The calculations will change for v1.7.1, resulting in more precise and higher values and faster processing time. The documentation reflects the current status of changes. By the time of writing only 1 OXP is affected (Vector). The values below are subject to change.


This is the main class for the OXPStrength with its members and part of the Cabal_Common_Library.

It is a helper tool specially for mission OXPs to check the environment and helps to determine the players strength. The script is meant for OXP developers only and does nothing on it's own. It's main purpose is to help OXPs to decide if specific options should/can be offered to the player or if super strong entities may affect the mission.

The underlaying API calculates a checksum (coef) for entities in relation to the hotspots (main station, witchpoint and lanes witchpoint->planet, planet->sun, witchpoint->sun). This checksum can be gathered by scripts for specific entities (Player and NPCs) and for all NPCs. Factors are:

  • Accuracy (v1.7.1)
  • Distance to the hotspots (Main Station, WP and lanes WP, PS, WS)
  • Equipment
  • Escorts / Defense ships
  • Laser
  • Mass (v1.7.1)
  • MaxEnergy
  • MaxPitch (v1.7.1)
  • MaxRoll (v1.7.1)
  • MaxSpeed
  • MaxThrust
  • Missiles
  • PrimaryRole
  • ShieldRechargeRates
  • Subent laser
  • Turrets


Functions

All profiled times are only for gathering infos for a fully equipped player ship.

checkPower()

worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.checkPower( entity, logging, coef, location );
Profiler
Native 0.001295s
Extension 0.000488s
JS 0.000807s

Checks entities and returns the gathered coefficient. This is the main entry point for OXPs.

Player ships: All standard player ships are starting with ~100 if equipped with only a Pulse Laser and based on the installed equipment ramp up to <600 (only native equipment). Stronger OXP ships will get easily >3,000.

NPCs: The standard range is <500, but OXP entities can have a lot higher value based on their settings. Multilaser ships and/or turreted ships are getting easily >3,000. Everything beyond 1,000 may affect missions. The highest value I've seen was beyond 40,000,000!

Parameters:

entity
Entity. If specified only this entity will be checked, otherwise all entities in the system (except the player).
Optional.
logging
Boolean. If true a verbose list will be logged to Latest.log. This is useful while writing OXPs.
Optional. Default false.
coef
Number. If specified the minimum threshold for returned coef. Unused if entity is specified.
Optional. Default 400.
location
Number - Bitmask. If used distance calculations are based on set bits.
Optional. Default 7.
Values:
  • 1 - Main Station, default
  • 2 - Witchpoint, default
  • 4 - Lane W->P, default
  • 8 - Lane P->S
  • 16 - Lane W->S

Returns:

coef
Number. Calculated coefficient.
If entity was specified the value for this specific entity, otherwise the highest value in the system.


checkEQs()

worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.checkEQs( entity );
Profiler
Native 0.000423s
Extension 0.000032s
JS 0.000083s

Returns weighted sum of installed equipment.

Paramerters:

entity
Entity.

Returns:

value
Number. Summed value for all installed equipment.
Every equipment adds based on tokens
  • 35 - naval, military, jammer, laser
  • 30 - energy, shield, boost, cloak
  • 25 - turret, missile, mine
  • 20 - hide, eeu, rack
  • 10 - ecm, target


checkMissiles()

worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.checkMissiles( entity );
Profiler
Native 0.000168s
Extension 0.000064s
JS 0.000124s

Returns weighted sum of pylon mounted weapons.

Parameters:

entity
Entity.

Returns:

value
Number. Summed value for all mounted pylons.
Every pylon mounted missile or mine adds based on tokens
  • 5 - naval, boost, military, cascade
  • 4 - harpoon, intercept, nuke, law, frag, bomb
  • 3 - mine, stun, override, jammer, drone, guard, field
  • 2 - hard, ecm, rack, launcher, ams
  • 1 - otherwise


checkSpaceLane()

worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.checkSpaceLane( entity, location );
Profiler
Native 0.000286s
Extension 0.000151s
JS 0.000319s

Returns array with distances to the main station, witchpoint and lanes (witchpoint->planet, planet->sun, witchpoint->sun).

Parameters:

entity
Entity.
location
Number.
Optional. Default 7.

Returns:

array
Array with the format [ID,distMS,distWP,distLWP,distLPS,distLWS]. Distances >50000 will be -1.
ID is
  • -2 - Nova system
  • -1 - Interstellar space
  • 0 - standard system
  • 1 - interstellar space, entities close to [0,0,0]
  • 2 - standard system, entities close to checked locations


checkWeapons()

worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.checkWeapons(entity);
Profiler
Native 0.000144s
Extension 0.000061s
JS 0.000139s

Returns array with values for weapons in standard weapon slots (forward, aft, port, starboard).

Parameters:

entity
Entity.

Returns:

array
Array with the format [number of slots, sum, typestring]. typestring is concatenated string of sum (e.g. "5311").
sum is the sum of all weapons
  • 1 - Pulse Laser
  • 3 - Beam Laser
  • 4 - Mining Laser, Twin Plasma Cannon
  • 5 - Military Laser
  • 8 - Thargoid Laser


checkSubWeapons()

worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.checkSubWeapons( entity );
Profiler
Native 0.000180s
Extension 0.000077s
JS 0.000132s

Returns array with values for weapons in subEntites.

Parameters:

entity
Entity.

Returns:

array
Array with the format [Number of Turrets, Number of slots, sum, typestring]. typestring is concatenated string of sum, but exclusive turrets (e.g. "1111").


grabSTDValue()

worldScripts.Cabal_Common_OXPStrength.checkOXPStrength.grabSTDValue( mass, name );
Profiler
Native 0.000274s
Extension 0.000022s
JS 0.000142s

Returns calculated value based peak value for the Boa Class Cruiser. Values degrade linear to minimum value. Usecase is to compare the derieved value from checkPower() against a list of 'native' values. If name is passed the script will return the standard value for native ships instead if it matches the native names.

Parameters:

mass
Number. E.g. player.ship.mass.
name
String.
Optional.

Returns:

value
Number.

Properties

CCL_OXPStrength

The script can set a property to be used for strong entities.

worldScripts.Cabal_Common_OXPStrength.CCL_OXPStrength = 5;

Main purpose is to prevent the spawning by the populator. OXPs can use it in condition scripts. Default is 9.

Suggested classes:

  • 1 = coef < 300
  • 2 = coef < 400 - This is the default threshold for entities if logging is used.
  • 3 = coef < 600
  • 4 = coef < 800
  • 5 = coef < 1,000
  • 6 = coef < 1,500
  • 7 = coef < 3,000
  • 8 = coef < 5,000
  • 9 = otherwise, default setting for CCL_OXPStrength.


scriptInfo

ccl_missionShip

Missionships can also use a script_info key to indicate that this entity has to be handled with care by other scripts.

script_info = {ccl_missionShip = true;}


Table of Player Ships

A short overview about the values for native Oolite player-ships if fully equipped. OXP equipment and weaponry may add to the values and changed native ships (like in replacement sets) may change these values as well. The table is meant as rough orientation if OXPs want to base decisions on players strength.

Ship Standard (only Pulse Laser) Hardheads QC-Mines
Adder 108 375 380
Anaconda 44 335 417
Asp Mark II 107 400 404
Boa 114 428 479
Boa Class Cruiser 122 516 590
Cobra Mark I 88 298 306
Cobra Mark III 105 470 517
Fer-de-lance 116 482 499
Moray Medical 112 384 400
Moray Star Boat 112 467 483
Python 85 343 357
Retrieved from "http://backup.witchspacewiki.org/index.php?title=Cabal_Common_Library_Doc_OXPStrength&oldid=36103"