Difference between revisions of "Oolite JavaScript Reference: System"

From Elite Wiki
(→‎Properties: Added mainStation.)
(Updated formatting. Added properties and methods for finding entities.)
Line 9: Line 9:
   
 
== Properties ==
  
== Properties ==
  +
=== <code>allShips</code> ===
  +
'''allShips''' : Array (read-only)
  +
A list of the ships in the system. If there are none, an empty list.
  +
  +
'''See Also:''' <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.
  +
 
=== <code>description</code> ===
  
=== <code>description</code> ===
−
description [read/write string]
 +
'''description''' : String (read/write)
 
The description of the current system, as seen on the planet info screen.
  
The description of the current system, as seen on the planet info screen.
   
 
=== <code>economy</code> ===
  
=== <code>economy</code> ===
−
economy [read/write int]
 +
'''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 [read-only string]
 +
'''economyDescription''' : String (read-only)
 
A description of the economy type, for example, “Mostly Industrial”. (See also: <code>[[#economy|economy]]</code>)
  
A description of the economy type, for example, “Mostly Industrial”. (See also: <code>[[#economy|economy]]</code>)
−  
−
=== <code>ID</code> ===
  
−
ID [read-only integer]
  
−
A number identifying the system. 0 to 255, or -1 for interstellar space. Equivalent to <code>planet_number</code> in plist scripts.
  
−  
−
=== <code>inhabitantsDescription</code> ===
  
−
inhabitantsDescription [read/write string]
  
−
The description of the inhabitants of the current system, such as “Slimy Blue Frogs”.
  
−  
−
=== <code>isInterstellarSpace</code> ===
  
−
isInterstellarSpace [read-only boolean]
  
−
<code>true</code> if the current system is in interstellar space, <code>false</code> otherwise.
  
   
 
=== <code>goingNova</code> ===
  
=== <code>goingNova</code> ===
−
goingNova [read-only boolean]
 +
'''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>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> ===
  
=== <code>goneNova</code> ===
−
goneNova [read-only boolean]
 +
'''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>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 [read/write int]
 +
'''government''' : Number (integer, read/write)
 
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 [read-only string]
 +
'''governmentDescription''' : String (read-only)
 
A description of the government type, for example, “Democracy”. (See also: <code>[[#government|government]]</code>)
  
A description of the government type, for example, “Democracy”. (See also: <code>[[#government|government]]</code>)
  +
  +
=== <code>ID</code> ===
  +
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.
   
 
=== <code>inhabitantsDescription</code> ===
  
=== <code>inhabitantsDescription</code> ===
−
inhabitantsDescription [read/write string]
 +
'''inhabitantsDescription''' : String (read/write)
 
The description of the inhabitants of the current system, such as “Slimy Blue Frogs”.
  
The description of the inhabitants of the current system, such as “Slimy Blue Frogs”.
  +
  +
=== <code>isInterstellarSpace</code> ===
  +
'''isInterstellarSpace''' : Boolean (read-only)
  +
<code>true</code> if the current system is in interstellar space, <code>false</code> otherwise.
  +
  +
=== <code>mainPlanet</code> ===
  +
'''mainPlanet''' : [[Oolite/Development/Scripting/Class/Planet|Planet]] (read-only)
  +
The system’s main planet, or <code>null</code> if there is none.
   
 
=== <code>mainStation</code> ===
  
=== <code>mainStation</code> ===
−
mainStation [read-only [[Oolite/Development/Scripting/Class/Station|Station]]]
 +
'''mainStation''' : [[Oolite/Development/Scripting/Class/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>planets</code> ===
  +
'''planets''' : Array (read-only)
  +
A list of the planets in the system. If there are none, an empty list.
   
 
=== <code>population</code> ===
  
=== <code>population</code> ===
−
population [read/write int]
 +
'''population''' : Number (integer, read/write)
 
The population of the current system.
  
The population of the current system.
   
 
=== <code>productivity</code> ===
  
=== <code>productivity</code> ===
−
productivity [read/write int]
 +
'''productivity''' : Number (integer, read/write)
 
The productivity of the current system.
  
The productivity of the current system.
  +
  +
=== <code>sun</code> ===
  +
'''sun''' : [[Oolite/Development/Scripting/Class/Planet|Planet]] (read-only)
  +
The system’s sun, or <code>null</code> if there is none.
   
 
=== <code>techLevel</code> ===
  
=== <code>techLevel</code> ===
−
techLevel [read/write int]
 +
'''techLevel''' : Number (integer, read/write)
 
The technology level of the current system, ranging from 0 to 15.
  
The technology level of the current system, ranging from 0 to 15.
  +
   
 
== Methods ==
  
== Methods ==
 
=== <code>addMoon</code> ===
  
=== <code>addMoon</code> ===
−
void addMoon(planetInfoKey)
 +
'''addMoon'''(planetInfoKey : String)
 
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> ===
−
void addPlanet(planetInfoKey)
 +
'''addPlanet'''(planetInfoKey : String)
 
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>countShipsWithRole</code> ===
  
=== <code>countShipsWithRole</code> ===
−
integer countShipsWithRole(role)
 +
'''countShipsWithRole'''(role : String) : Number (integer)
−
Returns the number of ships with the specified role in the system; equivalent to checkForShips: in plist scripts. ('''To do''': <code>array shipsWithRole(role)</code>)
 +
Returns the number of ships with the specified role in the system; equivalent to checkForShips: in plist scripts.
  +
  +
=== <code>entitiesWithScanClass</code> ===
  +
'''entitiesWithScanClass'''(scanClass : String [, relativeTo : [[Oolite/Development/Scripting/Class/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.
  +
  +
'''See Also:''' <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.
  +
  +
=== <code>filteredEntities</code> ===
  +
<div class="boilerplate metadata" style="margin: 0 5%; padding: 0 7px 7px 7px; background: #EDF1F1; border: 1px solid #999999; text-align: left; font-size:95%;">'''This method currently doesn’t work.''' It is intended that it be available in Oolite 1.70, but there are technical problems which may require it to be removed.</div>
  +
'''filteredEntities'''(this : Object, predicate : Function [, relativeTo : [[Oolite/Development/Scripting/Class/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.
  +
  +
'''Example:'''
  +
this.findIdlePoliceInScannerRange = function()
  +
{
  +
function isIdlePolice(entity)
  +
{
  +
return entity.isShip && entity.isPolice && !entity.target
  +
}
  +
  +
return system.filteredEntities(this, isIdlePolice, player, 25600)
  +
}
  +
  +
'''See Also:''' <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>.
   
 
=== <code>legacy_addShips etc.</code> ===
  
=== <code>legacy_addShips etc.</code> ===
−
void legacy_addShips(role, number)
 +
'''legacy_addShips'''(role : String, count : Number)
−
void legacy_addSystemShips(role, number, position)
 +
'''legacy_addSystemShips'''(role : String, count : Number, position : Number)
−
void legacy_addShipsAt(role, number, coordscheme, [[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]])
 +
'''legacy_addShipsAt'''(role : String, count : Number, coordscheme : String, where : [[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]])
−
void legacy_addShipsAtPrecisely(role, number, coordscheme, [[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]])
 +
'''legacy_addShipsAtPrecisely'''(role : String, count : Number, coordscheme : String, where : [[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]])
−
void legacy_addShipsWithinRadius(role, number, coordScheme, [[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]], radius)
 +
'''legacy_addShipsWithinRadius'''(role : String, count : Number, coordScheme : String, where : [[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]], radius : Number)
−
void legacy_spawn(role, number)
 +
'''legacy_spawn'''(role : String, count : Number)
−
void legacy_spawnShip(shipDataKey)
 +
'''legacy_spawnShip'''(shipDataKey : String)
 
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.
  
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.
   
 
=== <code>sendAllShipsAway</code> ===
  
=== <code>sendAllShipsAway</code> ===
−
void sendAllShipsAway()
 +
'''sendAllShipsAway'''()
 
Makes all ships hyperspace out of the system.
  
Makes all ships hyperspace out of the system.
   
 
=== <code>setSunNova</code> ===
  
=== <code>setSunNova</code> ===
−
void setSunNova(secondsUntilNova)
 +
'''setSunNova'''(secondsUntilNova)
 
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]].
  
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]].
  +
  +
=== <code>shipsWithPrimaryRole</code> ===
  +
'''shipsWithPrimaryRole'''(role : String [, relativeTo : [[Oolite/Development/Scripting/Class/Entity|Entity]] [, range : Number]]) : Array
  +
A list of the entities in the system whose [[Oolite/Development/Scripting/Class/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.
  +
  +
'''See Also:''' <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.
  +
  +
=== <code>shipsWithRole</code> ===
  +
'''shipsWithRole'''(role : String [, relativeTo : [[Oolite/Development/Scripting/Class/Entity|Entity]] [, range : Number]]) : Array
  +
A list of the entities in the system whose [[Oolite/Development/Scripting/Class/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>.

Revision as of 16:09, 8 October 2007

Prototype: Object
Subtypes: none

This page documents a planned future Oolite scripting feature. It is presented as a basis for discussion or to help developers organize their thoughts. The functionality presented may end up taking a radically different form, or may not become available at all.

The System class represents the current system. There is always one System object, available through the global propery 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. If there are none, an empty list.

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

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 description of the economy type, for example, “Mostly Industrial”. (See also: economy)

goingNova

goingNova : Boolean (read-only)

true if the system’s sun is in the process of going nova, false otherwise. (To do: this should be a propery of the sun.) (See also: goneNova, setSunNova())

goneNova

goneNova : Boolean (read-only)

true if the system’s sun hase gone nova, false otherwise. (To do: this should be a propery of the sun.) (See also: goingNova, setSunNova())

government

government : Number (integer, read/write)

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 description of the government type, for example, “Democracy”. (See also: government)

ID

ID : Number (integer, read-only)

A number identifying the system. 0 to 255, or -1 for interstellar space. Equivalent to planet_number in plist scripts.

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.

planets

planets : Array (read-only)

A list of the planets in the system. If there are none, an empty list.

population

population : Number (integer, read/write)

The population of the current system.

productivity

productivity : Number (integer, read/write)

The productivity of the current system.

sun

sun : Planet (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.


Methods

addMoon

addMoon(planetInfoKey : String)

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

addPlanet(planetInfoKey : String)

Adds a planet to the system, using the specified entry in planetinfo.plist. (See also: addMoon())

countShipsWithRole

countShipsWithRole(role : String) : Number (integer)

Returns the number of ships with the specified role in the system; equivalent to checkForShips: in plist scripts.

entitiesWithScanClass

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

This method currently doesn’t work. It is intended that it be available in Oolite 1.70, but there are technical problems which may require it to be removed.
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, 25600) 
}

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

legacy_addShips etc.

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

Various ways of causing ships to appear. Each of these corresponds to a legacy scripting method. A new, more flexible addShips() function will supersede all of them.

sendAllShipsAway

sendAllShipsAway()

Makes all ships hyperspace out of the system.

setSunNova

setSunNova(secondsUntilNova)

Sets the system’s sun to go nova after the specified time interval. Time is specified in game real time.

shipsWithPrimaryRole

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

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().

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