Difference between revisions of "Oolite JavaScript Reference: SystemInfo"

From Elite Wiki
(Special Witchspace Location)
Line 98: Line 98:
 
== Special Witchspace Location ==
 
== Special Witchspace Location ==
   
In order to access information about witchspace locations - ones the player can only reach via a misjump, the short form for the local SystemInfo (system.info) will access a special, generic witchspace location, one that always return data for the ''current'' witchspace location, or null values if the player is not in witchspace.
+
In order to access information about the current witchspace location while in witchspace itself - an in-between systems location, one that the player can only reach via a misjump - the short form for the local SystemInfo (system.info) will access a special, generic witchspace location, one that always return data for the ''current'' witchspace position, or null values if the player is not in witchspace.
   
In practice, the witchspace SystemInfo works like all others, with the exception that you cannot store the whole witchspace systemInfo inside a single convenience variable for later use, and that you cannot change specific values to apply to witchspace. For example:
+
In practice, the witchspace SystemInfo works like all others, with the exception that you cannot store the whole witchspace systemInfo inside a single convenience variable for later use, and that you cannot change specific values to apply to witchspace. As an example, trying to set a value for the local witchspace 'system':
   
 
system.info.economy = 5;
 
system.info.economy = 5;
   
will be ignored in witchspace.
+
will simply be ignored while in witchspace.
   
 
[[Category:Oolite JavaScript Reference]]
 
[[Category:Oolite JavaScript Reference]]

Revision as of 02:06, 26 July 2010

Prototype: Object

This class was added in Oolite test release 1.74.

SystemInfo objects provide information about a specific system.

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.

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.”

Properties that are changed in system.info are stored in the save file and are permanently changed for that commander. When both the planetInfo.plist and the data from a changed system.info file are present, those of the system.info are used. You can undo any changes in system.info by setting the value to null.

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)

systemsInRange

This method was added in Oolite test release 1.74.2.

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.

See also: SystemInfo.systemsInRange() (which always provides results relative to the current system).

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() in Oolite 1.74.
SystemInfo.systemsInRange = function(range) 
{ 
   if (range === undefined) 
   { 
       range = 7; 
   } 
   
   var thisSystem = system.info; 
   return SystemInfo.filteredSystems(this, function(other) 
   { 
       return (other.systemID !== thisSystem.systemID) && (thisSystem.distanceToSystem(other) <= range); 
   }); 
}

systemsInRange

function systemsInRange([range : Number]) : Array

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

Note: As of 1.74.2, this method works correctly for all systemInfos in the current galaxy, and for the current witchspace location. Trying to use it for other galaxies - or for a non-current witchspace location - will produce an error.

Example:

system.info.systemsInRange(5);

Special Witchspace Location

In order to access information about the current witchspace location while in witchspace itself - an in-between systems location, one that the player can only reach via a misjump - the short form for the local SystemInfo (system.info) will access a special, generic witchspace location, one that always return data for the current witchspace position, or null values if the player is not in witchspace.

In practice, the witchspace SystemInfo works like all others, with the exception that you cannot store the whole witchspace systemInfo inside a single convenience variable for later use, and that you cannot change specific values to apply to witchspace. As an example, trying to set a value for the local witchspace 'system':

system.info.economy = 5;

will simply be ignored while in witchspace.