Oolite JavaScript Reference: Station

Prototype: Ship
Subtypes: none

The Station class is an Entity representing a station or carrier (i.e., a ship with a docking port). A Station has all the properties and methods of a Ship, and some others.

Properties

alertCondition

alertCondition : Number (read/write, integer)

Returns the current alert condition. 1 = Green, 2 = Yellow, 3 = Red.

See also: alertConditionChanged

allegiance

This property was added in Oolite test release 1.79.

allegiance : String (read/write)

A string which provides a hint to the AI about the likely response to approaching this station. The following values are recognised by the standard AIs in 1.79

• "hunter": this station is friendly to bounty hunters and hostile to offenders and fugitives
• "galcop": this is the main station or one with similar behaviour
• "neutral": pirates and criminals will not dock here, but may hang around outside safely. Everyone else may dock
• "pirate": pirates and criminals can dock here, while others may get a hostile response
• "chaotic": anyone will be allowed to dock here
• "thargoid": this station is controlled by the Thargoids and is hostile to all Cooperative ships
• "private": this station will refuse docking except to specifically authorised ships. Core Oolite AIs will assume that any station with an unrecognised allegiance is equivalent to "private".
• "restricted": this station will refuse docking to and probably fire upon all unauthorised ships

Stations without an allegiance specified when they are created will have a guess made dependent on their legal status, armament and scan class.

allowsAutoDocking

allowsAutoDocking : Boolean (read/write)

If the player's ship has a docking computer and this property is true, the player can dock with the station (assuming it isn’t hostile) by pressing the autopilot key (default c) or via the engageAutopilotToStation method. The corresponding shipdata.plist key is allows_auto_docking (default: true).

allowsFastDocking

allowsFastDocking : Boolean (read/write)

If the player's ship has a docking computer and this property is true, the player can instantaneously dock with the station (assuming it isn’t hostile) by pressing the fast-dock key (default shift-C). This property does not affect the dockPlayer method. The corresponding shipdata.plist key is allows_fast_docking (default: false, but set to true when setting up the main station).

breakPattern

This property was added in Oolite test release 1.77.

breakPattern : Boolean (read/write)

If true (the default state), the break pattern defined in shipdata.plist will be shown when launching or docking.

dockedContractors

dockedContractors : Number (read-only, integer)

Returns the number of docked contractors ships that can launch as miner or scavenger.
There is only one counter for miners and scavengers. The maximum that can launch as miner/scavenger is determined by the shipdata-key max_scavengers. However, miners can only launch when there is no other miner in the stations scanner range, even when contractor ships are docked.

dockedDefenders

dockedDefenders : Number (read-only, integer)

Returns the number of docked defence ships that can launch as defence ships.
There is only one counter for defence and police ships. However, the maximum that can launch as defenders is determined by the shipdata-key max_defense_ships.

dockedPolice

dockedPolice : Number (read-only, integer)

Returns the number of docked defence ships that can launch as police or patrol ships.
There is only one counter for defence and police ships. However, the maximum that can launch as police/patrol is determined by the shipdata-key max_police.

equipmentPriceFactor

equipmentPriceFactor : Number (read-only, float)

Returns the equipment_price_factor for the station as defined in shipdata.plist.

equivalentTechLevel

equivalentTechLevel : Number (read-only, Integer)

Returns the equivalent_tech_level for the station as defined in shipdata.plist.

hasNPCTraffic

hasNPCTraffic : Boolean (read/write)

If true, the station has associated non-player traffic, such as shuttles, patrol ships and scavengers. Corresponds to the has_npc_traffic shipdata.plist key.

hasShipyard

This property was added in Oolite test release 1.77.

hasShipyard : Boolean (read-only)

If true, the station has a shipyard where the player may trade in their ship. Corresponds to the has_shipyard shipdata.plist key.

See also: shipyard

isMainStation

isMainStation : Boolean (read-only)

true if the station is the main station of the system, false otherwise.

See also: system.mainStation

market

This property was added in Oolite test release 1.77.

market : Object (read-only)

An object with one property for each commodity in the game. Each property has a read-only object as its value, reflecting the commodities.plist entry for this station, and the current market state. For example:

computers: {
       marketMaskPrice: "3",
       marketEcoAdjustPrice: "14",
       price: 900,
       quantityUnit: "0",
       marketMaskQuantity: "3",
       marketBaseQuantity: "56",
       marketEcoAdjustQuantity: "14",
       marketBasePrice: "154",
       quantity: 0,
       displayName: "Computers"
}

price is measured in decicredits, and quantity in the units determined by quantityUnit.

In 1.79 or later there is also a "legalPenalty" entry describing the export bounty applied per unit for this cargo at main stations.

In 1.81 or later the format of this object's properties changes to the following, and the number of properties on the object reflects the contents of trade-goods.plist rather than commodities.plist

{
    quantity_random: "0.04",
    key: "food",
    trumble_opinion: "1.0",
    quantity: 16,
    quantity_average: "13.5",
    classes: ["oolite-consumer", "oolite-edible", "oolite-farming"],
    price_random: "0.04",
    quantity_unit: "0",
    price_economic: "0.55",
    peak_export: "7",
    legality_import: "0",
    name: "[commodity-name food]",
    sort_order: "100",
    peak_import: "0",
    legality_export: "0",
    quantity_economic: "0.52",
    price_average: "50",
    price: 38
}

See also: setMarketPrice(), setMarketQuantity()

requiresDockingClearance

requiresDockingClearance : Boolean (read/write)

true if the station requires docking clearance, false otherwise.

roll

This property was added in Oolite test release 1.77.

roll : Number (read/write)

The rate of roll of the station in radians/second (positive for anti-clockwise, negative for clockwise)

For stations, this can be set to any value between -2 and +2 to adjust their roll rate. The default is 0.4, or the value specified by the station_roll key in shipdata.plist. (Note that the station_roll property is for historical reasons in right-angles/second, not radians/second, so the reported value of station.roll will not be numerically equal to the shipdata.plist station_roll property)

shipyard

This property was added in Oolite test release 1.89.

shipyard : Array (read-only)

An array of shipyard ship dictionaries that defines all the ships currently for sale at the station. Returns null if the station has no shipyard.

Each element of the array contains a shipyard ship dictionary item similar to the following:

{
   short_description: "Python: Plus Galactic Hyperdrive. Extra Energy Unit. Docking Computers. E.C.M. System. Forward weapon upgraded to military laser. Price 215 000 ₢.",
   shipdata_key: "python-player",
   id: "675b6b-c60a74",
   price: 215000,
   ship: {
     ...shipdata.plist details of ship...
   },
   personality: 9807,
   extras: ["EQ_GAL_DRIVE", "EQ_FUEL_SCOOPS", "EQ_ENERGY_UNIT", "EQ_FUEL_INJECTION", "EQ_DOCK_COMP", "EQ_ECM"]
}

Example:

var ship_count = system.mainStation.shipyard.length;
var key = system.mainStation.shipyard[0].shipdata_key;

Note: The shipyard is a zero-based array. So, if station.shipyard.length is 10 (meaning there are 10 items in the array), then the shipIndex value for the first item is 0, and the shipIndex for the last item is 9.

See also: hasShipyard, addShipToShipyard(), removeShipFromShipyard()

suppressArrivalReports

suppressArrivalReports : Boolean (read/write)

If set to true, arrival reports are not shown when the player docks with the station.

See also: player.addMessageToArrivalReport, Arrival Reports (2012)

Methods

abortAllDockings

This method was added in Oolite test release 1.79.

function abortAllDockings()

Removes docking clearance from all ships currently waiting to dock. Their AIs will receive a message.

abortDockingForShip

This method was added in Oolite test release 1.79.

function abortDockingForShip(ship)

Removes docking clearance from the specified ship if it is currently waiting to dock.

addShipToShipyard

This method was added in Oolite test release 1.89.

function addShipToShipyard(dictionary)

Adds a shipyard dictionary entry for a new ship to the shipyard of the station.

Example:

system.mainStation.addShipToShipyard({ 
   short_description: "Cobra Mark I: With fuel injectors and galactic hyperdrive.", 
   shipdata_key:"cobramk1-player", 
   price:120000, 
   personality:Math.floor(Math.random() * 32768), 
   extras:["EQ_FUEL_INJECTION","EQ_GAL_DRIVE"]
});

Notes:

• The shipdata_key must exist in a shipdata.plist file, which must be defined with a "player" role, and must have an equivalent entry in a shipyard.plist file.
• If personality is not provided, it will default to 0 (zero).
• extras is an array of equipment items that will be added to the ship upon purchase. Lasers (eg "EQ_WEAPON_BEAM_LASER") can be specified in this list. The laser will be compared to the default front laser that comes with the ship, and if it's better it will be installed in that position. If not, it will be installed in the aft position.

See also: shipyard, removeShipFromShipyard()

canDockShip

This method was added in Oolite test release 1.85.

function canDockShip(shipEntity) : Boolean 

Returns true if the station can dock the ship entity passed as parameter (the ship fit into the dock), otherwise returns false.

dockPlayer

function dockPlayer() : Boolean 

This method docks the player at the specified station. Returns false if docking fails, otherwise true. The station's allows_fast_docking/allowsFastDocking property does not affect this method.

launchDefenseShip

function launchDefenseShip() : Ship 

This method adds a ship with a role defined in the ship key "defense_ship_role" or a specific ship defined with a ship key "defense_ship", to the launching queue at the specified station. When no defense ships are defined it selects one from the police or interceptors. All ships launch with a primary role of "defense_ship". Returns the entity of the chosen ship. This method aborts all dockings for an immediate launch.

launchEscort

This method was added in Oolite test release 1.79.

function launchEscort() : Ship 

This method adds a ship with an "escort" role to the launching queue, and returns the ship. This ship is not an escort of the station itself - it will need to find a suitable mothership to escort once launched.

launchMiner

function launchMiner() : Ship 

This method adds a ship with a miner role to the launching queue at the specified station. Launches only a miner when there is a contractor ship at the station and when the number of miners around the station is zero. (there can only be one!) Returns the entity of the chosen ship.

launchPatrol

function launchPatrol() : Ship 

This method adds a ship with a police role and planetPatrolAI.plist to the launching queue at the specified station. Returns the entity of the chosen ship.

launchPirateShip

function launchPirateShip() : Ship 

This method adds a ship with a pirate role to the launching queue at the specified station. All ships launch with a primary role of "defense_ship" and pirateAI.plist. These pirate ships are counted as defense_ship. Returns the entity of the chosen ship.

launchPolice

function launchPolice() : Array 

This method adds up to 4 police ships to the launching queue at the specified station. Returns an array of chosen police ships. Depending on the system it selects ships with role police or interceptor, but on launch all primary roles will be police
It will only launch a ship if the station has a target and there are police ships left. This method aborts all dockings for an immediate launch.

launchScavenger

function launchScavenger() : Ship 

This method adds a ship with a scavenger role to the launching queue at the specified station. Launches only a scavenger when there is a contractor ship at the station and when the number of scavengers around the station is less than the maximum number of scavengers. Returns the entity of the chosen ship.

launchShipWithRole

function launchShipWithRole(role : String, [abortAllDockings : Boolean]) : Ship 

This method adds a ship with given role to the launching queue at the specified station. Returns the entity of the chosen ship.
When abortAllDockings is true (default: false), all ships in the docking process get an abort message and launching of ships starts immediately. Don't use this parameter when not strictly necessary for your launching ship.

launchShuttle

function launchShuttle() : Ship 

This method adds a ship with a shuttle role to the launching queue at the specified station. Returns the entity of the chosen ship.

removeShipFromShipyard

function removeShipFromShipyard(shipIndex: Integer)

This method removes the selected index from the station.shipyard array, removing that ship from sale.
Note: The shipyard is a zero-based array. So, if station.shipyard.length is 10 (meaning there are 10 items in the array), then the shipIndex value for the first item is 0, and the shipIndex for the last item is 9.

See also: shipyard, addShipToShipyard()

setInterface

This method was added in Oolite test release 1.77.

function setInterface(key : String, interfaceDefinition : Object)

This method sets the station interface (F4 screen) definition for the specified key (or removes that definition, if the interfaceDefinition is null). interfaceDefinition objects have the following required properties:

• title: (short) String: the title displayed in the interface list.
• category: (short) String: the category displayed and used to sort the interface list.
• summary: String: the summary text displayed below the interface list when this interface is selected.
• callback: Function: the function that will be called when this interface is activated. This callback can safely and generally will call mission.runScreen. The callback function will be passed the interface key as a parameter, so you can use the same callback for multiple interface entries if necessary.

and the following optional properties:

• cbThis: Script: the script that will act as 'this' when the callback runs. This can be omitted if you use the bind method.

As the key must be unique, it is strongly recommended to prefix it with an OXP-specific string.

For example:

station.setInterface("my-oxp-example1",{
  title: "Example title",
  category: "Examples",
  summary: "This is an example interface definition. Further information is available.",
  callback: this._furtherExampleInformation.bind(this)
});

or

// the player has accepted the mission, so remove the interface
station.setInterface("my-oxp-example2",null);

setMarketPrice

This method was added in Oolite test release 1.77.

function setMarketPrice(commodity : String, price : Number)

Sets the price of the specified commodity in the local station market to the given value. The price is in decicredits and must be between 0 and 1020 decicredits. For example:

station.setMarketPrice("food",38);
// this sets the unit-price of food to 3.8 credits

See also: market, setMarketQuantity()

setMarketQuantity

This method was added in Oolite test release 1.77.

function setMarketQuantity(commodity : String, quantity : Number)

Sets the quantity of the specified commodity in the local station market to the given value. The quantity is in units and must be between 0 and 127 units. For example:

station.setMarketQuantity("machinery",15);

See also: market, setMarketPrice()

Links

• Station Ships
• OXP howto dockable stations
• How do I to add an image to a station? (2010)