Difference between revisions of "Oolite JavaScript Reference: System"

From Elite Wiki
 
(62 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
<small>'''Prototype:''' <code>Object</code></small><br />
  
<small>'''Prototype:''' <code>Object</code></small><br />
−
<small>'''Subtypes:''' none
 +
<small>'''Subtypes:''' none</small>
   
−
The '''<code>System</code>''' class represents the current system. There is always one <code>System</code> object, available through the global propery <code>system</code>.
 +
The '''<code>System</code>''' class represents the current star system. There is always one <code>System</code> object, available through the global property <code>system</code>.
   
 
Attempts to change system properties are ignored in interstellar space (i.e., the place you end up in after a witchspace malfunction).
  
Attempts to change system properties are ignored in interstellar space (i.e., the place you end up in after a witchspace malfunction).
Line 8: Line 8:
 
== Properties ==
  
== Properties ==
 
=== <code>allShips</code> ===
  
=== <code>allShips</code> ===
−
{{Oolite-prop-added|1.70}}
  
 
'''allShips''' : Array (read-only)
  
'''allShips''' : Array (read-only)
−
A list of the ships in the system. If there are none, an empty list.
 +
A list of the ships in the system.
   
−
'''See Also:''' <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.
 +
'''See Also:''' <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>, <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>
  +
  +
=== <code>allVisualEffects</code> ===
  +
{{oolite-prop-added|1.77}}
  +
'''allVisualEffects''' : Array (read-only)
  +
A list of the [[Oolite_JavaScript_Reference:_VisualEffect|visual effects]] in the system.
  +
  +
=== <code>ambientLevel</code> ===
  +
{{oolite-prop-added|1.81}}
  +
'''ambientLevel''' : float (read/write)
  +
Adjusts the level of ambient light in the current system. Values should typically be between 0.0 and 1.0 (1.0 is the default) but can be higher for a flat lit, cartoon-like effect. This is will override the "ambient_level" setting defined in [[Planetinfo.plist]]. The change is not permanent and will be reset when the system is reloaded.
  +
  +
=== <code>breakPattern</code> ===
  +
{{oolite-prop-added|1.77}}
  +
'''breakPattern''' : Boolean (read/write)
  +
If <code>true</code> (the default state set on entry to a new system), the break pattern will be shown to the player as they exit witchspace. While this property may be set from places other than the <code>shipWillExitWitchspace</code> world script event, it is pointless to do so.
  +
  +
Unlike all other system properties, this one may be changed on entry to interstellar space.
   
 
=== <code>description</code> ===
  
=== <code>description</code> ===
Line 20: Line 19:
 
=== <code>economy</code> ===
  
=== <code>economy</code> ===
 
'''economy''' : Number (integer, read/write)
  
'''economy''' : Number (integer, read/write)
−
The type of economy in the current system, ranging from 0 (Rich Industrial) to 7 (Poor Agricultural). (See also: <code>[[#economyDescription|economyDescription]]</code>)
 +
The type of economy in the current system, ranging from 0 (Rich Industrial) to 7 (Poor Agricultural).
  +
  +
'''See Also:''' <code>[[#economyDescription|economyDescription]]</code>
   
 
=== <code>economyDescription</code> ===
  
=== <code>economyDescription</code> ===
 
'''economyDescription''' : String (read-only)
  
'''economyDescription''' : String (read-only)
−
A description of the economy type, for example, “Mostly Industrial”. (See also: <code>[[#economy|economy]]</code>)
 +
A localized description of the economy type, for example, “Mostly Industrial”. Since this string is localized, it should only be used for display purposes.
−  
−
=== <code>goingNova</code> ===
  
−
'''goingNova''' : Boolean (read-only)
  
−
<code>true</code> if the system’s sun is in the process of going nova, <code>false</code> otherwise. ('''To do''': this should be a propery of the sun.) (See also: <code>[[#goneNova|goneNova]]</code>, <code>[[#setSunNova|setSunNova()]]</code>)
  
   
−
=== <code>goneNova</code> ===
 +
'''See Also:''' <code>[[#economy|economy]]</code>
−
'''goneNova''' : Boolean (read-only)
  
−
<code>true</code> if the system’s sun hase gone nova, <code>false</code> otherwise. ('''To do''': this should be a propery of the sun.) (See also: <code>[[#goingNova|goingNova]]</code>, <code>[[#setSunNova|setSunNova()]]</code>)
  
   
 
=== <code>government</code> ===
  
=== <code>government</code> ===
 
'''government''' : Number (read/write, integer)
  
'''government''' : Number (read/write, integer)
−
The type of government in the current system, ranging from 0 (Anarchy) to 7 (Corporate State). (See also: <code>[[#governmentDescription|governmentDescription]]</code>)
 +
The type of government in the current system, ranging from 0 (Anarchy) to 7 (Corporate State).
  +
  +
'''See Also:''' <code>[[#governmentDescription|governmentDescription]]</code>
   
 
=== <code>governmentDescription</code> ===
  
=== <code>governmentDescription</code> ===
 
'''governmentDescription''' : String (read-only)
  
'''governmentDescription''' : String (read-only)
−
A description of the government type, for example, “Democracy”. (See also: <code>[[#government|government]]</code>)
 +
A localized description of the government type, for example, “Democracy”. Since this string is localized, it should only be used for display purposes.
  +
  +
'''See Also:''' <code>[[#government|government]]</code>
   
 
=== <code>ID</code> ===
  
=== <code>ID</code> ===
 
ID : Number (integer, read-only)
  
ID : Number (integer, read-only)
−
A number identifying the system. 0 to 255, or -1 for interstellar space. Equivalent to <code>planet_number</code> in plist scripts.
 +
A number identifying the system. 0 to 255, or -1 for interstellar space.
  +
  +
=== <code>info</code> ===
  +
'''info''' : [[Oolite JavaScript Reference: SystemInfo|SystemInfo]] (read/write)
  +
Allows access to system properties, using the same keys as [[planetinfo.plist]].
  +
  +
'''Example:'''
  +
system.info.description = "This is a dull planet.";
   
 
=== <code>inhabitantsDescription</code> ===
  
=== <code>inhabitantsDescription</code> ===
Line 45: Line 44:
   
 
=== <code>isInterstellarSpace</code> ===
  
=== <code>isInterstellarSpace</code> ===
−
{{Oolite-prop-added|1.70}}
  
 
'''isInterstellarSpace''' : Boolean (read-only)
  
'''isInterstellarSpace''' : Boolean (read-only)
 
<code>true</code> if the current system is in interstellar space, <code>false</code> otherwise.
  
<code>true</code> if the current system is in interstellar space, <code>false</code> otherwise.
   
 
=== <code>mainPlanet</code> ===
  
=== <code>mainPlanet</code> ===
−
{{Oolite-prop-added|1.70}}
  
  +
'''mainPlanet''' : {{oojsclass|Planet}} (read-only)
−
'''mainPlanet''' : [[Oolite JavaScript Reference: Planet|Planet]] (read-only)
  
 
The system’s main planet, or <code>null</code> if there is none.
  
The system’s main planet, or <code>null</code> if there is none.
   
 
=== <code>mainStation</code> ===
  
=== <code>mainStation</code> ===
−
{{Oolite-prop-added|1.70}}
  
 
'''mainStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only)
  
'''mainStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only)
 
The system’s main station, or <code>null</code> if there is none.
  
The system’s main station, or <code>null</code> if there is none.
  +
  +
=== <code>name</code> ===
  +
'''name''' : String (read/write)
  +
The name of the system.
   
 
=== <code>planets</code> ===
  
=== <code>planets</code> ===
−
{{Oolite-prop-added|1.70}}
  
 
'''planets''' : Array (read-only)
  
'''planets''' : Array (read-only)
−
A list of the planets in the system. If there are none, an empty list.
 +
A list of the planets in the system.
   
 
=== <code>population</code> ===
  
=== <code>population</code> ===
 
'''population''' : Number (integer, read/write)
  
'''population''' : Number (integer, read/write)
 
The population of the current system.
  
The population of the current system.
  +
  +
=== <code>populatorSettings</code> ===
  +
{{oolite-prop-added|1.79}}
  +
'''populatorSettings''' : Dictionary (read-only)
  +
The current [[Oolite_System_Populator|populator settings]]. This is only useful to read during while system population is being prepared. After that point further changes are meaningless.
  +
  +
'''See Also:''' <code>[[#setPopulator|setPopulator]]</code>
  +
   
 
=== <code>productivity</code> ===
  
=== <code>productivity</code> ===
 
'''productivity''' : Number (integer, read/write)
  
'''productivity''' : Number (integer, read/write)
 
The productivity of the current system.
  
The productivity of the current system.
  +
  +
=== <code>pseudoRandom100</code> ===
  +
'''pseudoRandom100''' : Number (integer, read-only)
  +
A random number between 0 and 99 that is always the same for a given system. '''Important:''' this method has the undesirable side effect of resetting the system random number generator. It should only be used for backwards-compatibility. For new development, use <code>[[#scrambledPseudoRandomNumber|scrambledPseudoRandomNumber]]()</code> or <code>[[#pseudoRandomNumber|pseudoRandomNumber]]</code>.
  +
  +
=== <code>pseudoRandom256</code> ===
  +
'''pseudoRandom256''' : Number (integer, read-only)
  +
A random number between 0 and 255 that is always the same for a given system. '''Important:''' this method has the undesirable side effect of resetting the system random number generator. It should only be used for backwards-compatibility. For new development, use <code>[[#scrambledPseudoRandomNumber|scrambledPseudoRandomNumber]]()</code> or <code>[[#pseudoRandomNumber|pseudoRandomNumber]]</code>.
  +
  +
=== <code>pseudoRandomNumber</code> ===
  +
'''pseudoRandomNumber''' : Number (read-only)
  +
A random number between 0 and 1 that is always the same for a given system. In general, you should avoid using this number directly and call <code>[[#scrambledPseudoRandomNumber|scrambledPseudoRandomNumber]]()</code> instead.
  +
  +
=== <code>stations</code> ===
  +
{{oolite-prop-added|1.79}}
  +
'''stations''' : Array (read-only)
  +
A list of the stations in the system.
   
 
=== <code>sun</code> ===
  
=== <code>sun</code> ===
−
{{Oolite-prop-added|1.70}}
  
 
'''sun''' : [[Oolite JavaScript Reference: Sun|Sun]] (read-only)
  
'''sun''' : [[Oolite JavaScript Reference: Sun|Sun]] (read-only)
 
The system’s sun, or <code>null</code> if there is none.
  
The system’s sun, or <code>null</code> if there is none.
Line 81: Line 104:
 
The technology level of the current system, ranging from 0 to 15.
  
The technology level of the current system, ranging from 0 to 15.
   
  +
=== <code>wormholes</code> ===
  +
{{oolite-prop-added|1.79}}
  +
'''wormholes''' : Array (read-only)
  +
A list of the [[Oolite_JavaScript_Reference:_Wormhole|wormholes]] in the system.
  +
  +
=== <code>waypoints</code> ===
  +
{{oolite-prop-added|1.79}}
  +
'''waypoints''' : Array (read-only)
  +
A dictionary of the [[Oolite_JavaScript_Reference:_Waypoint|waypoints]] in the system by key and value.
  +
  +
'''See Also:''' <code>[[#setWaypoint|setWaypoint()]]</code>
   
 
== Methods ==
  
== Methods ==
  +
=== <code>addGroup</code> ===
  +
function '''addGroup'''(role : String, count : Number [, position: {{oojsvecexpr}}] [, radius: Number]) : {{oojsclass|ShipGroup}}
  +
Like <code>[[#addShips|addShips()]]</code>, but puts the ships in a group and returns the group.
  +
  +
'''See Also:''' <code>[[#addGroupToRoute|addGroupToRoute()]]</code>, <code>[[#addShips|addShips()]]</code>
  +
  +
=== <code>addGroupToRoute</code> ===
  +
function '''addGroupToRoute'''(role : String, count : Number [, fraction: Number] [, route: String]) : {{oojsclass|ShipGroup}}
  +
Like <code>[[#addShipsToRoute|addShipsToRoute()]]</code>, but puts the ships in a group and returns the group.
  +
  +
'''See Also:''' <code>[[#addGroup|addGroup()]]</code>, <code>[[#addShipsToRoute|addShipsToRoute()]]</code>
  +
 
=== <code>addMoon</code> ===
  
=== <code>addMoon</code> ===
−
'''addMoon'''(planetInfoKey : String)
 +
function '''addMoon'''(planetInfoKey : String) : {{oojsclass|Planet}}
−
Adds a moon to the system, using the specified entry in ''[[planetinfo.plist]]''. A moon is the same as a planet, except that it has no atmosphere. (See also: <code>[[#addPlanet|addPlanet()]]</code>)
 +
Adds a moon to the system, using the specified entry in ''[[planetinfo.plist]]''. A moon is the same as a planet, except that it has no atmosphere.
  +
  +
'''See Also:''' <code>[[#addPlanet|addPlanet()]]</code>
   
 
=== <code>addPlanet</code> ===
  
=== <code>addPlanet</code> ===
−
'''addPlanet'''(planetInfoKey : String)
 +
function '''addPlanet'''(planetInfoKey : String) : {{oojsclass|Planet}}
−
Adds a planet to the system, using the specified entry in ''[[planetinfo.plist]]''. (See also: <code>[[#addMoon|addMoon()]]</code>)
 +
Adds a planet to the system, using the specified entry in ''[[planetinfo.plist]]''.
  +
  +
'''See Also:''' <code>[[#addMoon|addMoon()]]</code>
  +
  +
=== <code>addShips</code> ===
  +
function '''addShips'''(role : String, count : Number [, position: {{oojsvecexpr}}] [, radius: Number]) : Array
  +
Adds ships to the system and returns the added ships in an array. Position is in absolute coordinates. When no position is given, the witchpoint is assumed. When no radius is given, the maximum scanner range is used. Ships added in range of the witchpoint automatically create a witchpoint entry cloud.
  +
  +
When you want to use coordinates from the legacy "pwp" system you can use the function [[Oolite_JavaScript_Reference:_Vector3D#fromCoordinateSystem|fromCoordinateSystem]] to convert legacy type coordinates to absolute coordinates.
  +
  +
If you wish to add ships of a specific shipdata key, pass the key as the "role" parameter, enclosed in square brackets.
  +
  +
'''See Also:''' <code>[[#addGroup|addGroup()]]</code>, <code>[[#addShipsToRoute|addShipsToRoute()]]</code>
  +
  +
=== <code>addShipsToRoute</code> ===
  +
function '''addShipsToRoute'''(role : String, count : Number [, fraction: Number] [, route: String]) : Array
  +
Adds ships to the system on certain common routes and returns the added ships as an array. The routes are the two character codes <code>wp</code>, <code>pw</code>, <code>ws</code>, <code>sw</code>, <code>sp</code>, and <code>ps</code>, where <code>w</code> stands for the witchpoint, <code>p</code> for the planet and <code>s</code> for the sun.
  +
  +
When no route is defined, the route witchpoint → main station is assumed.
  +
  +
The position is a fraction of the route and must be between 0 and 1. Unlike the legacy commands the fraction takes planetary radii in account, so it does not start counting in the centre of sun/planet but from its surface. When no fraction is defined, a random fraction is chosen. Ships are added within scanner range of this position. Ships added in range of the witchpoint automatically create a witchpoint entry cloud.
  +
  +
'''Example''':
  +
var ships = system.addShipsToRoute("myShips", 2, 0.7, "sw")
  +
var pirates = system.addShipsToRoute("pirate", 3, Math.random(), "sp")
  +
The first line adds 2 ships near each-other on the route from sun to witchpoint and puts the added ship in the array <code>ships</code>, and the second line adds a group of 3 pirates at a random position along the sun to planet route and returns the array <code>pirates</code>.
  +
  +
'''Note:''' this method will fail and return <code>null</code> if either of the route end points doesn’t exist. No valid routes exist in interstellar space.
  +
  +
'''See Also:''' <code>[[#addGroupToRoute|addGroupToRoute()]]</code>, <code>[[#addShips|addShips()]]</code>
  +
  +
=== <code>addVisualEffect</code> ===
  +
{{oolite-method-added|1.77}}
  +
function '''addVisualEffect'''(effectKey : String, position: {{oojsvecexpr}}) : VisualEffect
  +
Adds a new visual effect with the effectKey in effectdata to the system, at the specified position, and returns the added effect. If the effectKey does not exist, or creation was otherwise impossible, this method will fail and return <code>null</code>.
  +
  +
Note that unlike the functions for adding ships, <code>addVisualEffect</code> returns a single entity, not an array.
  +
  +
=== <code>countEntitiesWithScanClass</code> ===
  +
function '''countEntitiesWithScanClass'''(scanClass : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Number (integer)
  +
Returns the number of ships with the specified ScanClass in the system.
  +
  +
=== <code>countShipsWithPrimaryRole</code> ===
  +
function '''countShipsWithPrimaryRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Number (integer)
  +
Returns the number of ships with the specified primary role in the system.
   
 
=== <code>countShipsWithRole</code> ===
  
=== <code>countShipsWithRole</code> ===
−
'''countShipsWithRole'''(role : String) : Number (integer)
 +
function '''countShipsWithRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Number (integer)
−
Returns the number of ships with the specified role in the system; equivalent to checkForShips: in plist scripts.
 +
Returns the number of ships with the specified role in the system. Counts not only the primary role the ship is added with but all roles a ship can have.
   
 
=== <code>entitiesWithScanClass</code> ===
  
=== <code>entitiesWithScanClass</code> ===
−
{{Oolite-method-added|1.70}}
  
  +
function '''entitiesWithScanClass'''(scanClass : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
−
'''entitiesWithScanClass'''(scanClass : String [, relativeTo : [[Oolite JavaScript Reference: Entity|Entity]] [, range : Number]]) : Array
  
 
A list of the entities in the system whose scan class is <code>scanClass</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.
  
A list of the entities in the system whose scan class is <code>scanClass</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.
   
Line 103: Line 148:
   
 
=== <code>filteredEntities</code> ===
  
=== <code>filteredEntities</code> ===
−
{{Oolite-method-added|1.70}}
  
  +
function '''filteredEntities'''(this : Object, predicate : Function [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
−
'''filteredEntities'''(this : Object, predicate : Function [, relativeTo : [[Oolite JavaScript Reference: Entity|Entity]] [, range : Number]]) : Array
  
 
A list of the entities for which <code>predicate</code> returns <code>true</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.
  
A list of the entities for which <code>predicate</code> returns <code>true</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.
   
 
'''Example:'''
  
'''Example:'''
−
this.findIdlePoliceInScannerRange = function()
+
this.findIdlePoliceInScannerRange = function()
−
{
+
{
−
function isIdlePolice(entity)
+
function $isIdlePolice(entity)
−
{
+
{
−
return entity.isShip && entity.isPolice && !entity.target
+
return entity.isShip && entity.isPolice && !entity.target
−
}
+
}
−
+
−
return system.filteredEntities(this, isIdlePolice, player, 25600)
+
return system.filteredEntities(this, $isIdlePolice, player.ship, 25600);
 
}
  
}
   
Line 121: Line 165:
   
 
=== <code>legacy_addShips etc.</code> ===
  
=== <code>legacy_addShips etc.</code> ===
−
'''legacy_addShips'''(role : String, count : Number)
 +
function '''legacy_addShips'''(role : String, count : Number)
−
'''legacy_addSystemShips'''(role : String, count : Number, position : Number)
 +
function '''legacy_addSystemShips'''(role : String, count : Number, position : Number)
−
'''legacy_addShipsAt'''(role : String, count : Number, coordscheme : String, where : [[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]])
 +
function '''legacy_addShipsAt'''(role : String, count : Number, coordscheme : String, where : {{oojsvecexpr}})
−
'''legacy_addShipsAtPrecisely'''(role : String, count : Number, coordscheme : String, where : [[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]])
 +
function '''legacy_addShipsAtPrecisely'''(role : String, count : Number, coordscheme : String, where : {{oojsclass|Planet}})
−
'''legacy_addShipsWithinRadius'''(role : String, count : Number, coordScheme : String, where : [[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]], radius : Number)
 +
function '''legacy_addShipsWithinRadius'''(role : String, count : Number, coordScheme : String, where : {{oojsclass|Planet}}, radius : Number)
−
'''legacy_spawn'''(role : String, count : Number)
 +
function '''legacy_spawnShip'''(shipDataKey : String)
−
'''legacy_spawnShip'''(shipDataKey : String)
 +
Various ways of causing ships to appear. Each of these corresponds to a legacy scripting method. For more info about the <code>coordScheme</code>, look at [[Oolite coordinate systems]]. These methods are kept for backwards-compatibility; for new development, <code>[[#addShips|addShips()]]</code> is preferred.
−
Various ways of causing ships to appear. Each of these corresponds to a legacy scripting method. A new, more flexible <code>addShips()</code> function will supersede all of them.
 +
  +
'''Important:''' <code>legacy_spawn</code>, previously listed here, never worked as intended and has been replaced with <code>Ship.[[Oolite JavaScript Reference: Ship#spawn|spawn]]()</code>.
  +
  +
=== <code>locationFromCode</code> ===
  +
{{oolite-method-added|1.79}}
  +
'''locationFromCode(code)''' : Vector
  +
Returns a random location in the region specified by the code string. The code strings are the same as used by the [[Oolite_System_Populator|Oolite populator]]
  +
  +
=== <code>scrambledPseudoRandomNumber</code>===
  +
function '''scrambledPseudoRandomNumber'''(salt : Number (integer)) : Number
  +
Returns a number that’s greater than or equal to zero and less than one. It will always return the same value for a given <code>salt</code> value and system. Crucially, the relationship between systems and numbers is effectively completely different for each salt value, so scripts making similar decisions based on <code>scrambledPseudoRandomNumber()</code> but using different salts will get uncorrelated results. For example, if two different OXPs add a certain type of station to 25% of systems using <code>if (system.pseudoRandomNumber < 0.25)</code>, the two station types will always be found in the same system; using <code>scrambledPseudoRandomNumber()</code> with different salts avoids this.
   
 
=== <code>sendAllShipsAway</code> ===
  
=== <code>sendAllShipsAway</code> ===
−
'''sendAllShipsAway'''()
 +
function '''sendAllShipsAway'''()
 
Makes all ships hyperspace out of the system.
  
Makes all ships hyperspace out of the system.
   
−
=== <code>setSunNova</code> ===
 +
=== <code>setPopulator</code> ===
−
'''setSunNova'''(secondsUntilNova : Number)
 +
{{oolite-method-added|1.79}}
−
Sets the system’s sun to go nova after the specified time interval. Time is specified in [[Time scales in Oolite#Game real time|game real time]].
 +
'''setPopulator(key : String, definition : Object)'''
  +
Sets the [[Oolite_System_Populator|populator settings]] for the specified key to the given definition, or deletes them if the definition is null. Calling this outside of the system population set up is possible but useless. See the populator settings page for more information on the format of the <code>definition</code> object.
  +
  +
'''See Also:''' <code>[[#populatorSettings|populatorSettings]]</code>
  +
  +
=== <code>setWaypoint</code> ===
  +
{{oolite-method-added|1.79}}
  +
'''setWaypoint(key : String, position : VectorExpression, orientation : QuaternionExpression, parameters : Object)'''
  +
Adds a [[Oolite_JavaScript_Reference:_Waypoint|waypoint]] to the system with the given <code>key</code>, placed at the specified <code>position</code> and <code>orientation</code>. <code>parameter</code> is an object with the following optional keys:
  +
* '''size''': the radius of the waypoint in metres
  +
* '''beaconCode''': the beacon code (default "W")
  +
* '''beaconLabel''': the beacon label (default "Waypoint")
  +
Waypoints will be visible only when the player has a working Advanced Space Compass.
  +
  +
'''setWaypoint(key : String)'''
  +
Removes the waypoint with the specified <code>key</code>, if it exists.
  +
  +
In Oolite 1.81, waypoints can either be oriented (the 1.80 default) or unoriented. Unoriented waypoints do not display the directional arrows. To create an unoriented waypoint, set its orientation to the zero quaternion (0,0,0,0) either on creation or later.
  +
  +
'''See Also:''' <code>[[#waypoints|waypoints]]</code>
   
 
=== <code>shipsWithPrimaryRole</code> ===
  
=== <code>shipsWithPrimaryRole</code> ===
−
{{Oolite-method-added|1.70}}
  
  +
function '''shipsWithPrimaryRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
−
'''shipsWithPrimaryRole'''(role : String [, relativeTo : [[Oolite JavaScript Reference: Entity|Entity]] [, range : Number]]) : Array
  
 
A list of the entities in the system whose [[Oolite JavaScript Reference: Ship#primaryRole|primary role]] is <code>role</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.
  
A list of the entities in the system whose [[Oolite JavaScript Reference: Ship#primaryRole|primary role]] is <code>role</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.
   
Line 146: Line 189:
   
 
=== <code>shipsWithRole</code> ===
  
=== <code>shipsWithRole</code> ===
−
{{Oolite-method-added|1.70}}
  
  +
function '''shipsWithRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
−
'''shipsWithRole'''(role : String [, relativeTo : [[Oolite JavaScript Reference: Entity|Entity]] [, range : Number]]) : Array
  
 
A list of the entities in the system whose [[Oolite JavaScript Reference: Ship#roles|role set]] contains <code>role</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.
  
A list of the entities in the system whose [[Oolite JavaScript Reference: Ship#roles|role set]] contains <code>role</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.
   
 
'''See Also:''' <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.
  
'''See Also:''' <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.
   
−
[[Category: Oolite scripting]]
  
  +
  +
== Static Methods ==
  +
=== <code>infoForSystem</code> ===
  +
function '''infoForSystem'''(galaxyNumber: Integer, systemID : Integer) (write-only)
  +
Overwrites existing info of the given system. As properties it uses the [[planetinfo.plist]] keys. e.g.
  +
System.infoForSystem(0, 55).description = "This is a dull planet."
  +
sets the description of planet nr 55 in galaxy 0 to "This is a dull planet."
  +
  +
Starting from Oolite 1.73, all system Info for the present galaxy is also readable. Even though any galaxy system info property is fully settable, due to engine limitations other galaxies' data is not accessible. In other words
  +
System.infoForSystem(0, 55).description
  +
would return "This is a dull planet." if called from galaxy 0, and throw an exception if called from the other galaxies.
  +
  +
Of particular note the spelling of the '''techlevel''' property when using the infoForSystem function to extract it. While the property of system.techLevel is spelt using camelCase, System.infoForSystem(0, 55).techlevel is using all lower case. This is because planetinfo.plist has always had the techlevel key spelt this way.
  +
  +
=== <code>systemIDForName</code> ===
  +
function '''systemIDForName'''(systemName : String) : Integer
  +
Returns the ID number of a system in the current galaxy based on the system name.
  +
  +
'''Note:''' in galaxy 8, there are two systems named “Inzaan”. <code>systemIDForName()</code> will return the lower ID, which is 22.
  +
  +
=== <code>systemNameForID</code> ===
  +
function '''systemNameForID'''(systemID : Integer) : String
  +
Returns the name of a system in the current galaxy based on the given ID number.
  +
  +
  +
[[Category:Oolite JavaScript Reference]]

Latest revision as of 21:24, 18 June 2021

Prototype: Object
Subtypes: none

The System class represents the current star system. There is always one System object, available through the global property system.

Attempts to change system properties are ignored in interstellar space (i.e., the place you end up in after a witchspace malfunction).

Properties

allShips

allShips : Array (read-only)

A list of the ships in the system.

See Also: entitiesWithScanClass(), filteredEntities(), shipsWithPrimaryRole(), shipsWithRole()

allVisualEffects

This property was added in Oolite test release 1.77. 

allVisualEffects : Array (read-only)

A list of the visual effects in the system.

ambientLevel

This property was added in Oolite test release 1.81. 

ambientLevel : float (read/write)

Adjusts the level of ambient light in the current system. Values should typically be between 0.0 and 1.0 (1.0 is the default) but can be higher for a flat lit, cartoon-like effect. This is will override the "ambient_level" setting defined in Planetinfo.plist. The change is not permanent and will be reset when the system is reloaded.

breakPattern

This property was added in Oolite test release 1.77. 

breakPattern : Boolean (read/write)

If true (the default state set on entry to a new system), the break pattern will be shown to the player as they exit witchspace. While this property may be set from places other than the shipWillExitWitchspace world script event, it is pointless to do so.

Unlike all other system properties, this one may be changed on entry to interstellar space.

description

description : String (read/write)

The description of the current system, as seen on the planet info screen.

economy

economy : Number (integer, read/write)

The type of economy in the current system, ranging from 0 (Rich Industrial) to 7 (Poor Agricultural).

See Also: economyDescription

economyDescription

economyDescription : String (read-only)

A localized description of the economy type, for example, “Mostly Industrial”. Since this string is localized, it should only be used for display purposes.

See Also: economy

government

government : Number (read/write, integer)

The type of government in the current system, ranging from 0 (Anarchy) to 7 (Corporate State).

See Also: governmentDescription

governmentDescription

governmentDescription : String (read-only)

A localized description of the government type, for example, “Democracy”. Since this string is localized, it should only be used for display purposes.

See Also: government

ID

ID : Number (integer, read-only)

A number identifying the system. 0 to 255, or -1 for interstellar space.

info

info : SystemInfo (read/write)

Allows access to system properties, using the same keys as planetinfo.plist.

Example: 

system.info.description = "This is a dull planet.";

inhabitantsDescription

inhabitantsDescription : String (read/write)

The description of the inhabitants of the current system, such as “Slimy Blue Frogs”.

isInterstellarSpace

isInterstellarSpace : Boolean (read-only)

true if the current system is in interstellar space, false otherwise.

mainPlanet

mainPlanet : Planet (read-only)

The system’s main planet, or null if there is none.

mainStation

mainStation : Station (read-only)

The system’s main station, or null if there is none.

name

name : String (read/write)

The name of the system.

planets

planets : Array (read-only)

A list of the planets in the system.

population

population : Number (integer, read/write)

The population of the current system.

populatorSettings

This property was added in Oolite test release 1.79. 

populatorSettings : Dictionary (read-only)

The current populator settings. This is only useful to read during while system population is being prepared. After that point further changes are meaningless.

See Also: setPopulator


productivity

productivity : Number (integer, read/write)

The productivity of the current system.

pseudoRandom100

pseudoRandom100 : Number (integer, read-only)

A random number between 0 and 99 that is always the same for a given system. Important: this method has the undesirable side effect of resetting the system random number generator. It should only be used for backwards-compatibility. For new development, use scrambledPseudoRandomNumber() or pseudoRandomNumber.

pseudoRandom256

pseudoRandom256 : Number (integer, read-only)

A random number between 0 and 255 that is always the same for a given system. Important: this method has the undesirable side effect of resetting the system random number generator. It should only be used for backwards-compatibility. For new development, use scrambledPseudoRandomNumber() or pseudoRandomNumber.

pseudoRandomNumber

pseudoRandomNumber : Number (read-only)

A random number between 0 and 1 that is always the same for a given system. In general, you should avoid using this number directly and call scrambledPseudoRandomNumber() instead.

stations

This property was added in Oolite test release 1.79. 

stations : Array (read-only)

A list of the stations in the system.

sun

sun : Sun (read-only)

The system’s sun, or null if there is none.

techLevel

techLevel : Number (integer, read/write)

The technology level of the current system, ranging from 0 to 15.

wormholes

This property was added in Oolite test release 1.79. 

wormholes : Array (read-only)

A list of the wormholes in the system.

waypoints

This property was added in Oolite test release 1.79. 

waypoints : Array (read-only)

A dictionary of the waypoints in the system by key and value.

See Also: setWaypoint()

Methods

addGroup

function addGroup(role : String, count : Number [, position: vectorExpression] [, radius: Number]) : ShipGroup

Like addShips(), but puts the ships in a group and returns the group.

See Also: addGroupToRoute(), addShips()

addGroupToRoute

function addGroupToRoute(role : String, count : Number [, fraction: Number] [, route: String]) : ShipGroup

Like addShipsToRoute(), but puts the ships in a group and returns the group.

See Also: addGroup(), addShipsToRoute()

addMoon

function addMoon(planetInfoKey : String) : Planet

Adds a moon to the system, using the specified entry in planetinfo.plist. A moon is the same as a planet, except that it has no atmosphere.

See Also: addPlanet()

addPlanet

function addPlanet(planetInfoKey : String) : Planet

Adds a planet to the system, using the specified entry in planetinfo.plist.

See Also: addMoon()

addShips

function addShips(role : String, count : Number [, position: vectorExpression] [, radius: Number]) : Array

Adds ships to the system and returns the added ships in an array. Position is in absolute coordinates. When no position is given, the witchpoint is assumed. When no radius is given, the maximum scanner range is used. Ships added in range of the witchpoint automatically create a witchpoint entry cloud.

When you want to use coordinates from the legacy "pwp" system you can use the function fromCoordinateSystem to convert legacy type coordinates to absolute coordinates.

If you wish to add ships of a specific shipdata key, pass the key as the "role" parameter, enclosed in square brackets.

See Also: addGroup(), addShipsToRoute()

addShipsToRoute

function addShipsToRoute(role : String, count : Number [, fraction: Number] [, route: String]) : Array

Adds ships to the system on certain common routes and returns the added ships as an array. The routes are the two character codes wp, pw, ws, sw, sp, and ps, where w stands for the witchpoint, p for the planet and s for the sun.

When no route is defined, the route witchpoint → main station is assumed.

The position is a fraction of the route and must be between 0 and 1. Unlike the legacy commands the fraction takes planetary radii in account, so it does not start counting in the centre of sun/planet but from its surface. When no fraction is defined, a random fraction is chosen. Ships are added within scanner range of this position. Ships added in range of the witchpoint automatically create a witchpoint entry cloud.

Example: 

var ships = system.addShipsToRoute("myShips", 2, 0.7, "sw")
var pirates = system.addShipsToRoute("pirate", 3, Math.random(), "sp")

The first line adds 2 ships near each-other on the route from sun to witchpoint and puts the added ship in the array ships, and the second line adds a group of 3 pirates at a random position along the sun to planet route and returns the array pirates.

Note: this method will fail and return null if either of the route end points doesn’t exist. No valid routes exist in interstellar space.

See Also: addGroupToRoute(), addShips()

addVisualEffect

This method was added in Oolite test release 1.77. 

function addVisualEffect(effectKey : String, position: vectorExpression) : VisualEffect

Adds a new visual effect with the effectKey in effectdata to the system, at the specified position, and returns the added effect. If the effectKey does not exist, or creation was otherwise impossible, this method will fail and return null.

Note that unlike the functions for adding ships, addVisualEffect returns a single entity, not an array.

countEntitiesWithScanClass

function countEntitiesWithScanClass(scanClass : String [, relativeTo : Entity [, range : Number]]) : Number (integer)

Returns the number of ships with the specified ScanClass in the system.

countShipsWithPrimaryRole

function countShipsWithPrimaryRole(role : String [, relativeTo : Entity [, range : Number]]) : Number (integer)

Returns the number of ships with the specified primary role in the system.

countShipsWithRole

function countShipsWithRole(role : String [, relativeTo : Entity [, range : Number]]) : Number (integer)

Returns the number of ships with the specified role in the system. Counts not only the primary role the ship is added with but all roles a ship can have.

entitiesWithScanClass

function entitiesWithScanClass(scanClass : String [, relativeTo : Entity [, range : Number]]) : Array

A list of the entities in the system whose scan class is scanClass. If relativeTo is specified, the list will be sorted in order of proximity to relativeTo (i.e., the first element of the list is closest). If range is also specified, entities further than range metres from relativeTo will be excluded. If no matching entities are found, an empty array is returned.

See Also: shipsWithPrimaryRole(), shipsWithRole(), filteredEntities().

filteredEntities

function filteredEntities(this : Object, predicate : Function [, relativeTo : Entity [, range : Number]]) : Array

A list of the entities for which predicate returns true. If relativeTo is specified, the list will be sorted in order of proximity to relativeTo (i.e., the first element of the list is closest). If range is also specified, entities further than range metres from relativeTo will be excluded. If no matching entities are found, an empty array is returned.

Example: 

this.findIdlePoliceInScannerRange = function()
{
    function $isIdlePolice(entity)
    {
        return entity.isShip && entity.isPolice && !entity.target
    }
  
    return system.filteredEntities(this, $isIdlePolice, player.ship, 25600);
}

See Also: shipsWithPrimaryRole(), shipsWithRole(), entitiesWithScanClass().

legacy_addShips etc.

function legacy_addShips(role : String, count : Number)
function legacy_addSystemShips(role : String, count : Number, position : Number)
function legacy_addShipsAt(role : String, count : Number, coordscheme : String, where : vectorExpression)
function legacy_addShipsAtPrecisely(role : String, count : Number, coordscheme : String, where : Planet)
function legacy_addShipsWithinRadius(role : String, count : Number, coordScheme : String, where : Planet, radius : Number)
function legacy_spawnShip(shipDataKey : String)

Various ways of causing ships to appear. Each of these corresponds to a legacy scripting method. For more info about the coordScheme, look at Oolite coordinate systems. These methods are kept for backwards-compatibility; for new development, addShips() is preferred.

Important: legacy_spawn, previously listed here, never worked as intended and has been replaced with Ship.spawn().

locationFromCode

This method was added in Oolite test release 1.79. 

locationFromCode(code) : Vector

Returns a random location in the region specified by the code string. The code strings are the same as used by the Oolite populator

scrambledPseudoRandomNumber

function scrambledPseudoRandomNumber(salt : Number (integer)) : Number

Returns a number that’s greater than or equal to zero and less than one. It will always return the same value for a given salt value and system. Crucially, the relationship between systems and numbers is effectively completely different for each salt value, so scripts making similar decisions based on scrambledPseudoRandomNumber() but using different salts will get uncorrelated results. For example, if two different OXPs add a certain type of station to 25% of systems using if (system.pseudoRandomNumber < 0.25), the two station types will always be found in the same system; using scrambledPseudoRandomNumber() with different salts avoids this.

sendAllShipsAway

function sendAllShipsAway()

Makes all ships hyperspace out of the system.

setPopulator

This method was added in Oolite test release 1.79. 

setPopulator(key : String, definition : Object)

Sets the populator settings for the specified key to the given definition, or deletes them if the definition is null. Calling this outside of the system population set up is possible but useless. See the populator settings page for more information on the format of the definition object.

See Also: populatorSettings

setWaypoint

This method was added in Oolite test release 1.79. 

setWaypoint(key : String, position : VectorExpression, orientation : QuaternionExpression, parameters : Object)

Adds a waypoint to the system with the given key, placed at the specified position and orientation. parameter is an object with the following optional keys:

  • size: the radius of the waypoint in metres
  • beaconCode: the beacon code (default "W")
  • beaconLabel: the beacon label (default "Waypoint")

Waypoints will be visible only when the player has a working Advanced Space Compass. 

setWaypoint(key : String)

Removes the waypoint with the specified key, if it exists.

In Oolite 1.81, waypoints can either be oriented (the 1.80 default) or unoriented. Unoriented waypoints do not display the directional arrows. To create an unoriented waypoint, set its orientation to the zero quaternion (0,0,0,0) either on creation or later.

See Also: waypoints

shipsWithPrimaryRole

function shipsWithPrimaryRole(role : String [, relativeTo : Entity [, range : Number]]) : Array

A list of the entities in the system whose primary role is role. If relativeTo is specified, the list will be sorted in order of proximity to relativeTo (i.e., the first element of the list is closest). If range is also specified, entities further than range metres from relativeTo will be excluded. If no matching entities are found, an empty array is returned.

See Also: shipsWithRole(), entitiesWithScanClass(), filteredEntities().

shipsWithRole

function shipsWithRole(role : String [, relativeTo : Entity [, range : Number]]) : Array

A list of the entities in the system whose role set contains role. If relativeTo is specified, the list will be sorted in order of proximity to relativeTo (i.e., the first element of the list is closest). If range is also specified, entities further than range metres from relativeTo will be excluded. If no matching entities are found, an empty array is returned.

See Also: shipsWithRole(), entitiesWithScanClass(), filteredEntities().


Static Methods

infoForSystem

function infoForSystem(galaxyNumber: Integer, systemID : Integer) (write-only)

Overwrites existing info of the given system. As properties it uses the planetinfo.plist keys. e.g. 

System.infoForSystem(0, 55).description = "This is a dull planet."

sets the description of planet nr 55 in galaxy 0 to "This is a dull planet."

Starting from Oolite 1.73, all system Info for the present galaxy is also readable. Even though any galaxy system info property is fully settable, due to engine limitations other galaxies' data is not accessible. In other words 

System.infoForSystem(0, 55).description

would return "This is a dull planet." if called from galaxy 0, and throw an exception if called from the other galaxies.

Of particular note the spelling of the techlevel property when using the infoForSystem function to extract it. While the property of system.techLevel is spelt using camelCase, System.infoForSystem(0, 55).techlevel is using all lower case. This is because planetinfo.plist has always had the techlevel key spelt this way.

systemIDForName

function systemIDForName(systemName : String) : Integer

Returns the ID number of a system in the current galaxy based on the system name.

Note: in galaxy 8, there are two systems named “Inzaan”. systemIDForName() will return the lower ID, which is 22.

systemNameForID

function systemNameForID(systemID : Integer) : String

Returns the name of a system in the current galaxy based on the given ID number.

Retrieved from "http://backup.witchspacewiki.org/index.php?title=Oolite_JavaScript_Reference:_System&oldid=66794"