Difference between revisions of "Oolite JavaScript Reference: SystemInfo"

From Elite Wiki
(Methods: samplePrice)
(Added note on "system.info.sun_color")
(9 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
<small>'''Prototype:''' <code>Object</code></small><br />
 
<small>'''Prototype:''' <code>Object</code></small><br />
  
'''<code>SystemInfo</code>''' objects provide information about a specific system. <code>SystemInfo</code>s can be retrieved for any system in the current galaxy, but not systems in other galaxies. If you keep a reference to a <code>SystemInfo</code> object after the player goes to a different galaxy, attempts to read properties of the stored <code>SystemInfo</code> will cause an exception.
+
'''<code>SystemInfo</code>''' objects provide information about a specific star system. <code>SystemInfo</code>s can be retrieved for any system in any galaxy as of version 1.82. In previous versions, only systems for the current galaxy could be read.
  
 
In interstellar space, <code>system.info</code> refers to a temporary <code>SystemInfo</code> object whose properties cannot be written to. Attempting to read properties of such a temporary <code>SystemInfo</code> after leaving interstellar space will raise an exception.
 
In interstellar space, <code>system.info</code> refers to a temporary <code>SystemInfo</code> object whose properties cannot be written to. Attempting to read properties of such a temporary <code>SystemInfo</code> after leaving interstellar space will raise an exception.
Line 19: Line 19:
 
  '''galaxyID''' : Number (read-only nonnegative integer)
 
  '''galaxyID''' : Number (read-only nonnegative integer)
 
The ID number of the galaxy.
 
The ID number of the galaxy.
 +
 +
'''See also''': <code>[[Oolite JavaScript Reference: Global#galaxyNumber|galaxyNumber]]</code>
  
 
=== <code>internalCoordinates</code> ===
 
=== <code>internalCoordinates</code> ===
Line 61: Line 63:
 
  530.40 (travelled time)
 
  530.40 (travelled time)
  
Warning: in version 1.76 or earlier there is a bug in this method which may cause a crash if either the start or end of the route is in interstellar space (i.e. system ID -1). In later versions this simply returns null.
+
Warning: in version 1.76 or earlier there is a bug in this method which may cause a crash if either the start or end of the route is in interstellar space (i.e. system ID -1). In later versions this simply returns <code>null</code>.
  
 
=== <code>samplePrice</code> ===
 
=== <code>samplePrice</code> ===
 
{{oolite-method-added|1.81}}
 
{{oolite-method-added|1.81}}
 
  function '''samplePrice'''(commodity : String) : Array
 
  function '''samplePrice'''(commodity : String) : Array
Return a sample main market price in decicredits for the commodity with that key in this system. As this requires reading system information, it will only work for systems in the current galaxy. There is of course no guarantee that the price returned by this function will be anywhere near the actual price when the system is next entered.
+
Return a sample main market price in decicredits for the commodity with that key in this system. As this requires reading system information, it will only work for systems in the current galaxy. There is of course no guarantee that the price returned by this method will be anywhere near the actual price when the system is next entered.
 +
 
 +
=== <code>setProperty</code> ===
 +
{{oolite-method-added|1.81}}
 +
function '''setProperty'''(layer: Number, key : String, value: String [, manifest: String])
 +
 
 +
This lets you set properties with more control than provided by writing directly to <code>systemInfo.property</code>. <code>layer</code> is the layer from 0 to 3 that the change should be applied at, as in [[planetinfo.plist]]. Layer 2 is the default layer for Javascript-initiated changes, but 3 may be used for changes absolutely crucial for OXP functionality.
 +
 
 +
It is also possible to make changes on behalf of a different OXP by passing the manifest ID of that OXP as the fourth parameter. Otherwise the OXP responsible for the current script execution context will be used.
  
 
=== <code>systemsInRange</code> ===
 
=== <code>systemsInRange</code> ===
Line 96: Line 106:
 
     });  
 
     });  
 
  }
 
  }
 +
 +
=== <code>setInterstellarProperty</code> ===
 +
{{oolite-method-added|1.81}}
 +
function '''setInterstellarProperty'''(galaxy : Number, fromsystem : Number, tosystem : Number, layer: Number, key : String, value: String, [, manifest: String])
 +
 +
This is similar to [[#setProperty|setProperty]] but for setting properties of interstellar space regions. Changes made to the current interstellar space region will only take effect if the player leaves and returns.
 +
 +
Note that the order of fromsystem (the last real system visited) and tosystem (the target of the latest jump) is significant - 0,7,55 is Lave to Leesti; 0,55,7 is Leesti to Lave. In many cases setting the same change for both directions may be necessary.
 +
 +
== <code>system.info.sun_color</code> ==
 +
I'm just a dumb pilot, but the 2018 posts [http://aegidian.org/bb/viewtopic.php?p=265497#p265497 here] state that this is a way of changing the sun's colour.
 +
''Eg'':
 +
 +
system.info.sun_color="1.0 0.6 0.3"
 +
system.info.sun_color="50 38 185"
 +
system.info.sun_color="yellowColor"
 +
 +
for RGB, HSB and named colours
  
 
[[Category:Oolite JavaScript Reference]]
 
[[Category:Oolite JavaScript Reference]]

Revision as of 17:54, 7 March 2023

Prototype: Object

SystemInfo objects provide information about a specific star system. SystemInfos can be retrieved for any system in any galaxy as of version 1.82. In previous versions, only systems for the current galaxy could be read.

In interstellar space, system.info refers to a temporary SystemInfo object whose properties cannot be written to. Attempting to read properties of such a temporary SystemInfo after leaving interstellar space will raise an exception.

Properties

coordinates

coordinates : Vector3D (read-only)

The coordinates of the system in light years. e.g. for Lave: (8, 34.6, 0). The z component is always zero.

The upper left corner has the coordinate (0, 0, 0). Going right increases the x value while going down on the map increases the y value.

Example:

System.infoForSystem(galaxyNumber, 7).coordinates

returns the coordinates of the system with an ID number of 7 in the current galaxy. In the first galaxy that would be the coordinates for Lave: (8, 34.6, 0).

galaxyID

galaxyID : Number (read-only nonnegative integer)

The ID number of the galaxy.

See also: galaxyNumber

internalCoordinates

internalCoordinates : Vector3D (read-only)

Discouraged in favour of coordinates.
The coordinate of the system in the internal coordinate system.

systemID

systemID : Number (read-only nonnegative integer)

The ID number of the system.

More properties

In addition to the properties above, you can access many other system properties, using the same keys as planetinfo.plist.

Example:

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

sets the description of the current planet to “This is a dull planet.”

Modified properties are permanent and are stored in saved game. Changes made by scripts override those in planetinfo.plist. Set a property to null to restore the planetinfo.plist value, or the default.

Methods

distanceToSystem

function distanceToSystem(system : SystemInfo) : Number

Returns the distance in light years to another SystemInfo.

Example:

System.infoForSystem(galaxyNumber, 7).distanceToSystem(System.infoForSystem(galaxyNumber, 8))

If galaxyNumber is 0, this returns 92.8.

routeToSystem

function routeToSystem(system : SystemInfo [, "OPTIMIZED_BY_JUMPS" | "OPTIMIZED_BY_TIME"] ) : Object

Returns a dictionary containing the route information to another SystemInfo. The dictionary contains the array of system IDs that belong to the route found, the distance and the time corresponding to said route. Takes the optional parameter "OPTIMIZED_BY_JUMPS" (default) or "OPTIMIZED_BY_TIME" to calculate least number of jumps or fastest transit time routes respectively.

Example:

var myRoute = System.infoForSystem(galaxyNumber, 7).routeToSystem(System.infoForSystem(galaxyNumber, 8))
myRoute.route
myRoute.distance
myRoute.time

returns:

7,129,227,73,89,222,29,42,131,62,150,36,28,16,185,86,138,51,8  (the route)
96.40  (distance of added jumps)
530.40 (travelled time)

Warning: in version 1.76 or earlier there is a bug in this method which may cause a crash if either the start or end of the route is in interstellar space (i.e. system ID -1). In later versions this simply returns null.

samplePrice

This method was added in Oolite test release 1.81.

function samplePrice(commodity : String) : Array

Return a sample main market price in decicredits for the commodity with that key in this system. As this requires reading system information, it will only work for systems in the current galaxy. There is of course no guarantee that the price returned by this method will be anywhere near the actual price when the system is next entered.

setProperty

This method was added in Oolite test release 1.81.

function setProperty(layer: Number, key : String, value: String [, manifest: String])

This lets you set properties with more control than provided by writing directly to systemInfo.property. layer is the layer from 0 to 3 that the change should be applied at, as in planetinfo.plist. Layer 2 is the default layer for Javascript-initiated changes, but 3 may be used for changes absolutely crucial for OXP functionality.

It is also possible to make changes on behalf of a different OXP by passing the manifest ID of that OXP as the fourth parameter. Otherwise the OXP responsible for the current script execution context will be used.

systemsInRange

function systemsInRange([range : Number]) : Array

Returns an array of SystemInfos in range (default: 7) from the given system.

Note: will not produce correct results if used in interstellar space.

Example:

system.info.systemsInRange(5);

Static methods

filteredSystems

function filteredSystems(this : Object, predicate : Function) : Array of SystemInfo

A list of the SystemInfos for which predicate returns true.

Example:

// This is the actual implementation of systemsInRange().
SystemInfo.prototype.systemsInRange = function systemsInRange(range) 
{ 
   if (range === undefined) 
   { 
       range = 7; 
   } 
   
   return SystemInfo.filteredSystems(this, function(other) 
   { 
       return (other.systemID !== this.systemID) && (this.distanceToSystem(other) <= range); 
   }); 
}

setInterstellarProperty

This method was added in Oolite test release 1.81.

function setInterstellarProperty(galaxy : Number, fromsystem : Number, tosystem : Number, layer: Number, key : String, value: String, [, manifest: String])

This is similar to setProperty but for setting properties of interstellar space regions. Changes made to the current interstellar space region will only take effect if the player leaves and returns.

Note that the order of fromsystem (the last real system visited) and tosystem (the target of the latest jump) is significant - 0,7,55 is Lave to Leesti; 0,55,7 is Leesti to Lave. In many cases setting the same change for both directions may be necessary.

system.info.sun_color

I'm just a dumb pilot, but the 2018 posts here state that this is a way of changing the sun's colour. Eg:

system.info.sun_color="1.0 0.6 0.3" 
system.info.sun_color="50 38 185" 
system.info.sun_color="yellowColor" 

for RGB, HSB and named colours