Elite Wiki - User contributions [en]

Traffic Control OXP

2021-07-17T03:41:51Z

Milo: added version 2.02

==Overview==
A little script which gives each system main station a traffic control department, whose job it is to guide new Commanders (and a few old hands who have become too reliant on docking computers) on the best route for manual approach and docking into the station. They oversee all traffic from station aegis and planetary approach right up until the actual docking itself. Also they keep an eye on ships leaving the station and wish people a bon voyage. Just don't dally in the approach lane and get in everyone's way, or you'll feel their wrath!

Recommended for new players learning how to dock manually, and for experienced players who want a bit of extra ambience around main stations. It is fully integrated with the docking clearance protocols introduced in Oolite 1.72 (if the stations enable them). Most messages from this OXP will appear only if your ship does not have functional docking computers, but a few will appear regardless, for example: Clear the lane, Commander! If you see a message that starts with 'Traffic Control:' then it is probably from this OXP.

In terms of balance, this OXP is neutral for beginners and slightly biased against the experienced player, because it enforces (with fines and small but escalating bounties) a sensible rule against the use of cloaking devices in proximity to main stations... however, to be fair, it will not impose any penalties if you pass undetected (or at least unidentified). Of course, requesting docking clearance or activating docking computers will transmit your identity to the station...

This OXP is compatible with all other OXPs, and includes considerations for Buoy Repair, ILS and AutoDock if those OXPs are also installed.

==Requirements==
This OXP requires at least version 1.88 of Oolite.

The traffic controllers also assume that any Commander's ship equipped with Docking Computers can look after itself in terms of approach and docking.

==Version History==
<pre>
09/10/2008 - Version 1.00, Initial release.
04/11/2008 - Version 1.01, scripting update for v1.72+ compatibility.
24/05/2010 - Version 1.10, fortified equipment damage checking for 1.74
13/02/2011 - Version 1.11, removal of upper limit, to allow running with 1.75
08/07/2020 - Version 2.00, updated by Milo; set minimum Oolite version to 1.88;
*fixed errors if navigation buoy is destroyed;
*corrected planet approach guidance (follow green circle, not square, if ship has a basic compass);
*added additional hints for new players (until they buy docking computers);
*set up recurring reminders to "clear the lane" when not supposed to be there;
*integrated docking advice with docking clearance protocol for main stations that require clearance;
*added warning messages to fugitive players entering station aegis or requesting docking clearance;
*Cloaking Devices: added responses to being detected using cloaking devices in the station aegis (this OXP now declares it illegal to cloak within main station aegis and introduces a small bounty for the first offence, which will be increased for non-fugitive players each time they are detected still cloaked after the initial offence; however, entering the aegis cloaked and never interacting with the station will not impose a penalty as the traffic controllers are unaware of the trespass); added a 1000 credit fine (or equivalent bounty) to the arrival report when docking at main stations while cloaked (even if fast-docking is used);
*added considerations for nova systems (traffic control will leave a recording when sun has gone nova) and for Buoy Repair, ILS and AutoDock OXPs
07/11/2021 - Version 2.01, updated by Milo; fix bug reported by dybal (docking clearance "granted" status was not correctly detected, resulting in unintended behavior, particularly noticeable when combined with ILS OXP)
07/16/2021 - Version 2.02, updated by Milo; reduced the frequency of some messages, changed one word to be more situationally neutral, and fixed a log warning involving percent symbols; updated license from CC 3.0 to CC 4.0
</pre>

==Download==
The latest version, [[Media:Oolite.oxp.Thargoid.TrafficControl.2.02.oxz|Traffic Control v2.02]], can be downloaded from the wiki by clicking on the link.

An older version, [http://www.box.com/shared/qah2zp7sq2 '''Traffic Control v1.11'''], can be downloaded from Box.Net by clicking on the link.

==Links==
*[[User:Thargoid|Thargoid's OXP page]].
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20180 BB Thread] (2019-20)
*[http://www.aegidian.org/bb/viewtopic.php?p=59662#p59662 Original thread] (2008)

[[File:Tag-colour-blue.png]]{{OXPLevel|0}}
{{mechanics-OXP}}

File:Oolite.oxp.Thargoid.TrafficControl.2.02.oxz

2021-07-17T03:40:29Z

Milo: 07/16/2021 - Version 2.02, updated by Milo; reduced the frequency of some messages, changed one word to be more situationally neutral, and fixed a log warning involving percent symbols; updated license from CC 3.0 to CC 4.0

== Summary ==
07/16/2021 - Version 2.02, updated by Milo; reduced the frequency of some messages, changed one word to be more situationally neutral, and fixed a log warning involving percent symbols; updated license from CC 3.0 to CC 4.0

Space Crowds

2021-07-16T01:00:11Z

Milo: added version history

Adds random encounters in deep space.

== Overview ==
Space Crowds (SC) is basically a heavy modification of Deep Space Pirates. The changes are:
* It is more focused on populating the "long lanes" than guarding the main lanes against "cheaters". SC is triggered by the use of the Torus drive rather than the location,
* It takes into account the base speed of your ship so the number of encounters is roughly function of the distance you travel with the Torus engaged,
* It is less player-centric: it doesn't increase the number of ships spawn depending on your kills, and it spawns equally pirates, hunters, police, traders and very rarely Thargoids ships.

Based on and inspired from [[User:Eric Walch|Eric Walch]]'s [[DeepSpacePirates|Deep Space Pirates]]. Should work with it, but they overlap in functionality. Configurable with [[User:Svengali|Svengali]]'s [[Library]].

== License ==
*CC-BY-NC-SA 4.0
*Author: [[User:Astrobe|Astrobe]]
*Version 1.2.0

== Links ==
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=19053 BB Thread]] (2017+)
*[[Stellar Serpents OXP|Space Crowds - Stellar Serpent]]

== Version History ==
*Version 1.2.0 - switch from visibility criteria to distance criteria to decide if a spawned ship should be removed - two options to however preserve asteroids and derelicts contributed by Dybal.
*Version 1.1.0 - contributed by phkb
*Version 1.0.0 - initial release

== Gameplay and Balance Indicator ==
[[File:Tag-colour-green.png|right]]
Good things and bad things usually end up balancing each other out.

{{Activity-OXP}}

File:SpaceCrowds 1.1.oxz

2021-07-16T00:56:54Z

Milo:

Missiles and Bombs

2021-07-15T03:33:07Z

Milo: added version history from 2.8 readme

== Overview ==

Missiles and Bombs is an OXP containing a collection of weapons and equipment available to buy from medium and high tech shipyards. While heavily focused on offensive weapons, the package also provides a selection of defensive equipment that may be particularly useful to pilots operating slower vessels.

== Offensive Weapons ==
<table>
<tr><td>[[Image:BlueSteel.png|left|150px]]</td><td valign="top">'''AS-1 Blue Steel Stand-off Cascade Missile'''</td><td valign="top">The Blue Steel is a large ship-sized missile armed with a 10-megaton quirium cascade warhead, effective at ranges of up to 20km. Although slower and less maneuverable than a conventional missile, the Blue Steel is hardened against both electronic countermeasures and direct laser fire, increasing its survivability in combat situations. Availability: TL13+ systems, 10,000₢ each. </td></tr>

<tr><td>
[[Image:RedPivot.png|left|150px]]</td><td valign="top">'''AS-2 Red Pivot Fragmentation Missile'''</td><td valign="top">The Red Pivot is a medium-sized missile armed with a fragmentation warhead. Upon initial detonation, a collection of bomblets are released which are then exploded via a time-delay fuse. The weapon has a 750m blast radius. Availability: TL9+ systems, 750₢ each. </td></tr>

<tr><td>
[[Image:GreenSpark.png|left|150px]]</td><td valign="top">'''AS-3 Green Spark Laydown Fragmentation Bomb'''</td><td valign="top">The Green Spark is a derivative of the Red Pivot missile and is armed with with a similar but significantly larger fragmentation warhead. The weapon is deployed in the form of a mine, and so may be used without a specific target being set into a ship's systems. The wide blast radius of the bomb makes it especially effective against multiple-ship formations or static targets such as asteroids or space stations. Availability: TL8+ systems, 650₢ each. </td></tr>

<tr><td>
[[Image:OrangeTear.png|left|150px]]</td><td valign="top">'''AS-4 Orange Tear Immobilisation Missile'''</td><td valign="top">Popularly known as the 'Lawmaker', the Orange Tear was developed for use by GalCop to help in apprehending fugitives. The missile uses a short-range electromagnetic pulse to temporarily disable a ship's systems, bringing the vehicle to a stop and allowing it to be boarded and searched by law enforcement officers. Availability: TL10+ systems, 2,000₢ each. </td></tr>

<tr><td>
[[Image:BlueNeon.png|left|150px]]</td><td valign="top">'''AS-5 Blue Neon High Speed Interception Missile'''</td><td valign="top">The Blue Neon is a small and highly-maneuverable missile designed for use against fast, agile targets capable of outrunning conventional weapons. For maximum speed the missile is equipped with fuel injection, however due to size and weight constraints this results in a relatively small warhead. The Blue Neon in therefore best used to damage and slow down targets, bringing them within range of laser fire or heavier missile weapons. Availability: TL7+ systems, 50₢ each. </td></tr>

<tr><td>
[[Image:YellowChisel.png|left|150px]]</td><td valign="top">'''AS-6 Yellow Chisel Multiple Warhead Anti-Thargoid Missile'''</td><td valign="top">Developed for use by the Imperial Navy against Thargoid warship formations, the Yellow Chisel is a large missile weapon that splits into four independent warheads; each warhead is equipped with a smart seeker head that is able to automatically identify and engage Thargoid ships, significantly increasing the odds of a successful attack. In the hands of Navy pilots, the Yellow Chisel is helping to turn the tide against the Thargoid menace. Availability: TL10+ systems, 8,000₢ each. </td></tr>

<tr><td>
[[Image:VioletFlax.png|left|150px]]</td><td valign="top">'''AS-7 Violet Flax Electronic Override Missile'''</td><td valign="top">An advanced development of the Orange Tear, the Violet Flax analyses a target's systems and within seconds generates an intelligent software virus designed to strike at vulnerable areas of code within the target's avionics systems. The virus is transmitted by the missile via a short-range electromagnetic pulse, and results in temporary control failure and severe damage to the ship's equipment. Availability: TL13+ systems, 8,500₢ each. </td></tr>

<tr><td>
[[Image:PurpleStrand.png|left|150px]]</td><td valign="top">'''AS-8 Purple Strand Remote Detonation Bomb'''</td><td valign="top">The Purple Strand is a high explosive munition that is deployed in the same way as a mine but is detonated using remote control rather than a time-delay fuse. The weapon is armed once it has reached a sufficient distance from the launching ship, after which it may be detonated using an ECM pulse. The bomb has an effective range of 5km. Availability: TL10+ systems, 2,000₢ each. </td></tr></table>
----
== Defense Systems ==

'''Chaff Dispenser'''

The Chaff Dispenser allows a pilot to launch bundles of chaff to provide a passive defense against most conventional missiles, including the industry-standard [[Faulcon de Lacy]] HM3 and HMX5 models. Chaff refills, available in bundles of five, may be purchased at shipyards once the dispenser equipment is installed.

Availability: TL8+ systems, 5,000₢ 
Chaff refills: TL5+ systems, 500₢ per refill.

'''Defense Mine'''

The Defense Mine is an anti-missile defense system. Each mine releases four smart missiles, each armed with a small fragmentation warhead, that automatically seek and destroy any other missiles in the immediate area.

Availability: TL10+ systems, 7,000₢ each.

'''Distress Beacon'''

For pilots operating in dangerous territory, the Distress Beacon is an invaluable security precaution. Once deployed, the beacon transmits a distress signal to the nearest police unit, which will dispatch a squadron of ships to assist against any hostile targets.

Availability: TL10+ systems, 700₢ each.

== Version Requirement ==
The latest version of Missiles and Bombs is v2.8 requires Oolite v1.79+ to work properly.

== Download ==
Download v2.8 in OXZ format [[Media:Missiles_and_Bombs_2.8.oxz|here]] for Oolite 1.79 or later (downloaded {{#downloads:Missiles_and_Bombs_2.8.oxz}} times). Discussion of this updated version can be found on the [http://aegidian.org/bb/viewtopic.php?t=19488 BB Forum here].

Missiles and Bombs (v2.5) is available from Ramirez' Oolite Pages [http://www.arcadia-digital.net/steve/Oolite/Oolite.html here].

== Version History ==
2.8, July 2021 (by phkb)
- Made Intercept missile susceptible to ECM.

2.7, July 2018 (by phkb)
- Added unique missile icon for Intercept missile.

2.6, March 2018 (by phkb)
- Updated to avoid deprecated AI methods.

2.5, December 2011
- fixed a problem with errors caused when missiles have no target

2.4, December 2009
- fixed a problem with chaff refills not being available after removing pylon-mounted weapons (compatibility with Oolite v1.73.4)

2.3, October 2009
- fixed problem with AI stack overflow on the Override and Lawmaker missiles

2.2, September 2009
- minor correction to the equipment.plist to make the Cascade Missile available to all

2.1, February 2009
- re-engineered the chaff launcher to avoid having overwrite original missile AIs

2.0, January 2009
- fixed the override missile, which was incorrectly damaging players' systems when used against NPCs
- revised the two EMP weapons so that they do not affect stations or asteroids
- made some minor game balancing tweaks
- general renaming of entities for consistency
- use of javascript to manage the chaff launcher more efficiently

1.2, December 2008
- incorporated Commander McLane's Status Quo Q-Bomb OXP, which prevents cascade weapons from detonating close to planets and suns
- modified the warning message used with by the electronic override missile shows which system has been damaged
- implemented compatibility changes for Oolite v1.72

1.1, September 2008
- electronic override missile now causes random failure of a ship's systems. Note that the weapon can be used against the player as well as NPC ships.
- defence mine has been modified so that once again it targets incoming missiles. The new missile interception code used in Oolite v1.71.2 makes this more effective than in previous versions of Oolite
- anti-thargoid missile will target any thargoid or thargon ships in the area

1.0, May 2008
- full release version to include compatibility with latest Oolite version (1.71.2)
- introduced javascript to manage the fragmentation weapons. Each one is now fitted with a proper Strike Enable Facility to ensure that they can only be activated when given the correct instruction. In previous versions, weapons such as the frag missile and frag bomb were liable to detonate in the event of a collision or explosion
- chaff refills are now only available from the shipyard if the player has a chaff dispenser fitted.

0.5, March 2008
- modified chaff so that it is no longer 100% effective and not as persistent.

0.4, November 2007
- added a multi-use chaff dispenser. The flares in v0.3 have been modified so that missiles (both standard and ECM-hardened) will lock onto them. The system has then been transformed into a multi-use chaff launcher
- interception missiles now make more use of fuel injection as originally intended
- added the Purple Strand ECM-activated remote detonation bomb.

0.3, September 2007
- added the Violet Flax Electronic Override Missile
- added the Distress Beacon
- altered the EMP Immobilisation Missile to have only a temporary effect on targets; ships will now be out of action for only 15 seconds
- further minor tweaks to various stats

0.2, March 2007
- altered the Defence Mine so that its missiles target pirate ships rather than other missiles. This makes it much more useful in combat.
- minor tweaks to various stats.

0.1, February 2007
- Initial package containing the following:
- Cascade Missile
- Anti-Thargoid Missile
- EMP Immobilisation Missile
- Fragmentation Missile and Bomb
- Interception Missile
- Anti-Missile Defence Mine
- Flare Dispenser

{{weapon-OXP}} {{equipment-OXP}}

Shipdata.plist

2021-07-15T02:53:51Z

Milo: added missing quotation mark pointed out by UK_Eliter

= Format =
Shipdata.plist is in [http://wiki.alioth.net/index.php/Property_list Property List] format.
The shipdata document is a dictionary of ships. Example:

{
"rsvh_adder" = {
like_ship = "adder";
is_external_dependency = yes;
pilot = "oolite-hunter";
roles = "rrs-vicious-hunter(1)";
"missile_role" = "EQ_HARDENED_MISSILE";
"script_info" = {
"randomshipnames" = "hunter";
"skilled_npc_role" = "hunter";
};
};

"rsvh_asp" = {
like_ship = "asp";
is_external_dependency = yes;
pilot = "oolite-hunter";
roles = "rrs-vicious-hunter(1)";
"aft_weapon_type" = "WEAPON_BEAM_LASER";
"script_info" = {
"randomshipnames" = "hunter";
"skilled_npc_role" = "hunter";
};
};
}

'''shipdata.[[plist]]''' will provide Oolite with all the definitions necessary to include it as an entity in the game, be it ship, station, freak object or sub-entity [[shipdata_structure|(extra)]]. The following (property) entries are, for order's sake, listed alphabetically:

= Ship keys=
The following keys are used by all ships
==accuracy==
Used with missiles it has influence on tracking of target. Allowed values with missiles are between 0.0 and 10.0. When not defined, the system assigns to the missile the accuracy value of 0.0, which corresponds to the standard missile tracking behaviour.

In 1.76 or earlier, when used with NPC ships it slightly enlarges the chance of shooting at greater distances, and makes a small improvement to their aim. Value with NPC ships is between -5 and 10 though all values between -5 and +1 will be increased to +1. When not defined, NPCs will be assigned a random value in the range +1 to +10.

In 1.77 or later, when used with NPC ships it affects various aspects of the ship AI. Values can be assigned between -5 and +10. When not defined, a random value between -5 and +5 will be used. [[OXP_NPC_Combat_AI|NPC accuracy]] significantly affects the quality of the AI in combat.

Example:
"accuracy" = 8.3;

== aft_eject_position ==
Determines the XYZ point on the model from which cargo is ejected.

Example:
"aft_eject_position" = "0.0 -4.5 -23.0";

== aft_weapon_type ==
Assigns the ship's aft laser.
Any weapon type from the [[equipment.plist]] can be used (and WEAPON_NONE).

Example:
"aft_weapon_type" = "WEAPON_BEAM_LASER";

== ai_type ==
Assigns an AI to the entity. This may be a previously existing AI, or one custom made for the occasion.

Example:
"ai_type" = "pirateAI.plist";

== auto_ai ==
This will autoswitch the ai to the appropriate one if a ship was added in one of its standard roles like trader or pirate. (true by default). See also the comment in the autoAIMap.plist inside Oolite. Defining auto_ai is only necessary when using one of the standard roles mentioned in the autoAIMap.plist for your ship. auto_ai does nothing for ships with custom roles.
Example:
"auto_ai" = yes;
This auto_ai switch is also used for bounties. When auto_ai is false the ship will keep the bounty as defined for the ship but, when true and the ship is added in one of the populator roles, the ship will get the default bounty for that role.

== auto_weapons ==
{{oolite-prop-added|1.79}}

This parameter if true (the default is false) indicates to the Oolite system populator (and potentially to OXPs) that they may change the weapons, missile load, equipment and other such parameters of this ship to make it better fit its role. This allows you to specify a single hull for multiple roles, and have the ship re-equipped to suit those roles. Ships intended for general addition to the spacelanes in standard roles and not intended to be significantly different in difficulty to the core ships should probably turn this on.

Example:
"auto_weapons" = yes;

== beacon ==
A special feature for beacons and navigation aids.
The string can be anything - the first letter is what's displayed in the advanced space compass.

Example:
"beacon" = "X";

Characters that are known to be used as identifiers for '''stations and other fixed objects''' are found on the page for the [[Advanced_Space_Compass#List_of_Navigational_Buoys|Advanced Space Compass]]. Most letters have been used multiple times in various OXPs. In 1.79 the HUD will therefore display a longer label also; before that several HUD OXPs are available to do something similar.

We can also use custom icons with the compass. For that you must define a key in descriptions.plist with the same name as the beacon definition. Than define the icon in the same way as missile icons. (An array of x/y-coordinates that will be connected by lines). You can find more info at [http://aegidian.org/bb/viewtopic.php?f=4&t=9529 the Oolite BB]. 
Example in shipdata:
"beacon" = "fuelStation_location";
Example in descriptions.plist
"fuelStation_location" = (1, 2, -3, 2, -3, -4, 3, -4, 3, 4, -3, 4, -3, 3, 2, 3, 2, -3, 1, -3 );
Before 1.75 the ships primary role was used for defining the icon name in descriptions.plist, but since 1.75 the beacon name itself is used.

== beacon_label ==
{{oolite-prop-added|1.79}}

A full label for the beacon. If this is not set, it will default to be the same as <code>beacon</code>, but it may be useful to have a beacon with a full label starting with a different letter than its code. The beacon label text will be expanded using the standard description rules
"beacon_label" = "%H Station"; // Lave Station, Diso Station, etc.

== bounty ==
Sets a Cr. reward on the NPC's head, and is bound to give it trouble with the law . This bounty setting is overruled when adding ships in one of the populator roles like pirate, trader etc. Pirates are default added with a small bounty and traders are added clean. However, like the player, also the npc bounty can raise when attacking other clean ships or police vessels.

Example:
"bounty" = 50;

== cargo_carried ==
Determines the type of cargo carried as described in [[commodities]] and [[commodities.plist]]. Only one type can be specified. This key can be used for both ships and barrels.

Example:
"cargo_carried" = "Gold";

When used for barrels, it is also possible to add several units in a pod by preceding the commodity name with a space separated number. Adding more than a ton in a pod is not possible. Defining a quantity for ships is not possible this way. 
It is possible to define a mix of random cargo for ships by using the string "SCARCE_GOODS" or "PLENTIFUL_GOODS", instead of a commodity name. The first selects random goods that are scarce at the main station, the second selects goods that are plentiful present at the main station. (Populator added traders heading toward the station always have scarce goods while traders heading from the main station always have plentiful goods on board. It would be wise to stick to this rule with custom ships.) 
To make cargo_carried working for ships, the cargo_type must be "CARGO_NOT_CARGO" to define the ship not being cargo itself. (see below)

'''Note''': A bug introduced in 1.82 means that only commodity keys from the [[Trade-goods.plist]] are recognised here. That is "gold" will be recognised, whereas "Gold" will not. This bug is fixed in the 1.83/1.84 release.

== [[cargo_type]] ==
Determines if object is indeed cargo (CARGO_RANDOM, CARGO_SLAVES, CARGO_THARGOID, CARGO_ALLOY, CARGO_MINERALS, CARGO_CARRIED) or a ship, as below, which is not cargo. (CARGO_RANDOM is not fully random but means that a container can hold any kind of commodity.) 

Example:
"cargo_type" = "CARGO_RANDOM";

Will create random cargo, often based on availability in the system. When you want fixed cargo you can use:

Example:
"cargo_type" = "CARGO_CARRIED";
"cargo_carried" = "4 Gold";

You can also specify the cargo of a ship. use "cargo_type" = CARGO_NOT_CARGO and define the contents of the barrels it will give with "cargo_carried". In that case there must be no quantity defined, only the type of [[commodity]].

Example:
"cargo_type" = "CARGO_NOT_CARGO";
"cargo_carried" = "Computers";

Another notable type of cargo is the scripted item CARGO_SCRIPTED_ITEM, as examplified by the cloacking device. When CARGO_SCRIPTED_ITEM is defined, the barrels will trigger scooping events for the ship-scripts. Other barrels don't trigger scooping events. 
The cargo barrels are stored in the ships hold like normal barrels when a cargo was defined for them with the JS method "setCargo". Without defined content, scripted barrels are removed after scooping. Scripted cargo works with any object that can be scooped. When you have scripted escape pods that must be preserved after scooping, fill it with one ton of Slaves.

== cloak_automatic ==
{{oolite-prop-added|1.75}}

When false, the cloak of npc ships will never get activate automatic during combat, but is only activated by JS script commands. (True by default)

Example:
"cloak_automatic" = no;

== cloak_passive ==
When true, any firing of laser will deactivate the cloak. (False by default in 1.76 or earlier, true by default in 1.77 or later)

Example:
"cloak_passive" = yes;

==conditions==
With this option you can include an array of extra conditions when to add a ship. When the conditions are not met, the ship does not appear in a selection list by role. Useful when you have a standard ship like a trader that should only be added in certain systems.

Example:
"conditions" = (
"systemGovernment_number equal 3",
"systemEconomy_number lessthan 4"
);

==condition_script==
''Available from Oolite 1.77 onwards''

This option specifies a Javascript file which controls the addition of this ship. The <code>allowSpawnShip</code> function in that [[Oolite_JavaScript_Reference:_Condition_scripts|condition script]] will then be tested before the ship is added. Several ships can share a condition script.

Example:
"condition_script" = "myoxp_conditions.js";

== counts_as_kill ==
{{oolite-prop-added|1.75}}

Killing this ship will not count as a kill by the player when set to false. (Default is true). Using this key prevents awarding kills to all kind of cargo, debris etc.

Example:
"counts_as_kill" = no;

== custom_views==
Will add the ability to display custom POVs of the player ship, in game toggled by pressing '''v'''.

This is an array with any number of entries, one for each view, each with:
*a '''view_description''' - giving a textual description of the view.
*a '''view_position''' - relative to the origin of the ship model.
*a '''view_orientation''' - this is a [[Quaternions|quaternion]] expressing a rotation from directly forwards.
*a '''weapon_facing''' - FORWARD, AFT, PORT or STARBOARD. The weapon that will fire when that view is selected.

The view_position is best chosen by selecting a facet, line or point in Wings and copying down the coordinates.

For the view_orientation you will probably need a calculator but the basic method is to choose a unit vector (x y z) as the axis for a rotation then calculate the four values W X Y and Z for the quaternion as follows:

W = the cosine of half the angle rotated about the axis xyz 
X = the sine of half the angle rotated about xyz, multiplied by x 
Y = the sine of half the angle rotated about xyz, multiplied by y 
Z = the sine of half the angle rotated about xyz, multiplied by z 

Four decimal places are probably enough accuracy for these values.

Example:
custom_views =
(
{
view_description = "Front View";
view_orientation = "0.0 0.0 1.0 0.0";
view_position = "0.0 30.0 200.0";
weapon_facing = "FORWARD";
}
);

== death_actions ==
Gives an opportunity to have a ship's death trigger one or a set of [[Shipdata.plist#script_actions|script_actions]]. It contains an array of legacy script expressions.

Example:
"death_actions" = ("spawn: explosive_shrapnel 1");

== debris_role ==
{{oolite-prop-added|1.74}}

Specifies the kind of debris an asteroid or boulder generates. When not defined they default to generating 'ships' with role "boulder" or "splinter".

Example:
"debris_role" = "my_boulder_foo";

== density ==
This real value is used to calculate a ships total mass. Default is 1.0. The mass of the ship is then 20 * density * volume.

Ship's mass does not affect its flight under the non-inertial engines - see [[#thrust|thrust]]. It does affect:
* changes in momentum, and damage done, in a collision
* the minimum distance needed from this ship for another ship to open a witchspace wormhole (the blocking radius is the square root of a tenth of the mass)
* the length of time a witchspace wormhole opened by this ship will remain open, and the radius of that wormhole.

Example:
"density" = 1.5;

== display_name ==
States the model's name as it will be known to the ID computer. By default this is the same as "name". Added for multilingual oolite.

Example:
"display_name" = "ExampleShip Mark IX";

== energy_recharge_rate ==
The rate at which energy is replenished. Stations are at 100, Adders at 2. (Default value: 1)

Example:
"energy_recharge_rate" = "3.5";

== escape_pod_model ==
With this entry ships can have custom escape pods. (starting from version 1.65) You have to specify the '''role''' of your custom escape pod (not its entry-name).

Example:
"escape_pod_model" = "custom_pod";

== escorts ==
Determines how many escorts an NPC shall have. Maximum is 16.

Example:
"escorts" = 4;
Warning: Ships with scanClass = CLASS_POLICE should always have escorts set to zero. Oolite will set this value here and add wingmans instead of escorts. Without special scripting escorts won't escort a mother with CLASS_POLICE. 
For ships that are added in a trader role, the populator can decide to subtract escorts from the defined value when the system is estimated as safe.

== escort_role ==
Assigns the specific ship type to be the escort, by the ship's role. (Before Oolite 1.74 only the name "escort-role" is accepted.)

Example:
"escort_role" = "my_custom_escort_role";
Escort ships will use the escortAI.plist unless "auto_ai" is set to false.

==escort_roles==
{{oolite-prop-added|1.79}}

This property overrules <code>escorts</code>, <code>escort_role</code> and <code>escort_ship</code> to allow more flexible specification of a ship's escorts. It takes the form of a list of dictionaries, each containing a "role", "min" and "max" key. The ship will then get between "min" and "max" of that role of escort ship (specific ships can be added using the "[dataKey]" style of role), with "max" more likely in Anarchy systems and "min" more likely in Corporate States.

escort_roles = (
{ role = "escort"; min = -2; max = 2; },
{ role = "escort-medium"; min = 0; max = 4; },
{ role = "escort-heavy"; min = -4; max = 2; },
{ role = ""; min = 0; max = 2; } // spare slots for wandering escorts
);

A negative number can be used for "min" - this makes it more likely that none of this type of escort will be used in safer systems, and makes the maximum number less likely in the more dangerous systems. In the example above, the ship will mainly be escorted by "escort-medium" ships, with a couple of "escort" ships likely in unsafe systems, and a small chance of "escort-heavy" ships also appearing in more dangerous systems.

Leaving the role key blank allows the ship to have spare slots for escorts which are left unfilled when the ship is spawned. This can be used to simulate a willingness to hire additional escorts, or to indicate that the ship has already lost some of its escorts.

The maximum number of escorts remains 16, and the list will be processed from top to bottom. Once 16 escorts are added no further entries will be considered.

== escort_ship ==
Assigns the specific ship type to be the escort, by the ship's name. (Before Oolite 1.74 only the name "escort-ship" is accepted.)

Example:
"escort_ship" = "cobramk1";
Escort ships will use the escortAI.plist unless "auto_ai" is set to false.

In Oolite 1.77 and later it is also possible to use <code>"escort_role" = "[cobramk1]"</code>

== exhaust ==
The XYZ position(s) of exhaust plume(s), and the XYZ of the plume shape, ergo

x y z width height length

'''x y z''' is the position relative to the origin of the main model.

'''width''' in meters, how far a plume extends on x axis, on each side of plume position. (x radius)

'''height''' in meters, how far a plume extends on y axis, above and below of plume position. (y radius)

'''length''' in meters, how long a plume is on z axis. (This value is in current Oolite versions ignored. Length is now derived from the ships speed)

Below are 2 assigned plumes at coords 5, 0, -25 and -5, 0, -25, and each plume is 6 m wide and 4 m tall. (length info is ignored)

Example:
"exhaust" = (
"5 0.0 -25 3.0 2.0 10.0",
"-5 0.0 -25 3.0 2.0 10.0"
);

== exhaust_emissive_color ==
{{oolite-prop-added|1.79}}

Determines the colour of the exhausts.

For the colour you can use either a [[Materials in Oolite#Colour specifiers|colour specifier]] or a [[Materials in Oolite#Named colours|named colour]].

Example:
"exhaust_emissive_color" = "redColor";
or
"exhaust_emissive_color" = "1 0 0";

== explosion_type ==
{{oolite-prop-added|1.81}}

A list of [[explosions.plist]] entries describing how the ship explodes if destroyed.

Example:
"explosion_type" = ("oolite-default-asteroid-explosion");

== extra_cargo ==
Cargobay extension size can be customised. This is the amount the cargo capacity increases when an extra cargobay is installed. Default value is 15. It is only used with player ships.

Example:
"extra_cargo" = 25;

== forward_weapon_type ==
Assigns the ship's forward laser.
Any weapon type from the [[equipment.plist]] can be used. e.g.: WEAPON_PULSE_LASER, WEAPON_BEAM_LASER, WEAPON_MILITARY_LASER, WEAPON_MINING_LASER, WEAPON_PLASMA_CANNON, WEAPON_THARGOID_LASER and WEAPON_NONE.

Example:
"forward_weapon_type" = "WEAPON_BEAM_LASER";

== frangible ==
Determines if eventual sub-entities are "loose". By default any given object is already frangible, so the use of this line must be to negate that.
If set to false, the object plus subentities will be regarded as a single object.
If set to true, sub entities can be destroyed seperately from the main object. Frangible sub-entities can have a max_energy and an energy_recharge_rate that is independently set from the main entity.

Example:
"frangible" = no;

== fragment_chance ==
Determines if a ship breaks apart into fragments and generates parts with role "wreckage". By chance factor, or true/false. Default is 90% chance.
The amount of wreckage is based on the ships mass with a maximum of 3. Wreckage is scaled to match the ships size but is very short living. (0.25s -> 1.25s)

Example:
"fragment_chance" = no;

== fuel ==
Determines an NPC ship's fuel storage, which will affect how it uses its Fuel Injectors and how far it can jump. If unspecified the default is zero (though ships added via the system populator will often be given some fuel anyway)

Example:
"fuel" = 70;

== has_cloaking_device ==
Determines if a ship has a cloacking device installed. By chance factor, or true/false.

Example:
"has_cloaking_device" = 0.5;

== has_ecm ==
Determines if a ship has the E.C.M system installed. By chance factor, or true/false.

Example:
"has_ecm" = 0.5;
or
"has_ecm" = no;

== has_energy_bomb ==
Determines if a ship has an energy bomb. If it has one, it might launch a mine with role "energy_bomb" as part of his fleeing behavior. currently the only build-in mine with this role is the q-bomb. A ship will only deploy the bomb when it has also fuel-injectors and some fuel left to avoid getting killed by its own bomb. On average it will try to deploy the bomb once every 100 seconds during fleeing.

Example:
"has_energy_bomb" = yes;

== has_escape_pod ==
Determines if a ship has an escape pod. Can be either a boolean value, or a number from 0 to 1 expressing the likelihood of the equipment being present. Starting with version 1.65 ships can have multiple escape pods. To specify more than one escape pod, '''has_escape_pod''' must be set to a numeric value corresponding to the escape pods present on board.

Examples:
has_escape_pod = no;
has_escape_pod = 0.75;
has_escape_pod = 3;

== has_fuel_injection ==
Determines if a ship has the witchdrive fuel injector.

Example:
"has_fuel_injection" = 0.99;

==has_military_jammer==
Determines if a ship has a military jammer. Ships equipped with this item become invisible on the radar.
Example:
"has_military_jammer" = 0.75;

==has_military_scanner_filter==
Determines if a ship has a military jammer filter. Ships equipped with this item can see ships equipped with a military jammer on the radar.
Example:
"has_military_scanner_filter" = 0.50;

== has_scoop ==
Determines if a ship has a fuel/cargo scoop.

Example:
"has_scoop" = no;

== has_scoop_message ==
A key for cargo. Determines if a barrel generates a default scoop message when scooped. Default is true, but setting it to false suppresses any messages, so a scripts can generate its custom messages on scooping. (Added with Oolite 1.74)

Example:
"has_scoop_message" = no;

== has_shield_booster==
Determines if a ship has the shield booster. (enlarges max energy with 256)

Example:
"has_shield_booster" = 0.80;

== has_shield_enhancer ==
Determines if a ship has the coveted shield enhancer. (enlarges max energy with 256 and raises energy recharge rate with 50%)

Example:
"has_shield_enhancer" = 0.45;

== heat_insulation ==
This real number gives the amount of heat insulation of a ship. Default is 1.0 (2.0 for ships equipped with EQ_HEAT_SHIELD). Values below 0.125 will be increased to that minimum. This parameter is only for NPC ships and stations. Player ships ignore this and always start with 1.0 heat insulation and can add an additional 1.0 (for a total of 2.0) with the ship equipment EQ_HEAT_SHIELD. Heat insulation for NPCs is only a factor when close to the sun. Energy damage does not cause overheating (because otherwise it would be too easy to overheat NPC ships with missiles or lasers), but it can raise ships' temperature to the maximum safe level. Overheating occurs when a ship's temperature exceeds the safe level, which is determined by the heat insulation level. External temperature is determined by distance from the sun. Larger suns are hotter. Suns that are going nova are, unsurprisingly, even warmer.

Example:
"heat_insulation" = "2.0";

NPC ships launched from stations are given the same heat insulation as the station if the station's is greater than the ship's. Courier ships generated by the core system populator are given a heat insulation level of 6.0. Escort ships (if any) receive at least the same heat insulation as the ship they are escorting. See [http://www.aegidian.org/bb/viewtopic.php?p=177357#p177357 BB Thread] (2012)

Player ships use the same model as NPC ships for external temperature from the sun, but additionally simulate heat from air friction when inside planetary atmospheres, which is a factor that NPC ships ignore.

== hud ==
Used for a playership, to assign another HUD than the default one.

Example:
"hud" = "specialhud.plist";

== hyperspace_motor ==
If set to false / NO, it will stop ships from executing normal hyperspace jump (player ships will still be able to execute galactic jumps). Default = true / YES. (Planned for Oolite 1.75)

Examples:
"hyperspace_motor" = no;

hyperspace_motor=NO;

== hyperspace_motor_spin_time ==
Used to modify jump countdown time. Default = 15.

Examples:
"hyperspace_motor_spin_time" = "15";

==injector_burn_rate==
{{oolite-prop-added|1.81}}

The default fuel burn rate of injectors on this ship, in deci-LY per second. The default is 0.25.

"injector_burn_rate" = 0.25;

==injector_speed_factor==
{{oolite-prop-added|1.81}}

The multiplier applied to the ship's maximum speed when it is using injectors. The default is 7.

"injector_speed_factor" = 7;

==is_external_dependency==
This key should be added to ships that use like_ship references to ships in other oxps but don't depend on them. Normally will Oolite write errors in the log when it can't resolve a like_ship reference. When this key is set to YES, it will suppress the error generation. WARNING: only set this key to YES when the model won't get added to the system without the other oxp installed or you will miss a valuable warning.

Example:
"is_external_dependency" = yes;

==is_submunition==
Key added for missiles with multiple warheads. When this key is set and the entity is spawn or fired by a missile, it inherits its parent as owner. This key must be set so the player will be awarded for a kill by submunition.

Example:
"is_submunition" = yes;

==is_template==
Set this to yes for ships which are only used through like_ships and are not intended to be used directly. If your (otherwise working) OXP generates warnings about ships with no roles or model attribute, you probably need this.

Example:
"is_template" = yes;

== laser_color ==
Determines a ship's laser colour.

As colour you can use a [[Materials in Oolite#Colour specifiers|colour specifier]] or a [[Materials in Oolite#Named colours|named colour]]. The game requires laser colours to be reasonably bright; if the brightest colour component is less than 0.5, the colour will be brightened.

Example:
"laser_color" = "cyanColor"

== launch_actions ==
Triggers a script on the entity just after setup, also when called by spawn and addShip methods.
Can be used to change to a custom AI, when a ship is generated by standard role.
[[Shipdata.plist#script_actions|script_actions]]

Example:
"role = trader";
"launch_actions" = (
"setAITo: pirateAI.plist"
);

== like_ship ==
Allows a shipdata entry (of a ship with many matching characteristics to another) to be short and sweet. With '''like_ship''' you can reference to another existing shipdata entry, and then only specify the differences to the 'original'. It takes the unique '''entry-identifier''' as argument. Of course you have to make sure that the 'original' you are referring to actually exists, or Oolite won't be able to create your ship.

Works well together with the [[#is_template|is_template]]-key.

Example:
"my_ship" = {
"like_ship" = "adder";
"max_flight_speed" = "700";
"name" = "Freak Turbo Adder";
},

== likely_cargo ==
This is only used for ships with role asteroid and pirate. With asteroids it gives the likely number of boulders it breaks into. With pirates added by the [[System Populator]]: when lower than 16 it is the cargo, when higher than 15, it is changed in a random value between 0 and 15. This value is overridden by the actual scooped cargo if the pirate had scooped something.

Example:
"likely_cargo" = "2";

== materials ==
See [[Materials in Oolite]].

== max_cargo ==
Sets the ship's cargo limit. On explosion of trader ships added by the [[System Populator]], 10% of this value is used as likely cargo. When the result is lower than 16 it is the cargo, when higher than 15, it is changed in a random value between 0 and 15.

Example:
"max_cargo" = "5";

== max_energy ==
Sets the ship's energy value. (Default value: 200)

Example:
"max_energy" = "300";

== max_flight_pitch ==
Sets pitch factor. Will usually range from a sluggish 0.6 to a very sensitive 3.0

Example:
"max_flight_pitch" = "2.2";

== max_flight_roll ==
Sets roll factor. Will usually range from 0.8 to 4.6.

Example:
"max_flight_roll" = "4.2";

== max_flight_speed ==
Sets the model's top speed. Interceptors fly at 520 (0.52 LM), Shuttles at 80.

Example:
"max_flight_speed" = "320";

== max_flight_yaw ==
Sets yaw factor. Will usually range from a sluggish 0.6 to a very sensitive 3.0 When no value is defined it will use the same value as max_flight_pitch

Example:
"max_flight_yaw" = "2.2";

== max_missiles ==
Sets a ship's missile limit. Maximum allowable value for the player is 16 and for npc ships 32. When not defined, the value with "missiles" is used as max_missiles. When defining more than a few missiles, it could be wise to also define value for "missile_load_time" to avoid massive missile launches. npc ships are more likely to fire missiles the more they carry.

Example:
"max_missiles" = "1";

== missile_launch_position ==
Determines the XYZ point on the model from which a missile is launched.

Example:
"missile_launch_position" = "0.0 -2.25 10.0";

This position should lie outside the bounding box of the core entity and not just outside of the ships mesh. Default value: (0, -4, 1) 
If the position does lie inside the bounding box, the launch position is shifted along its direction until the launched missile lies outside the bounding box of the central entity. (Bounding boxes of subentities are ignored) The collision radius of the launched missile is taken into account. The collision radius for a plain missile is 4.52 meter.

== missile_load_time ==
Defines the time in seconds before a new missile is ready to fire after one is fired. Mainly useful for npc ships that have many missiles.

Example:
"missile_load_time" = "2.1";

== missiles ==
Sets the number of missiles the ship is equipped with on ship creation. e.g. you can set this at zero and than use a dedicated script to fill up the bay with specific missiles.

Example:
"missiles" = "0";

== missile_role ==
Defines the type of missiles (or mines) an NPC ship is provided with. Default is "EQ_MISSILE". When missiles are loaded on ship creation, 90% will be of this type and 10% will be random, chosen from all possible NPC missiles and mines. Also affects the javascript [[Oolite_JavaScript_Reference:_Ship#selectNewMissile|selectNewMissile()]] command.
The string defined inside missile_role needs both to be defined inside [[equipment.plist]], and be inside the '''roles''' property of the missile/mine shipdata entry.

To assign a specific missile type to a newly bought player ship, its dependancies must be defined inside [[shipyard.plist]].

Example:
"missile_role" = "EQ_THARGON";

== model ==
Assigns the entity's corresponding '''.dat''' file that will be found with the exact same name in the ''Models'' folder.

Example:
"model" = "example_ship.dat";

== model_scale_factor ==
1.81 or later only.

If this is set, the model specified in the <code>model</code> property will be scaled by this factor (the default is 1.0, of course). Additionally, all subentities will have both their positions and sizes scaled (recursively if necessary), and the weapon positions will also be multiplied by the scale factor.

Player ships will also have their internal and external view positions multiplied by the scale factor.

model_scale_factors on subentities will be ignored - the value for the main entity will be used instead.

Example:
"model_scale_factor" = 2.0;

== name ==
States the model's name as it will be known to the ID computer.

Example:
"name" = "ExampleShip Mark IX";

== no_boulders ==
With older versions, scripted asteroids had no boulders by default. Starting with 1.70 all asteroids produce boulders when hit by a mining laser. no_boulders can overwrite this to emulate the old situation. By chance factor, or true/false.

Example:
"no_boulders" = yes;

== pilot ==
Gives the ship a predefined pilot, defined in [[characters.plist]]. Can eject in pod, if available, and be captured. 
By default every object starts with a pilot except buoys, missiles, cargo and rocks. By defining a specific pilot, any default pilot is replaced or a pilot is added to previously unpiloted objects.

Example:
"pilot" = "constrictor-mission-thief";

When no pilot is defined, Oolite will create a random pilot based on the ships role. For custom roles this means that Oolite has no clue and the pilot might have other bounties/insurances than desired. For this reason contains Oolite, starting with v 1.75, some predefined pilots: "oolite-trader", "oolite-pirate", "oolite-hunter", "oolite-police", "oolite-miner", "oolite-passenger" and "oolite-slave". When using one of these pilots, a random bounty/insurance will be set appropriate for this pilot role. Pilot bounty is different as ship bounty but on ejecting the pilot inherits the highest of both values. (actually a bitwise OR of both values)

== port_weapon_type ==
{{oolite-prop-added|1.77}}

Assigns the ship's port laser.
Any weapon type from the [[equipment.plist]] can be used (and WEAPON_NONE).

While not essential, you should generally assign the same weapon to [[#starboard_weapon_type|starboard_weapon_type]].

Example:
"port_weapon_type" = "WEAPON_BEAM_LASER";

== roles ==
Assigns which [[role]](s) the entity should have, that can correspond to one specific, exclusive use, or several.

The game engine constantly calls for generic roles to populate the universe. In the example below the ship in question will be considered twice as often (2.0) when a trader is called for, only one quarter as often (0.25) when looking for a hunter, and as often as any other pirate ships when looking for a pirate. Multiple roles are space separated. An explanation of the generic roles available in Oolite 1.79 or later is at [[Oolite_Ship_Roles]].

'''NB:''' If the ship cannot be docked to, extra care should be taken to avoid using the words '''station''' or '''carrier''' as part of any of the ship's role names. When either of these words are inside the roles key, the ship is automatically given station attributes. Other ships might even fruitless try to dock with it, and it will affect how some ships / entities are shown on the scanner.

Example:
"roles" = "hunter(0.25) trader(2.0) pirate";

or an exclusive role, simply:

"roles" = "uniquely_named_role";

This has the benefit of being the only ship to be selected when a [[Script.plist|script]] calls for the ''uniquely_named_role'' ship.

An item from the [[commodities]] can also be named as a role, for when that commodity is floating in space and called upon, to be represented by a particular model.

Example:
"roles" = "Gold";

Some roles are used by the game engine to populate systems, detect and define properties. (see also the [[System Populator]])
Such roles include 'thargoid', 'missile' and 'energybomb'.
Externally used equipment also needs specific mention of role, for example EQ_*_MINE and EQ_*_MISSILE.

== rotational_velocity ==
May be applied to a sub-entity, like the following entry to the [[Shipdata.plist#subentities|subentity]] spines of the [[Weeviloid Hunter]].
Takes the form of [[Quaternions|quaternions]]. The following example enables rotation around the Z-axis.

Example:
"rotational_velocity" = "0.707 0.0 0.0 0.707";

An explaining example taken from the Oolite Bulletin board.

The rotational velocity key is rotation per second.

For instance, if you want to rotate once per 20 seconds around the Z axis:

a = 360 ° / 20 = 18 °

[x, y, z] = [0, 0, 1]

sin a ˜ 0.30902

cos a ˜ 0.95106

Q = (0.95106, 0, 0, 0.30902)

'''shipdata.plist entry:'''
"rotational_velocity"="0.95106 0.0 0.0 0.30902";

== scan_class ==
Will alter the model's appearance on the [[IFF system]]. If this line is omitted, it will usually become by default a standard ship entity (CLASS_NEUTRAL), appearing as a yellow flag on the radar (red if hostile to the player), but may be given a different scan class if added with other roles. There are other options.
* CLASS_BUOY - green/yellow on scanner, will rotate in idle state, does not masslock
* CLASS_CARGO - white on scanner, can be scooped, does not masslock
* CLASS_MILITARY - purple on scanner, better pilots, will not attack other military ships, flashes purple/magenta if hostile to player
* CLASS_MISSILE - cyan on scanner, will not avoid collisions
* CLASS_POLICE - purple on scanner, will not attack other police ships, legal penalties for attacking, never has bounty, flashes purple/magenta if hostile to player
* CLASS_ROCK - white on scanner, launched defense ships do not inherit scan class, does not masslock
* CLASS_STATION - green on scanner, launched defense ships do not inherit scan class
* CLASS_THARGOID - green/red on scanner, considered hostile to any non-thargoid ship
* CLASS_NO_DRAW - invisible on scanner, cannot be targeted by missiles, does not masslock
* CLASS_MINE - red/yellow on scanner, automatically set on mines launched by player to override existing scan class, does not masslock
(This property was called "scanClass" before Oolite 1.74.)
Scan classes marked as "does not masslock" will masslock the player anyway if they are hostile to the player (as condition will be Red)

Scripts can define custom colours for ships on the [[IFF system]] so ships may have a scanner appearance different to the default for their scan class.

Example:
"scan_class" = "CLASS_ROCK";

==== Developer Note ====
Oolite uses scan_class internally to determine the behaviour of some ships (particularly with regard to who may shoot whom without incurring legal penalties). Bear this in mind and don't allocate CLASS_POLICE or CLASS_THARGOID to ships lightly!

== scan_description ==
{{oolite-prop-added|1.81}}

The description of the ship's legal status on the [[Scanner Targeting Enhancement]]. If this is absent, the default text for the scan class will be used.

"scan_description" = "Unclaimed rock";

== scanner_display_color1 ==
Overrides the color that would normally be set by scanClass.

Example:
"scanner_display_color1" = "greenColor";

== scanner_display_color2 ==
Overrides the color that would normally be set by scanClass. If this is set, the ship will flash between the two colours.

Example:
"scanner_display_color2" = "redColor";

== scanner_hostile_display_color1 ==
{{oolite-prop-added|1.81}}

Overrides the color that would normally be set by scanClass when the ship is hostile and targeting the player.

If no hostile colours are set, but normal colours are set, then the normal colours, not the scan class colours, will be used for a hostile ship.

Example:
"scanner_hostile_display_color1" = "greenColor";

== scanner_hostile_display_color2 ==
{{oolite-prop-added|1.81}}

Overrides the color that would normally be set by scanClass when the ship is hostile and targeting the player. If this is set, the ship will flash between the two colours.

Example:
"scanner_hostile_display_color2" = "redColor";

== scanner_range ==
Sets a custom scanner range. Standard is 25.6 km, thargoids have 50 km. Only applies to NPCs. However, at least since oolite 1.65 all defined scanner ranges are limited to 25.6 km, even for thargoids. This means it only makes sense defining shorter ranges than the maximum range.

Example:
"scanner_range" = "25600";

== scoop_position ==
Determines the XYZ point on the model from which cargo is scooped. (default is 0,0,0)

Example:
"scoop_position" = "0.0 -4.5 -23.0"

Scooping for a player ship starts when the cargo collides with the front half of the bottom of the ship. Any other place of first contact leads to smashing the cargo in pieces. A good y-value for the position would therefor be half the size of the lowest body part of this area of the ship. For the z-value a point in the back side would be better.

== script ==
Specifies a [[Scripting Oolite with JavaScript|JavaScript script]] (through it's filename) to attach to the ship. Ship scripts are the preferred approach for scripting ships in current Oolite.

== script_info ==
A property list whose contents are available to JavaScript scripts, for whatever use they desire. It is exposed to JavaScript as the <code>[[Oolite JavaScript Reference: Ship#scriptInfo|scriptInfo]]</code> property of <code>Ship</code> objects. 
Take note that when using an ascii plist, the JS engine will read in all entries as strings. When you need an entry as number, you might need to explicit convert it to a number. This is specially true for booleans as a "NO" string will be read as true. For all normal keys its Oolite that does the conversion for you.

A short overview about used [[OXP_scriptInfo|script_info keys in OXPs]].

== script_actions ==
Gives an oportunity to insert events such as in [[script.plist]], to involve a specific shipdata entity. As seen in the following example, this particular object checks if Player has a cloaking device, and if not, will award it. Should Player already have it, the gift will be in gold. See also [[scripts within shipdata]] for more detailled info.

Example:
"script_actions" =
(
"testForEquipment: EQ_CLOAKING_DEVICE",
{
"conditions"
(
"foundEquipment_bool equal NO"
)
"do"
(
"awardEquipment: EQ_CLOAKING_DEVICE"
)
"else"
(
"awardCargo: 100 Gold"
)
}
);

== setup_actions ==
Arranges a process that may be necessary for some objects, like ball turrets.

Example:
"setup_actions" =
(
"initialiseTurret"
);

== shaders ==
The ''shaders'' dictionary has the same structure as the ''[[#materials|materials]]'' dictionary. When [[Shaders in Oolite|shaders]] are available, the contents of the ''shaders'' dictionary are used in preference to those in ''materials''. If shaders are not available, the ''shaders'' dictionary is ignored.

== ship_name ==
{{oolite-prop-added|1.79}}

The name of this individual ship (e.g. Pride of Lave), which is placed in [[Oolite_JavaScript_Reference:_Ship#shipUniqueName|ship.shipUniqueName]]. It rarely makes sense to set this property in <code>shipdata.plist</code>, except perhaps for a unique mission ship.

== ship_class_name ==
{{oolite-prop-added|1.79}}

The name of this ship's class (e.g. Sidewinder), which is placed in [[Oolite_JavaScript_Reference:_Ship#shipClassName|ship.shipClassName]]. If this is not set, it will default to [[#name|name]], which is usually suitable.

== show_damage ==
{{oolite-prop-added|1.81}}

Whether to show sparks and other damage effects when this ship is hit.

Defaults to on if energy recharge rate is greater than zero, off otherwise, for compatibility with previous hard-coded behaviour.

== smooth ==
Determines if the model will use glLightModel(GL_FLAT) or glLightModel(GL_SMOOTH).

If true, then lighting effects will be interpolated across the polygons of the model, giving a more 'rounded' effect.

Asteroids, Boulders and Splinters use this effect as do some other models.

Example:
"smooth" = yes;

== spawn ==
The spawn directory is only used when a ship is added with the command: "spawnShip: shipname". This command only allows to add one ship by name (not role!). The position and orientation are taken from a spawn directory that describes the position it is placed and the position it is looking at.

Example
"spawn"
{
"facing_position" = "spu 0 0 0";
"position" = "wpu 0 0 0.2";
}

== starboard_weapon_type ==
{{oolite-prop-added|1.77}}

Assigns the ship's starboard laser.
Any weapon type from the [[equipment.plist]] can be used (and WEAPON_NONE).

While not essential, you should generally assign the same weapon to [[#port_weapon_type|port_weapon_type]].

Example:
"starboard_weapon_type" = "WEAPON_BEAM_LASER";

== subentities ==
An array of ''subentity definitions''. A ''subentity'' is an object attached to your ship. There are several types of subentity:
* ''Static subentities'', the default type, are simply extra models. They are defined as separate shipdata.plist entries, so technically they’re ships, but they don’t have a mind of their own. If the main ship is [[#frangible|frangible]], static subentities can take damage and blow up separately from the main ship. They can also be individually exploded or removed by scripts.
* ''Docks'' are recognized when setting up a station or carrier, and used to determine the station’s docking port parameters. After set-up, they work just like normal static subentities. The string "dock" in lowercase must be part of the old style name in order to get recognised as the dock subEntity.
* ''Ball turrets'' turn to track the ship’s current target, and shoot plasma balls if the target is within range (6000 metres). A ball turret’s field of fire is a 157 ° cone centred on its original facing. Currently, ball turrets make no effort not to shoot their own ship, so it is up to the designer to ensure this field of fire is clear. Like a static subentity, a ball turret is based on a shipdata.plist entry so its appearance can be customized. Oolite provides a built-in shipdata entry for ball turrets called, imaginatively, '''ballturret'''.
* ''Flashers'' are blobs which glow with a pulsating light. From Oolite 1.74 onwards, constant light will also be an option. Note that while flashers appear luminous – they are unaffected by shadows – they do not cast light on other objects.

=== New-style subentity definition ===
Oolite 1.73 introduced a more flexible, dictionary-based way of specifying subentities. A new-style subentity is a dictionary using the following keys:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"
|+ Subentity definition properties
! Name !! Type !! Description
|-
| '''type''' || string || One of: “'''standard'''”, “'''ball_turret'''”, “'''flasher'''”. If not specified, “standard” is assumed.
|-
| '''subentity_key''' || string || The key of a ''shipdata.plist'' entry. Required for '''standard''' and '''ball_turret''' subentities, ignored for flashers.
|-
| '''position''' || vector || The position of the subentity relative to its parent. (This can be specified as a string with three numbers in it, or an array of three numbers, or a dictionary with '''x''', '''y''' and '''z''' entries.) Default: (0, 0, 0).
|-
| '''orientation''' || [[quaternion]] || The orientation of the subentity. Ignored for flashers. (This can be specified as a string with four numbers in it, or an array of four numbers, or a dictionary with '''w''', '''x''', '''y''' and '''z''' entries.) Default: (1, 0, 0, 0), which corresponds to no rotation.
|-
| '''is_dock''' || boolean || True if the subentity is a dock; false by default. Only applies to '''standard''' subentities. '''Note:''' this is ''not'' implied by having “dock” in the '''subentity_key''', as it is for old-style subentity definitions. In Oolite 1.76 or earlier a station may only have at most one dock subentity.
|}

{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"
|+ Subentity definition properties for dock subentities (1.77 or later)
! Name !! Type !! Description
|-
| '''allow_docking''' || boolean || ''In Oolite 1.77 or later'', whether the dock allows docking. Defaults to true. (and always true in 1.76). Ignored for non-docks.
|-
| '''allow_launching''' || boolean || ''In Oolite 1.77 or later'', whether the dock allows launching. Defaults to true. (and always true in 1.76). Ignored for non-docks.
|-
| '''disallowed_docking_collides''' || boolean || ''In Oolite 1.77 or later'', if this is true, ships attempting to dock here will collide with the dock if <code>allow_docking</code> is false. If it is false, ships attempting to dock here will be docked with the station anyway. Defaults to false. (and always false in 1.76). Ignored for non-docks.
|-
| '''dock_label''' || string || ''In Oolite 1.77 or later'', the name given to the dock by traffic control (overrides the display_name of the dock subentity). Defaults to "the docking bay", and ignored for non-docks. In Oolite 1.76 or earlier the concept of dock names is meaningless.
|}
See [[Multiple Docks]] for more information on dock subentities and stations with more than one dock in Oolite 1.77 or later.

{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"
|+ Subentity definition properties for ball turrets
! Name !! Type !! Description
|-
| '''fire_rate''' || number || Interval between shots in seconds, for '''ball_turret''' subentities. Default: 0.5; minimum: 0.25.
|-
| '''weapon_range''' || number || Range for '''ball_turret''' subentities. Default: 6000; maximum 7500.
|-
| '''weapon_energy''' || number || Weapon energy for '''ball_turret''' subentities. Default: 25; maximum 100.
|}

{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"
|+ Subentity definition properties for flashers
! Name !! Type !! Description
|-
| '''color''' || [[Materials in Oolite#Colour specifiers|colour specifier]] || Single colour for a flasher. Ignored for non-flashers. Default value: '''redColor'''.
|-
| '''colors''' || array || Array of colour specifiers for a flasher. Ignored for non-flashers. Before 1.74, only the first entry was used. If not present, see '''color'''. '''Note:''' like [[#laser_color|laser_color]], flasher colours must be “reasonably bright”.
|-
| '''frequency''' || number || Pulse rate for flashers, in cycles per second. Ignored for non-flashers. If 0, the flasher will have full intensity all the time in Oolite 1.74 and later, but half intensity in earlier releases. Default: 2.
|-
| '''initially_on''' || boolean || Specifiers whether a flasher is turned on when created. Ignored for non-flashers. Default: yes.
|-
| '''phase''' || number || Pulse phase offset for flashers, in seconds. Ignored for non-flashers. (This value is simply added to the time to get the pulse parameter.) Default: 0.
|-
| '''size''' || positive number || Diameter of a flasher in metres. Ignored for non-flashers. Default: 8. (Why 8? I don’t remember.)
|-
| '''bright_fraction''' || number || ''In Oolite 1.77 or later'', a number between 0 and 1 defining the proportion of the flasher's cycle that the flasher is bright for. Ignored for non-flashers. The default (which mimics the behaviour of all flashers in 1.76 or earlier) is 0.5.
|-
|}

=== Old-style subentity definition ===
Prior to Oolite 1.73, this was the the only way to specify a subentity.

An old-style subentity definition is a string with eight items separated by spaces. In the description below, words in bold correspond to keys in [[#New-style subentity definition|new-style definitions]]. There are two variants:

==== Flashers ====
For a flasher, the entry takes the form:
*FLASHER* x y z hue frequency phase size
''*FLASHER*'' must be precisely the string “*FLASHER*”, in capitals.

''x'', ''y'' and ''z'' form the '''position'''.

''hue'' specifies the [http://en.wikipedia.org/wiki/HSL_and_HSV HSV] hue component (in degrees) of '''color'''. Saturation and value are always 1.

'''frequency''', '''phase''' and '''size''' are the same as in the new-style format.

'''initially_on''' is false.

==== Other subentities ====
For a non-flasher, the entry takes the form:
key x y z qw qx qy qz
''key'' corresponds to '''subentity_key'''.

''x'', ''y'' and ''z'' form the '''position'''.

''qw'', ''qx'', ''qy'' and ''qz'' form the '''orientation'''.

'''type''' is ''standard'' unless the command ''initialiseTurret'' is present in the [[#setup_actions|setup_actions]] of the subentity, in which case it is ''ball_turret''. Note that the ''initialiseTurret'' no longer does anything when executed in a script; its presence is only used as an indicator to set the ''is_turret'' property when old-style definitions are translated. If ''initialiseTurret'' is inside a condition, it will be ignored. The ''initialiseTurret'' command is not required or useful for turrets which are only referenced using new-style subentity definitions.

'''is_dock''' is implied by having the string “dock” (in lowercase) in the ''key''.

== sun_glare_filter ==
{{oolite-prop-added|1.79}}

The default strength of the sun glare filter on this ship. A number between 0 and 1, with the default being 0 (no filter)

"sun_glare_filter" = 0.3;

== track_contacts ==
Tracks the movement of the ship and sends a "CLOSE CONTACT" message to other ship AI's. It uses a time consuming tracking, so only set to true when actually used.

Example:
"track_contacts" = yes;

== throw_sparks ==
{{oolite-prop-added|1.73}}

Each new ship should start in seemingly good operating condition, unless specifically told not to. (false by default)

Example:
"throw_sparks" = yes;

== thrust ==
Gives the entity an 'inertia' value, telling how fast it can increase or reduce speed (in m/s^2). 0 for rocks and cargo, 50 for a very fast ship, 100 for a station. When used with turrets it defines the turn rate in revolutions per second (with 1 being an average value).

Example:
"thrust" = "25"

== unpiloted ==
Used to designate items that will never have a pilot, thus never turn aggressive and never eject a pod. By chance factor, or true/false. 
It will not add a pilot when set to false, but will remove any existing pilot when set to true.
commsMessages can only be broadcasted by piloted ships. Ships are by default piloted. cargo , rocks, missiles etc. are not piloted by default.

Example:
"unpiloted" = yes;

== view_position_.. ==
Sets the ship's 4 point-of-view positions in XYZ relative to the model.

Example:
"view_position_aft" = "0.0 5.0 -20.0";
"view_position_forward" = "0.0 1.9375 5.0";
"view_position_port" = "-11.85 2.825 -3.5";
"view_position_starboard" = "11.85 2.825 -3.5";

== weapon_energy ==
This setting works differently depending on the type of entity it's used for: 

Missiles. Changes the damage inflicted by the missile. Any value accepted.

NPC ships. Changes the forward weapon damage to a value different to the default one. Values higher than 50 will be clamped to 50. Does not change the value for aft weapons or subEntity weapons. 
N.B. It does not have any effect on player ships.

turrets. Unused for turrets. Set the turret weapon_energy in its [[Shipdata.plist#New-style_subentity_definition|subEntity directory]].

Default values are: WEAPON_PLASMA_CANNON = 6.0; WEAPON_PULSE_LASER = 15.0; WEAPON_BEAM_LASER = 15.0; WEAPON_MINING_LASER = 50.0; WEAPON_THARGOID_LASER = 12.5; WEAPON_MILITARY_LASER = 23.0

Example:
"weapon_energy" = "17";

== weapon_facings ==
{{oolite-prop-added|1.77}}

What weapon mounts are available on the ship. This is a bit-mask, so pick the mounts and add the numbers:

1 - Forward 
2 - Aft 
4 - Port 
8 - Starboard 

Example: 
Fore and aft weapon mounts only.
<key>weapon_facings</key>
<integer>3</integer>

If omitted, defaults to 15 (all mounts). If a player ship has this specified, and the same property specified in shipyard.plist, the shipyard.plist property takes precedence.

Weapons assigned to a mount that the ship does not have will be ignored. Scripting cannot be used to add weapons to these mounts later, either.

== weapon_mount_mode ==
{{oolite-prop-added|1.83}}

This controls how multiple weapon mount points work. It has three possible values:
* '''"single"''': this is the default, and replicates 1.82 and previous behaviour. In this mode, <code>weapon_position_*</code> properties are simple vector expressions, and there is exactly one mount per facing.
* '''"split"''': In this mode, <code>weapon_position_*</code> properties are an array of vector expressions. A weapon fitted to this facing has the same heat and energy cost as a single standard weapon, and the damage output is divided equally between all mount points. (in other words, the distinction is mainly cosmetic)
* '''"multiply"''': In this mode, <code>weapon_position_*</code> properties are an array of vector expressions. A weapon fitted to this facing has N times the heat and energy cost as a single standard weapon, and each mount point does normal damage. (in other words, the weapon is fitted N times at once)

For best results with AI and the "target reticle sensitive" feature, if there are several weapon positions in a (rough) line, the middle one should be listed first.

See [https://github.com/OoliteProject/oolite/pull/161 this comment] or [[Multiple Lasers]] for examples.

== weapon_offset ==
Removed after version 1.65 (it was used to change the offsetpoint of a plasma cannon.)

== weapon_position_.. ==
Plots the 'gunmouth' points of the model's 4 potential lasers.

In 1.82 and earlier, and in 1.83 and later in the "single" <code>weapon_mount_mode</code>, these are vector expressions.

Example:
"weapon_position_aft" = "0.0 -5.0 -20.0";
"weapon_position_forward" = "0.0 0.0417 16.6667";
"weapon_position_port" = "-13.75 -2.0625 -1.875";
"weapon_position_starboard" = "13.75 -2.0625 -1.875";

In 1.83 and later, with "split" or "multiply" <code>weapon_mount_mode</code>, these values are specified as arrays of vector expressions. For example:
"weapon_position_forward" = ( "0.0 3.0 32.0" , "-15.0 0.0 32.0" , "15.0 0.0 32.0" )

= Station keys=
The following keys are only used by stations or carriers.

== allegiance ==
An advisory flag that informs AIs how they should expect to be treated near or when attempting to dock with this station. See [[Oolite_JavaScript_Reference:_Station#allegiance|station.allegiance]] for the allowable values. If this is not set, the game will guess based on other station properties.

Example:
allegiance = "neutral";

== allows_auto_docking ==
{{oolite-prop-added|1.75}}

When set false for a station, this station will not allow the use of a docking computer. Default value in "yes".

Example:
allows_auto_docking = "no";

== allows_fast_docking ==
{{oolite-prop-added|1.75}}

When set true for a station, this station will allow fast docking with the docking computer. Default value in "no".

Example:
allows_fast_docking = "yes";

== defense_ship ==
Gives an oportunity to designate a particular ship by name that will defend a station/carrier. See also [[Shipdata.plist#defense_ship_role|defense_ship_role]]

Example:
defense_ship" = "my_defender";

== defense_ship_role ==
Gives an oportunity to designate a particular (group of) ships that will defend a station/carrier. This has to be specified in the [[Shipdata.plist#roles|roles]] of the ship(s) that are assigned to defend. When launched from a carrier the scan_class becomes that of the carrier. Default role is "police"/"interceptor" for normal stations and "hermit-ship" for stations of CLASS_ROCK. Defense ships with scanclass police or with a hermit-ship role launch with a policeInterceptAI.plist. All other ships use the ai_type as defined in shipdata.plist. After launch, all primary roles are changed into: "defense_ship"

Example:
"defense_ship_role" = " carrier_defenders";

== equipment_price_factor ==
Equipment price mask for dockables.

Example:
"equipment_price_factor" = "4.5";

== equivalent_tech_level ==
Sets shipyard tech level for dockables, different to the local system tech_level. Default value is the system tech_level.

Example:
"equivalent_tech_level" = 1;

== has_npc_traffic ==
Determines if a station launches NPC traffic. Default is "yes" for stationary stations, and "no" for stations with a non-zero maximum speed. When set to "no" the station will not launch random ships as part of the main Oolite system repopulator (though OXP scripts may still launch ships from it).

The type of traffic launched depends on the [[#allegiance|allegiance]] property of the station (which also determines what, if any, ships may try to dock at it).

Example:
"has_npc_traffic" = yes;

== has_patrol_ships ==
{{oolite-prop-added|1.75}}

Determines if a station launches periodic patrol ships. Default is "no". Main stations always have patrol ships.

Example:
"has_patrol_ships" = yes;

== has_shipyard ==
Determines if a station or carrier has a shipyard. By chance factor as number between 0 and 1, but it can also be an array of conditions. Default is "no", but for main stations has_shipyard is always "yes". (Name is valid starting with Oolite 1.74. Before it was called "hasShipyard".)

Example:
"has_shipyard" = "0.75";

or

"has_shipyard" = (
"systemGovernment_number morethan 3",
"systemEconomy_number lessthan 4"
)

== interstellar_undocking ==
{{oolite-prop-added|1.75}}

When set true for a station, this station will allow interstellar docking and undocking in interstellar space. When set to "no" the player docks in nearby normal space. Default value in "no".

Example:
interstellar_undocking = "yes";

==is_carrier==
Added as a tag for making the model be considered a carrier or station. An alternative to including ''carrier'' or ''station'' among the [[Shipdata.plist#roles|roles]]. When present this key even overrules station/carrier settings with roles. (Name is valid starting with Oolite 1.74. Before it was called "isCarrier".)

Example:
"is_carrier" = yes;

== market ==
Key that sets the market for stations and carriers. The name defines the key in [[commodities.plist]] that will be used as local market. Without a market key, the stations primaryRole is used as market. Added with test release 1.74 and no longer used in 1.81 or later, where it is replaced by the market_* properties below.

Example:
"market" = "none";

== market_broadcast ==
{{oolite-prop-added|1.81}}

If this is enabled the station's market will appear on the F8 screen if the player is in flight and has the station targeted. The default is enabled. This is ignored (and always true) if the station is the main station.

"market_broadcast" = no;

== market_capacity ==
{{oolite-prop-added|1.81}}

The capacity in units per trade good of the station market. If omitted, the default market capacity of 127 units will be used. This is ignored if the station is the main station as it will use the system market, not its own.

"market_capacity" = 31;

== market_definition ==
{{oolite-prop-added|1.81}}

An array of [[trade-goods.plist#Secondary_Market_Definitions|secondary market rules]] which modify some or all of the price, quantity, capacity and legal status of a good relative to the primary system market. This is ignored if the station is the main station as it will use the system market, not its own.

"market_definition" = (
{
// export cheap clothes
"type" = "class";
"name" = "oolite-wearable";
"price_multiplier" = 0.8;
"price_randomiser" = 0.1;
"quantity_multiplier" = 3.5;
"quantity_randomiser" = 3.0;
},
{
// not really interested in other goods
"type" = "default";
"price_multiplier" = 0.55;
"price_randomiser" = 0.25;
"quantity_multiplier" = 0.0;
"capacity" = 3;
}
);

If the capacity set by a rule is larger than the market_capacity of the station, the market_capacity of the station is used instead.

A blank array
"market_definition" = ();
will give a market identical to the primary system market.

If this key is omitted, the station will have no market. This is roughly equivalent to
"market_definition" = (
{
"type" = "default";
"price_multiplier" = 0;
"quantity_multiplier" = 0;
"capacity" = 0;
}
);

== market_monitored ==
{{oolite-prop-added|1.81}}

If this is true, the market is subject to Cooperative law for the import and export of trade goods, and the player will gain the usual bounties for smuggling contraband. The default value is no. This is ignored (and effectively always true) if the station is the main station.

market_monitored = yes;

== market_script ==
{{oolite-prop-added|1.81}}

Allows a [[Oolite Market Scripts|market script]] to be used to modify trade prices. This overrides market_definition, if it is present.

market_script = "myoxp_marketchanges.js";

== max_defense_ships ==
Designates how many ships a dockable entity (station, carrier) can launch in defense. Default value is 3. See also [[Station Ships]]

Example:
"max_defense_ships" = "10";

== max_police ==
Designates how many police or patrol ships a dockable entity (station, carrier) can launch. Default value is 8. See also [[Station Ships]]

Example:
"max_police " = "10";

== max_scavengers ==
Designates how many scavengers or miners a dockable entity (station, carrier) can launch. Default value is 3. See also [[Station Ships]]

Example:
"max_scavengers" = "10";

== port_dimensions ==
Defines the size of the docking port and takes 3 numbers, separated by "x". This key is generally of little use and can be skipped as it becomes overwritten by the actual size of the bounding box of the dock subentity when a correct dock subentity is defined.

Example:
"port_dimensions" = "65x30x500";

Size of Oolites main-station dock is: 64.00 x 192.00 x 250.00 while the dimension of a rock-hermit dock is: 138.001 x 138.001 x 250.12 (W x H x L) 
These sizes may be relevant for ship dimensions as since Oolite 1.75 ships must fit in these docks to be allowed docking or launching.

== port_radius ==
Defines the size of the docking port radius. Or more precise, this is the distance from the station centre to the port location. Default value is 500. This key is generally of little use and can be skipped as it will be overwritten by the real position of the dock subentity.

Example:
"port_radius" = "500";

== requires_docking_clearance ==
Sets the requirement for docking clearance. Default is "no". See also [[Oolite_Docking_Clearance_Protocol_%28v1.72_or_later%29|DockingClearance]]

Example:
"requires_docking_clearance" = yes;

==rotating==
Given to a station when rotation is desired. Default is "no".

Example:
"rotating" = yes;

== station_roll ==
{{oolite-prop-added|1.74.2}}

Determines the rotation speed of a station. Default value is determined by the systemwide station_roll in planetInfo.plist. If that is not defined, the default is 0.4. Negative values are also possible for a rotation in the other direction.

'''Note''': unlike the other turn rate properties, for historical reasons <code>station_roll</code> is measured in right-angles/second, ''not'' radians/second.

Example:
"station_roll" = "-1.5"

==tunnel_corners==
{{oolite-prop-added|1.75}}

Defines the number of corners in the docking tunnel. Ranges from 4 to 128. Default is "4".

Example:
"tunnel_corners" = 6;

==tunnel_start_angle==
{{oolite-prop-added|1.75}}

Defines the position of the first corner of the docking tunnel in degrees. 0 means the first corner is straight up. Default is "45".

Example:
"tunnel_start_angle" = 0;

==tunnel_aspect_ratio==
Defines the proportion of the tunnel’s width to its height. Default is "2.67".

Example:
"tunnel_aspect_ratio" = 1;

--------------------------------------------------------------------------------
[[Category:Oolite]]
[[Category:Oolite scripting]]

Deep Horizon Advanced Navigation Computer

2021-07-15T02:47:14Z

Milo: added 1.0.5 to version history

Adds a primeable piece of equipment that improves interstellar navigation in the form of fuel savings.

== Release Blurb ==
''A small blue-skinned humanoid approaches the podium in front of the assembled members of the press accompanied by an even shorter, squat, black-bodied avian with a white belly. He appears to have flippers instead of wings, and may be an Arritian. After scanning the room, the blue-skinned being begins reading aloud from his notes...''

"Greetings all. I'd like to thank you all for coming today.

Deep Horizon Industries, in association with Gorth Consultancy Services, is proud to announce our latest technological delivery to the space faring populace. Available immediately is the '''ANC-42 Advanced Navigation Computer'''. While the exact nature of Witchspace is still the subject of scientific research, we are aware that it has certain directional flows. We at Deep Horizon Industries together with our project partners at Gorth Consultancy Services, decided to take advantage of these eddies and currents within witchspace utilizing feedback derived from the recently deployed GFL-1 Witchpoint Tunnel Demarkation Buoys. By extending the calcuation time before making a witchjump, our Advanced Navigation Computer enables vessels to successfully navigate witchspace in a more efficient manner that results in a lower overall energy expenditure for a witchspace jump. A pilot utilizing this equipment can save 10% of his fuel expenditures in this manner.

Additionally, we at Deep Horizon Industries would like to announce the separate development of the '''EWI-OS-5141 Emergency Witchspace Initiator''' or '''EWI'''. Developed independently of the ANC project, the EWI offers a new hope for pilots. Combat is a dangerous proposition, whether entered willingly to claim a prize, begrudgingly in defense of another, or fearfully when not of your choosing. Given time, it is also inevitable for pilots to find themselves in combat. Likewise, overwhelming odds, inferior abilities compared to your opponent, or simple misfortune will one day turn the tide of battle against every pilot. Retreat is sometimes a necessity.

The Emergency Witchspace Initiator makes the interminable delay between deciding to retreat and the actual act a little quicker. By allowing certain 'safety guidelines' to be optimized, the EWI-OS-5141 is able to lessen the time needed for the hyperspace motors to 'spin up'. This can be a decrease of 50% of the normal spin-time required. Vital seconds during an emergency.

My legal team however would like me to add the following statement: ''Deep Horizon Industries would like to remind all customers that all safety guidelines published by GALCOP are there for your protection. Bypassing or eliminating such protocols may result in misjumps, faulty navigation calculations, damage to ship systems, wasted fuel, and other side-effects. Deep Horizon Industries is not responsible for any undesirable outcomes from use of this product including, but not limited to, death by Thargoid.''

== Large Slow Ships ==
Some large, slow-moving ships (such as the [[Anaconda (Oolite)|Anaconda]]) may not be able to complete reorientation before completion of the normal hyperspace countdown timer. This is a known issue. We decided that accelerating the reorientation any more than current would ruin the illusion of size of such large vessels. So instead, we are allowing this 'bug' to exist for this release, and may address it in a future release of this OXP.

== Equipment List ==
*Akai Stella Automated Transport Routing Unit: Plots wormhole entry and exit event horizons in conjunction with Witchspace Navigation Beacons:
*Dynamic Response Uridium Injection Dilator: Dynamically alters uridium injection into the drive initiator housing during exit sequence.
*Proton Anti-Gaussing Anisotropy Neutraliser: Re-stabilizes the proton-focusing crystal in the drive unit's anti-gaussing field destabilizer into an isotrophic state.
*Std. Heisenberg Atemporal Muon-Ambiplasma Navigation: Ensures asynchronous temporal wormhole exit by destabilising the witchspace exit meniscus only after the ship has entered the wormhole using ambiplasma-derived muons.
*Witchspace Initiator Chromo-Channel Accelerator: Accelerates particles in the quantum chromodynamics channel to initiate a witchspace jump.

== License ==
*CC-BY-NC-ND 3.0
*Authors: [[User:Cmd. Cheyd|Cmd. Cheyd]] & Phantorgorth
*Contributors: [[User:Svengali|Svengali]], Submersible & [[User:Phkb|Phkb]]

== Version History ==
*Version 1.0.5: Minor patch designating farpoint marker as unpiloted.
*Version 1.0.4: ANC will now disengage if auto-docking is started during a jump countdown.
*Version 1.0.3: Jump markers were not being removed if jump countdown was aborted by the player in some situations.
*Version 1.0.2: A couple of small bug fixes for "item is null" errors. Adjusted function names to remove them from the global namespace.
*Version 1.0.1: Updated to work with ANA navigation plotting introduced in 1.82.

== Links ==
*[http://aegidian.org/bb/viewtopic.php?f=4&t=13526 BB Thread] (2013+)
*[http://deephorizonindustries.com/ Deep Horizon industries]
*[[Hyperspace|witchspace]]

== Gameplay and Balance Indicator ==
[[File:Tag-colour-green.png|right]]
If one is attacked waiting to enter Witchspace, there are complications! Unsure that they warrant an orange rating.

{{Equipment-OXP}}

Traffic Control OXP

2021-07-13T03:59:03Z

Milo:

==Overview==
A little script which gives each system main station a traffic control department, whose job it is to guide new Commanders (and a few old hands who have become too reliant on docking computers) on the best route for manual approach and docking into the station. They oversee all traffic from station aegis and planetary approach right up until the actual docking itself. Also they keep an eye on ships leaving the station and wish people a bon voyage. Just don't dally in the approach lane and get in everyone's way, or you'll feel their wrath!

Recommended for new players learning how to dock manually, and for experienced players who want a bit of extra ambience around main stations. It is fully integrated with the docking clearance protocols introduced in Oolite 1.72 (if the stations enable them). Most messages from this OXP will appear only if your ship does not have functional docking computers, but a few will appear regardless, for example: Clear the lane, Commander! If you see a message that starts with 'Traffic Control:' then it is probably from this OXP.

In terms of balance, this OXP is neutral for beginners and slightly biased against the experienced player, because it enforces (with fines and small but escalating bounties) a sensible rule against the use of cloaking devices in proximity to main stations... however, to be fair, it will not impose any penalties if you pass undetected (or at least unidentified). Of course, requesting docking clearance or activating docking computers will transmit your identity to the station...

This OXP is compatible with all other OXPs, and includes considerations for Buoy Repair, ILS and AutoDock if those OXPs are also installed.

==Requirements==
This OXP requires at least version 1.88 of Oolite.

The traffic controllers also assume that any Commander's ship equipped with Docking Computers can look after itself in terms of approach and docking.

==Version History==
<pre>
09/10/2008 - Version 1.00, Initial release.
04/11/2008 - Version 1.01, scripting update for v1.72+ compatibility.
24/05/2010 - Version 1.10, fortified equipment damage checking for 1.74
13/02/2011 - Version 1.11, removal of upper limit, to allow running with 1.75
08/07/2020 - Version 2.00, updated by Milo; set minimum Oolite version to 1.88;
*fixed errors if navigation buoy is destroyed;
*corrected planet approach guidance (follow green circle, not square, if ship has a basic compass);
*added additional hints for new players (until they buy docking computers);
*set up recurring reminders to "clear the lane" when not supposed to be there;
*integrated docking advice with docking clearance protocol for main stations that require clearance;
*added warning messages to fugitive players entering station aegis or requesting docking clearance;
*Cloaking Devices: added responses to being detected using cloaking devices in the station aegis (this OXP now declares it illegal to cloak within main station aegis and introduces a small bounty for the first offence, which will be increased for non-fugitive players each time they are detected still cloaked after the initial offence; however, entering the aegis cloaked and never interacting with the station will not impose a penalty as the traffic controllers are unaware of the trespass); added a 1000 credit fine (or equivalent bounty) to the arrival report when docking at main stations while cloaked (even if fast-docking is used);
*added considerations for nova systems (traffic control will leave a recording when sun has gone nova) and for Buoy Repair, ILS and AutoDock OXPs
07/11/2021 - Version 2.01, updated by Milo; fix bug reported by dybal (docking clearance "granted" status was not correctly detected, resulting in unintended behavior, particularly noticeable when combined with ILS OXP)
</pre>

==Download==
The latest version, [[Media:Oolite.oxp.Thargoid.TrafficControl.2.01.oxz|Traffic Control v2.01]], can be downloaded from the wiki by clicking on the link.

An older version, [http://www.box.com/shared/qah2zp7sq2 '''Traffic Control v1.11'''], can be downloaded from Box.Net by clicking on the link.

==Links==
*[[User:Thargoid|Thargoid's OXP page]].
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20180 BB Thread] (2019-20)
*[http://www.aegidian.org/bb/viewtopic.php?p=59662#p59662 Original thread] (2008)

[[File:Tag-colour-blue.png]]{{OXPLevel|0}}
{{mechanics-OXP}}

File:Oolite.oxp.Thargoid.TrafficControl.2.01.oxz

2021-07-13T03:56:12Z

Milo:

Traffic Control OXP

2021-07-12T00:42:12Z

Milo:

==Overview==
A little script which gives each system main station a traffic control department, whose job it is to guide new Commanders (and a few old hands who have become too reliant on docking computers) on the best route for manual approach and docking into the station. They oversee all traffic from station aegis and planetary approach right up until the actual docking itself. Also they keep an eye on ships leaving the station and wish people a bon voyage. Just don't dally in the approach lane and get in everyone's way, or you'll feel their wrath!

Recommended for new players learning how to dock manually, and for experienced players who want a bit of extra ambience around main stations. It is fully integrated with the docking clearance protocols introduced in Oolite 1.72 (if the stations enable them). Most messages from this OXP will appear only if your ship does not have functional docking computers, but a few will appear regardless, for example: Clear the lane, Commander! If you see a message that starts with 'Traffic Control:' then it is probably from this OXP.

In terms of balance, this OXP is neutral for beginners and slightly biased against the experienced player, because it enforces (with fines and small but escalating bounties) a sensible rule against the use of cloaking devices in proximity to main stations... however, to be fair, it will not impose any penalties if you pass undetected (or at least unidentified). Of course, requesting docking clearance or activating docking computers will transmit your identity to the station...

This OXP is compatible with all other OXPs, and includes considerations for Buoy Repair, ILS and AutoDock if those OXPs are also installed.

==Requirements==
This OXP requires at least version 1.88 of Oolite.

The traffic controllers also assume that any Commander's ship equipped with Docking Computers can look after itself in terms of approach and docking.

==Version History==
<pre>
09/10/2008 - Version 1.00, Initial release.
04/11/2008 - Version 1.01, scripting update for v1.72+ compatibility.
24/05/2010 - Version 1.10, fortified equipment damage checking for 1.74
13/02/2011 - Version 1.11, removal of upper limit, to allow running with 1.75
08/07/2020 - Version 2.00, updated by Milo; set minimum Oolite version to 1.88;
*fixed errors if navigation buoy is destroyed;
*corrected planet approach guidance (follow green circle, not square, if ship has a basic compass);
*added additional hints for new players (until they buy docking computers);
*set up recurring reminders to "clear the lane" when not supposed to be there;
*integrated docking advice with docking clearance protocol for main stations that require clearance;
*added warning messages to fugitive players entering station aegis or requesting docking clearance;
*Cloaking Devices: added responses to being detected using cloaking devices in the station aegis (this OXP now declares it illegal to cloak within main station aegis and introduces a small bounty for the first offence, which will be increased for non-fugitive players each time they are detected still cloaked after the initial offence; however, entering the aegis cloaked and never interacting with the station will not impose a penalty as the traffic controllers are unaware of the trespass); added a 1000 credit fine (or equivalent bounty) to the arrival report when docking at main stations while cloaked (even if fast-docking is used);
*added considerations for nova systems (traffic control will leave a recording when sun has gone nova) and for Buoy Repair, ILS and AutoDock OXPs
07/11/2021 - Version 2.01, updated by Milo; fix bug reported by dybal (docking clearance "granted" status was not correctly detected, resulting in unintended behavior, particularly noticeable when combined with ILS OXP)
</pre>

==Download==
The latest version, [[Media:Oolite.oxp.Thargoid.TrafficControl.2.0.1.oxz|Traffic Control v2.0.1]], can be downloaded from the wiki by clicking on the link.

An older version, [http://www.box.com/shared/qah2zp7sq2 '''Traffic Control v1.11'''], can be downloaded from Box.Net by clicking on the link.

==Links==
*[[User:Thargoid|Thargoid's OXP page]].
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20180 BB Thread] (2019-20)
*[http://www.aegidian.org/bb/viewtopic.php?p=59662#p59662 Original thread] (2008)

[[File:Tag-colour-blue.png]]{{OXPLevel|0}}
{{mechanics-OXP}}

Traffic Control OXP

2021-07-12T00:41:47Z

Milo: version 2.01

==Overview==
A little script which gives each system main station a traffic control department, whose job it is to guide new Commanders (and a few old hands who have become too reliant on docking computers) on the best route for manual approach and docking into the station. They oversee all traffic from station aegis and planetary approach right up until the actual docking itself. Also they keep an eye on ships leaving the station and wish people a bon voyage. Just don't dally in the approach lane and get in everyone's way, or you'll feel their wrath!

Recommended for new players learning how to dock manually, and for experienced players who want a bit of extra ambience around main stations. It is fully integrated with the docking clearance protocols introduced in Oolite 1.72 (if the stations enable them). Most messages from this OXP will appear only if your ship does not have functional docking computers, but a few will appear regardless, for example: Clear the lane, Commander! If you see a message that starts with 'Traffic Control:' then it is probably from this OXP.

In terms of balance, this OXP is neutral for beginners and slightly biased against the experienced player, because it enforces (with fines and small but escalating bounties) a sensible rule against the use of cloaking devices in proximity to main stations... however, to be fair, it will not impose any penalties if you pass undetected (or at least unidentified). Of course, requesting docking clearance or activating docking computers will transmit your identity to the station...

This OXP is compatible with all other OXPs, and includes considerations for Buoy Repair, ILS and AutoDock if those OXPs are also installed.

==Requirements==
This OXP requires at least version 1.88 of Oolite.

The traffic controllers also assume that any Commander's ship equipped with Docking Computers can look after itself in terms of approach and docking.

==Version History==
<pre>
09/10/2008 - Version 1.00, Initial release.
04/11/2008 - Version 1.01, scripting update for v1.72+ compatibility.
24/05/2010 - Version 1.10, fortified equipment damage checking for 1.74
13/02/2011 - Version 1.11, removal of upper limit, to allow running with 1.75
08/07/2020 - Version 2.00, updated by Milo; set minimum Oolite version to 1.88;
*fixed errors if navigation buoy is destroyed;
*corrected planet approach guidance (follow green circle, not square, if ship has a basic compass);
*added additional hints for new players (until they buy docking computers);
*set up recurring reminders to "clear the lane" when not supposed to be there;
*integrated docking advice with docking clearance protocol for main stations that require clearance;
*added warning messages to fugitive players entering station aegis or requesting docking clearance;
*Cloaking Devices: added responses to being detected using cloaking devices in the station aegis (this OXP now declares it illegal to cloak within main station aegis and introduces a small bounty for the first offence, which will be increased for non-fugitive players each time they are detected still cloaked after the initial offence; however, entering the aegis cloaked and never interacting with the station will not impose a penalty as the traffic controllers are unaware of the trespass); added a 1000 credit fine (or equivalent bounty) to the arrival report when docking at main stations while cloaked (even if fast-docking is used);
*added considerations for nova systems (traffic control will leave a recording when sun has gone nova) and for Buoy Repair, ILS and AutoDock OXPs
07/11/2021 - Version 2.01, updated by Milo; fix bug reported by dybal (docking clearance "granted" status was not correctly detected, resulting in unintended behavior, particularly noticeable when combined with ILS OXP)
</pre>

==Download==
http://wiki.alioth.net/img_auth.php/3/38/Oolite.oxp.Thargoid.TrafficControl.2.0.1.oxz
The latest version, [[Media:Oolite.oxp.Thargoid.TrafficControl.2.0.1.oxz|Traffic Control v2.0.1]], can be downloaded from the wiki by clicking on the link.

An older version, [http://www.box.com/shared/qah2zp7sq2 '''Traffic Control v1.11'''], can be downloaded from Box.Net by clicking on the link.

==Links==
*[[User:Thargoid|Thargoid's OXP page]].
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20180 BB Thread] (2019-20)
*[http://www.aegidian.org/bb/viewtopic.php?p=59662#p59662 Original thread] (2008)

[[File:Tag-colour-blue.png]]{{OXPLevel|0}}
{{mechanics-OXP}}

File:Oolite.oxp.Thargoid.TrafficControl.2.0.1.oxz

2021-07-12T00:38:57Z

Milo:

File:Oolite.oxp.LittleBear.RandomStationNames.0.0.2.oxz

2020-08-05T20:57:17Z

Milo: 0.0.2 update

0.0.2 update

File:Oolite.oxp.LittleBear.RandomStationNames.0.0.1.oxz

2020-07-28T03:50:18Z

Milo: version 0.0.1

version 0.0.1

File:Oolite.oxp.Thargoid.Pods.1.48.oxz

2020-07-12T05:34:31Z

Milo: update by Milo

update by Milo

Pods OXP

2020-07-12T05:34:05Z

Milo: 1.48 update

==Overview==
A general expansion to the Ooniverse, this OXP introduces a number of new [[Cargo Container (Oolite)|cargo pod]] variations. Some are nice, some less so...

==New Pods==
* Standard containers - some more descriptive variants on the standard 1t cargo pods.
* Bulk container - larger capacity pod, featuring up to 10 tons of cargo, 100 kilos of metals (gold/platinum) or 200 grammes of gem-stones.
* Missile pod - again exactly what it says, a missile that can be scooped and added to your arsenal (if you have a free pylon). Usually standard missiles, but sometimes ECM hardened ones for the lucky commander. If scooper not have a free pylon. Then a missile pod will scooped as firearms. If you have a free pylon and it has been scooped missile pod to the cargo hold. If you like, so you can dumping a firearms and scooped for mount to pylon.
* Fuel pod - similar in nature to the external fuel tank, a pod which can carry up to 3.0 ly of witchspace fuel for your thirsty tanks. Occasionally the fuel has been known to be contaminated, requiring a tank purge.
* Piggybank pod - some poor soul's personal effects, including their life savings of up to 1000 credits.
* Empty pod - exactly what it says, either an empty pod or one full of worthless content.
* Trumble pod - pod containing everyone's favourite burger ingredient.
* Retry pod - a little annoyance, a pod that doesn't quite scoop right. If all else fails, try try again...
* Jam pod - no, not a pod full of jam, but when a pod tries to go through a fuel scoop sideways. Pod jams in the scoop, rendering it inoperable until a friendly tech can apply a pry-bar to it in dry-dock.
* Exploding pod - pod explodes within the ship's shields during scooping. Energy damage done to the ship, and fuel scoops destroyed.
* Breach pod - pod explodes in hold, causing hull breach. Some cargo may be vented before breach can be repaired.

==OXP Pods==
These are now included within the main pods OXZ (no additional add-on OXP is needed any more). If you have [[UPS Courier]], [[Cargo Wreck Teaser OXP|Cargo Wreck Teaser]] and Svengali [[CCL|Cabal Common Library]] v1.7.1 installed, then some of the cargopods should be from Pods.

== Technical Information ==

This OXP requires at least version 1.79 of Oolite.

===Download===
[[Media:oolite.oxp.Thargoid.Pods.1.48.oxz|Pods 1.48]] ({{#downloads:oolite.oxp.Thargoid.Pods.1.48.oxz}} downloads).

Old versions:
[[Media:Pods.oxz|Pods 1.46]] ({{#downloads:Pods.oxz}} downloads).
[[Media:Pods_1.35.oxz|Pods 1.35]] ({{#downloads:Pods_1.35.oxz}} downloads).

===License===
This work is licensed under the Creative Commons Attribution - Non-Commercial - Share Alike 3.0 license with clauses - see readme file.

=== Version History ===
19/08/2008 - Version 0.20, Beta-test release version.
22/08/2008 - version 1.00, Full release, now with Trumble, piggybank, breach and exploding pods added.
31/08/2008 - version 1.01, minor bug fix for the fuel pods fuel leak.
04/11/2008 - Version 1.02, scripting update for compatability with v1.72.
09/04/2009 - Version 1.03, script tidy-up to prevent error for awarding cargo when hold full. Also tweaked trumblepod.
01/11/2009 - Version 1.10, update to add scanclass and some new roles to the pods.
18/03/2010 - Version 1.20, update for v1.74 (not compatible with lower versions).
13/02/2011 - Version 1.21, removal of upper limit, to allow running with 1.75
19/02/2011 - Version 1.22, correction of Manifest / manifest script glitch
10/07/2012 - Version 1.30, merged pods and pods_UPS into one, and updated breachpod script (thanks to Eric W). Also added new variants for the standard 1t pods.
10/12/2012 - Version 1.31, fixed a few case sensitivity issues for non-Windows OS's.
12/12/2012 - Version 1.32, and a few more I missed before.
22/12/2012 - Version 1.33, sorted out some [%I] references in description.plist (again thanks Eric!).
20/01/2013 - Version 1.34, fixed a couple more references I missed last time (yet again thanks to Eric).
07/02/2013 - Version 1.35, added a rogue "s" back into the big kg script (thanks to Plisken for that one!).

12/09/2017 - Version 1.36 : update for oolite v1.79 - cag and rustem.
- Added logging for error cargo type in pods_standardPod.js.
- Edited name of the cargo type in description.plist and script for pods_standardPod.
- Edited the scripts: correct name decsriptions, sometimes increased time for display consoleMessage.
- Edited the shipdata: for pods_emptyBarrel (and pods_UPS_emptyBarrel) decreased value role of the cargopod from 0.1(0.12) to 0.005.
- Edited the shipdata: for pods_missileBarrel decreased value role of the cargopod from 0.05 to 0.005.
- Edited the shipdata: for all standart pods decreased value role of the cargopod from 0.5 to 0.05.
- Added damage sounds to Jam, Exploding and Breach pods.

14/09/2017 - Version 1.37, updated by Rustem
- Added "use strict" in the scripts.
- Improvement of damage sound effect for the correspond pods (thanks cag!).
- Add time interval for display consoleMessage of Jam pod (again thanks cag!).

19/09/2017 - Version 1.38, updated by Rustem
- Fixed: replaced hasScoopMessages on the has_scoop_message in the shipdata.
- Added no has_scoop_message to: fuelPod, emptyPod, retryPod, jamPod, missilePod, explodingPod, trumblePod (and UPS version also).

23/10/2017 - Version 1.39, updated by Rustem
- Added worldScript for storing all the resources. Added timer for exploding and breach pods (thanks cag!).
- Added group roles as brokenpod, bigpod, dampod for application in the other OXPs. Added group role names from UPS Courier OXP.
- Rebalanced role weights.
- New calculation of the credits for piggybank pod.

27/10/2017 - Version 1.40, updated by Rustem
- Resorting and optimization by template pods in the shipdata.plist.
- Added cargopod(hexapod) from CargoWreck OXP like external dependency as broken pods.
- Edited group role names for standart pods.

30/10/2017 - Version 1.41, updated by Rustem
- Added big pod(ccl_crateA) and broken pods(ccl_crateB) for cargopod from Svengali CCL OXP like external dependency.
- Added model scale factor to big pods.
- Fixed shipdata bug for external pods.

18/11/2017 - Version 1.42, updated by Rustem
- Added a routine for checking a setCargo by other OXPs and etc.
- Added logging condition in the pod ship.script.

21/11/2017 - Version 1.43, updated by Rustem
- Code refactoring: released an one script for Bulk container with NPC-scooping feature.
- Added a routine for checking a shipUniqueName for renew of the pod name (for cargo scanner).
- Modified the missilePod script for player-rescooping.
- Upgraded all scripts for NPC-scooping.

01/12/2017 - Version 1.44, updated by Rustem
- Added description for communicate.
- Fixed bug in the addition cargo to NPC.
- Code refactoring.

16/12/2018 - Version 1.45, updated by Rustem
- Logging is off.
- Formatted the JS code: scripts.
- Fixed ship script for trumble pod (a TypeError for player.awardEquipment in pods_standardPod-1t, pods_trumblePod).
- Tweaks in shipdata.plist, adds a materials for missilePod, adds a standartpod role.
- Upgraded a scripts for trumblePod.

20/12/2018 - Version 1.46, updated by Rustem
- Adds cargopods from the Griff Cargopods OXP as standart pod and piggybank pod.
- Reduce chance to award a trumble in the trumble pod.
- Code refactoring of the trumblepod-scooping.

10/07/2020 - Version 1.47, updated by Milo
- Fixed errors in the scripts for the breach pod, jam pod, and exploding pod.

12/07/2020 - Version 1.48, updated by Milo
- Fixed another error in the script for the exploding pod.

===Links===
*[[User:Thargoid|Thargoid's OXP page]]

==Quick Facts==
{{OXPLevel|0}}{{Infobox OXPb| title = Pods
|version = 1.48
|release = 2020-07-12
|features = New cargo pods and pod features
|license = CC BY-NC-SA 3
|category = Mechanics OXPs
|author = [[User:Thargoid|Thargoid]], [[User:Rustem|Rustem]] (maintainer), [[User:Milo|Milo]] (maintainer)
|download = [[Media:oolite.oxp.Thargoid.Pods.1.47.oxz|Download]]
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=4952 BB-Link]
}}

== Gameplay and Balance indicator ==
[[File:Tag-colour-orange.png]]

{{mechanics-OXP}}

File:Oolite.oxp.NewtSoup.MiningIFFScannerUpgrade.1.1.3.oxz

2020-07-10T19:27:11Z

Milo: Update by Milo

Update by Milo

File:Oolite.oxp.Thargoid.Pods.1.47.oxz

2020-07-10T19:05:39Z

Milo: Update by Milo

Update by Milo

Pods OXP

2020-07-10T19:04:58Z

Milo: Pods 1.47 update

==Overview==
A general expansion to the Ooniverse, this OXP introduces a number of new [[Cargo Container (Oolite)|cargo pod]] variations. Some are nice, some less so...

==New Pods==
* Standard containers - some more descriptive variants on the standard 1t cargo pods.
* Bulk container - larger capacity pod, featuring up to 10 tons of cargo, 100 kilos of metals (gold/platinum) or 200 grammes of gem-stones.
* Missile pod - again exactly what it says, a missile that can be scooped and added to your arsenal (if you have a free pylon). Usually standard missiles, but sometimes ECM hardened ones for the lucky commander. If scooper not have a free pylon. Then a missile pod will scooped as firearms. If you have a free pylon and it has been scooped missile pod to the cargo hold. If you like, so you can dumping a firearms and scooped for mount to pylon.
* Fuel pod - similar in nature to the external fuel tank, a pod which can carry up to 3.0 ly of witchspace fuel for your thirsty tanks. Occasionally the fuel has been known to be contaminated, requiring a tank purge.
* Piggybank pod - some poor soul's personal effects, including their life savings of up to 1000 credits.
* Empty pod - exactly what it says, either an empty pod or one full of worthless content.
* Trumble pod - pod containing everyone's favourite burger ingredient.
* Retry pod - a little annoyance, a pod that doesn't quite scoop right. If all else fails, try try again...
* Jam pod - no, not a pod full of jam, but when a pod tries to go through a fuel scoop sideways. Pod jams in the scoop, rendering it inoperable until a friendly tech can apply a pry-bar to it in dry-dock.
* Exploding pod - pod explodes within the ship's shields during scooping. Energy damage done to the ship, and fuel scoops destroyed.
* Breach pod - pod explodes in hold, causing hull breach. Some cargo may be vented before breach can be repaired.

==OXP Pods==
These are now included within the main pods OXZ (no additional add-on OXP is needed any more). If you have [[UPS Courier]], [[Cargo Wreck Teaser OXP|Cargo Wreck Teaser]] and Svengali [[CCL|Cabal Common Library]] v1.7.1 installed, then some of the cargopods should be from Pods.

== Technical Information ==

This OXP requires at least version 1.79 of Oolite.

===Download===
[[Media:oolite.oxp.Thargoid.Pods.1.47.oxz|Pods 1.47]] ({{#downloads:oolite.oxp.Thargoid.Pods.1.47.oxz}} downloads).

Old versions:
[[Media:Pods.oxz|Pods 1.46]] ({{#downloads:Pods.oxz}} downloads).
[[Media:Pods_1.35.oxz|Pods 1.35]] ({{#downloads:Pods_1.35.oxz}} downloads).

===License===
This work is licensed under the Creative Commons Attribution - Non-Commercial - Share Alike 3.0 license with clauses - see readme file.

=== Version History ===
19/08/2008 - Version 0.20, Beta-test release version.
22/08/2008 - version 1.00, Full release, now with Trumble, piggybank, breach and exploding pods added.
31/08/2008 - version 1.01, minor bug fix for the fuel pods fuel leak.
04/11/2008 - Version 1.02, scripting update for compatability with v1.72.
09/04/2009 - Version 1.03, script tidy-up to prevent error for awarding cargo when hold full. Also tweaked trumblepod.
01/11/2009 - Version 1.10, update to add scanclass and some new roles to the pods.
18/03/2010 - Version 1.20, update for v1.74 (not compatible with lower versions).
13/02/2011 - Version 1.21, removal of upper limit, to allow running with 1.75
19/02/2011 - Version 1.22, correction of Manifest / manifest script glitch
10/07/2012 - Version 1.30, merged pods and pods_UPS into one, and updated breachpod script (thanks to Eric W). Also added new variants for the standard 1t pods.
10/12/2012 - Version 1.31, fixed a few case sensitivity issues for non-Windows OS's.
12/12/2012 - Version 1.32, and a few more I missed before.
22/12/2012 - Version 1.33, sorted out some [%I] references in description.plist (again thanks Eric!).
20/01/2013 - Version 1.34, fixed a couple more references I missed last time (yet again thanks to Eric).
07/02/2013 - Version 1.35, added a rogue "s" back into the big kg script (thanks to Plisken for that one!).

12/09/2017 - Version 1.36 : update for oolite v1.79 - cag and rustem.
- Added logging for error cargo type in pods_standardPod.js.
- Edited name of the cargo type in description.plist and script for pods_standardPod.
- Edited the scripts: correct name decsriptions, sometimes increased time for display consoleMessage.
- Edited the shipdata: for pods_emptyBarrel (and pods_UPS_emptyBarrel) decreased value role of the cargopod from 0.1(0.12) to 0.005.
- Edited the shipdata: for pods_missileBarrel decreased value role of the cargopod from 0.05 to 0.005.
- Edited the shipdata: for all standart pods decreased value role of the cargopod from 0.5 to 0.05.
- Added damage sounds to Jam, Exploding and Breach pods.

14/09/2017 - Version 1.37, updated by Rustem
- Added "use strict" in the scripts.
- Improvement of damage sound effect for the correspond pods (thanks cag!).
- Add time interval for display consoleMessage of Jam pod (again thanks cag!).

19/09/2017 - Version 1.38, updated by Rustem
- Fixed: replaced hasScoopMessages on the has_scoop_message in the shipdata.
- Added no has_scoop_message to: fuelPod, emptyPod, retryPod, jamPod, missilePod, explodingPod, trumblePod (and UPS version also).

23/10/2017 - Version 1.39, updated by Rustem
- Added worldScript for storing all the resources. Added timer for exploding and breach pods (thanks cag!).
- Added group roles as brokenpod, bigpod, dampod for application in the other OXPs. Added group role names from UPS Courier OXP.
- Rebalanced role weights.
- New calculation of the credits for piggybank pod.

27/10/2017 - Version 1.40, updated by Rustem
- Resorting and optimization by template pods in the shipdata.plist.
- Added cargopod(hexapod) from CargoWreck OXP like external dependency as broken pods.
- Edited group role names for standart pods.

30/10/2017 - Version 1.41, updated by Rustem
- Added big pod(ccl_crateA) and broken pods(ccl_crateB) for cargopod from Svengali CCL OXP like external dependency.
- Added model scale factor to big pods.
- Fixed shipdata bug for external pods.

18/11/2017 - Version 1.42, updated by Rustem
- Added a routine for checking a setCargo by other OXPs and etc.
- Added logging condition in the pod ship.script.

21/11/2017 - Version 1.43, updated by Rustem
- Code refactoring: released an one script for Bulk container with NPC-scooping feature.
- Added a routine for checking a shipUniqueName for renew of the pod name (for cargo scanner).
- Modified the missilePod script for player-rescooping.
- Upgraded all scripts for NPC-scooping.

01/12/2017 - Version 1.44, updated by Rustem
- Added description for communicate.
- Fixed bug in the addition cargo to NPC.
- Code refactoring.

16/12/2018 - Version 1.45, updated by Rustem
- Logging is off.
- Formatted the JS code: scripts.
- Fixed ship script for trumble pod (a TypeError for player.awardEquipment in pods_standardPod-1t, pods_trumblePod).
- Tweaks in shipdata.plist, adds a materials for missilePod, adds a standartpod role.
- Upgraded a scripts for trumblePod.

20/12/2018 - Version 1.46, updated by Rustem
- Adds cargopods from the Griff Cargopods OXP as standart pod and piggybank pod.
- Reduce chance to award a trumble in the trumble pod.
- Code refactoring of the trumblepod-scooping.

10/07/2020 - Version 1.47, updated by Milo
- Fixed errors in the scripts for the breach pod, jam pod, and exploding pod.

===Links===
*[[User:Thargoid|Thargoid's OXP page]]

==Quick Facts==
{{OXPLevel|0}}{{Infobox OXPb| title = Pods
|version = 1.47
|release = 2018-12-20
|features = New cargo pods and pod features
|license = CC BY-NC-SA 3
|category = Mechanics OXPs
|author = [[User:Thargoid|Thargoid]], [[User:Rustem|Rustem]] (maintainer), [[User:Milo|Milo]] (maintainer)
|download = [[Media:oolite.oxp.Thargoid.Pods.1.47.oxz|Download]]
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=4952 BB-Link]
}}

== Gameplay and Balance indicator ==
[[File:Tag-colour-orange.png]]

{{mechanics-OXP}}

Traffic Control OXP

2020-07-09T02:49:12Z

Milo: more detailed description

==Overview==
A little script which gives each system main station a traffic control department, whose job it is to guide new Commanders (and a few old hands who have become too reliant on docking computers) on the best route for manual approach and docking into the station. They oversee all traffic from station aegis and planetary approach right up until the actual docking itself. Also they keep an eye on ships leaving the station and wish people a bon voyage. Just don't dally in the approach lane and get in everyone's way, or you'll feel their wrath!

Recommended for new players learning how to dock manually, and for experienced players who want a bit of extra ambience around main stations. It is fully integrated with the docking clearance protocols introduced in Oolite 1.72 (if the stations enable them). Most messages from this OXP will appear only if your ship does not have functional docking computers, but a few will appear regardless, for example: Clear the lane, Commander! If you see a message that starts with 'Traffic Control:' then it is probably from this OXP.

In terms of balance, this OXP is neutral for beginners and slightly biased against the experienced player, because it enforces (with fines and small but escalating bounties) a sensible rule against the use of cloaking devices in proximity to main stations... however, to be fair, it will not impose any penalties if you pass undetected (or at least unidentified). Of course, requesting docking clearance or activating docking computers will transmit your identity to the station...

This OXP is compatible with all other OXPs, and includes considerations for Buoy Repair, ILS and AutoDock if those OXPs are also installed.

==Requirements==
This OXP requires at least version 1.88 of Oolite.

The traffic controllers also assume that any Commander's ship equipped with Docking Computers can look after itself in terms of approach and docking.

==Version History==
<pre>
09/10/2008 - Version 1.00, Initial release.
04/11/2008 - Version 1.01, scripting update for v1.72+ compatibility.
24/05/2010 - Version 1.10, fortified equipment damage checking for 1.74
13/02/2011 - Version 1.11, removal of upper limit, to allow running with 1.75
08/07/2020 - Version 2.00, updated by Milo; set minimum Oolite version to 1.88; fixed errors if navigation buoy is destroyed; corrected planet approach guidance (follow green circle, not square, if ship has a basic compass); added additional hints for new players (until they buy docking computers); set up recurring reminders to "clear the lane" when not supposed to be there; integrated docking advice with docking clearance protocol for main stations that require clearance; added warning messages to fugitive players entering station aegis or requesting docking clearance; added responses to being detected using cloaking devices in the station aegis (this OXP now declares it illegal to cloak within main station aegis and introduces a small bounty for the first offence, which will be increased for non-fugitive players each time they are detected still cloaked after the initial offence; however, entering the aegis cloaked and never interacting with the station will not impose a penalty as the traffic controllers are unaware of the trespass); added a 1000 credit fine (or equivalent bounty) to the arrival report when docking at main stations while cloaked (even if fast-docking is used); added considerations for nova systems (traffic control will leave a recording when sun has gone nova) and for Buoy Repair, ILS and AutoDock OXPs
</pre>

==Download==
The latest version, [[Media:Oolite.oxp.Thargoid.TrafficControl.2.0.0.oxz|Traffic Control v2.0.0]], can be downloaded from the wiki by clicking on the link.

The previous version, [http://www.box.com/shared/qah2zp7sq2 '''Traffic Control v1.11'''], can be downloaded from Box.Net by clicking on the link.

==Links==
*[[User:Thargoid|Thargoid's OXP page]].
{{mechanics-OXP}}

Traffic Control OXP

2020-07-09T02:41:36Z

Milo: Traffic Control 2.0.0 release

File:Oolite.oxp.Thargoid.TrafficControl.2.0.0.oxz

2020-07-09T02:35:30Z

Milo: Update by Milo

Update by Milo

File:Oolite.oxp.NewtSoup.MiningIFFScannerUpgrade.1.1.2.oxz

2020-07-09T00:50:05Z

Milo: Update by Milo

Update by Milo

Career Options

2020-07-08T18:57:40Z

Milo: /* OXP's to help with or enhance mining */ corrected link for Mining IFF Scanner Upgrade (it was linked to the freight train OXP thread)

Oolite is built specifically with no plot or overall mission in place. The only plot is what you, the pilot, bring to the game (aside from any mission OXP's you might have installed). The game doesn't tell you where to go, what to be, how to play - it's completely up to you...

...up to a point. Oolite does have limits in what it can allow you to do. For instance, there is no option (nor will there likely be one) to become a backyard landscaper or an accountant. But within the limits of the game, there is still a number of options available to you.

It should be noted that none of these careers are mutually exclusive to the others. For instance, it's possible to be a passenger ferry and opportunistic trader at the same time.

In each section there is a small list of OXP's that can help or enhance that career option. Please make sure you read all the documentation about these OXP's before you install them. There may be unexpected consequences from adding them. For instance, installing the Bounty System will change how your offender status is treated. These lists are not to be considered as some form of recommendation, or even a complete list of OXP's for each career. They are merely a starting point for finding OXP additions that might be suitable for that career in your play experience. The links will take you to the page that describes the OXP. Read this information carefully before you install the OXP.

For a full list of OXP's you can visit [http://oolite.org/oxps oolite.org/oxps], which lists all the OXP's that can be downloaded directly from within the game, or go to the [[OXP List]] which lists pretty much everything else.

==Trader==
Trading (the action of buying and selling [[Commodities|commodities]]) is the first career almost every pilot is likely to choose, as it provides the most expedient and predictable path to credits, but there are different types of trader. Here we'll look at the most prominent ones. For all trading careers, cargo space is critical - the more space you have, the more cargo you can buy/sell, and therefore the greater the profits. For a [[Cobra_Mk.3_(Oolite)|Cobra Mk III]], the default 20t of space is OK for when you're starting out, but it will soon feel small. The [[Cargo Bay Expansion]] (400cr from TL2 systems) will add an extra 15t, but even at 35t, you might find it difficult to do serious trading. Many players who pursue a trading career will find changing their ship to a [[Python_(Oolite)|Python]] (100t), [[Boa_(Oolite)|Boa]] (125t), [[Boa_2_Class_Cruiser|Boa Class Cruiser]] (175t) or an [[Anaconda_(Oolite)|Anaconda]] (750t), is an essential move as soon as sufficient funds are available for the purchase, and is all the more important if additional careers, like [[Career_Options#Passenger_Transporting|passenger transporting]], are pursued.

===Bulk Trader===
The logic is simple enough - buy lots of cargo at low prices, sell it for a higher price. Finding the best deals is the trickiest part of the process (other than getting to each station alive - that can be tricky too).

In most cases, though, the secret is finding systems with opposite economies, reasonably close together. A rich industrial (RI) close to a poor agricultural (PA) will provide the best profits: buying computers cheaply at the RI, selling them at the PA, then buying furs cheaply and selling them back at the RI. This is what's known as a "milk run", and there are tools out there to help you find them.

Swapping back and forth between two systems can be a little monotonous, so your other option is to find a trade route where a series of systems have opposite economies,

===Contract Trader===
This type of trader uses the [[Contracts#Cargo_Contracts|cargo contracts]] page to take on specific deliveries of cargo to specific systems, within a given timeframe. The benefits for this type of trader come when your reputation starts to increase. The better your reputation, the more profitable are the contracts that will be offered to you.

Once your reputation starts to increase, look for contracts on gold, platinum or gem-stones. Because of the much smaller cargo space requirement for these commodities, more contracts can be accepted on each run, meaning far larger profits at the other end.

If you lose part of your contracted cargo on route to the destination, don't fret. You can buy the difference at any station, and it will count towards the total amount. As long as you arrive at the destination with the right amount of cargo, you will complete the contract successfully.

Be aware of the impact of using an [[Escape_Pod|escape pod]]. A large amount of time can transpire between launching and getting back to the dock, which might have a bearing on any deadlines you have. Also, unless your cargo is gold, platinum or gem-stones, you will lose all your cargo when you eject. To complete the contract successfully you will need to repurchase all the stock from wherever you can find it. And even some gold, platinum and gem-stones could be lost, if their amounts are larger than 500kg for gold or platinum, or 1000g for gem-stones, as amounts over those values will take up cargo space, rather than being contained by the ship's safe, which is kept on the escape pod.

===Opportunistic Trader===
An opportunistic trader is one that only trades when a particular opportunity presents itself. Normally, an opportunistic trader is also doing something else (like being a courier or bounty hunter), so they won't be scouring the galaxy for the best deals. Rather they will pick up any cargo they find and sell it, or they might notice that computers are cheap, so they buy a few tons and then when they see a good sell price on their travels, get the profit then.

An opportunistic trader is looking to simply supplement other income with some money on the side. There is a benefit to doing some of this type of trading, even if your primary focus is something else - other traders will notice. The more trading you do, the more likely it is that other ships will consider you as a trader, which can have benefits in a skirmish where there are multiple sides. If another trader considers you to be a trader as well, they are more likely to fight with you.

A [[Fuel_Scoops|fuel scoop]] is almost a requirement for the opportunistic trader, particularly if you want to take advantage of any cargo left behind in space. Fuel scoops can be purchased in any TL6 system for 525cr.

===OXP's to help with or enhance trading===
* [[MarketObserver|Market Observer]] enhances the market screen with valuable data, like average prices and % differences.
* [[Market Inquirer]] adds an interface screen (f4) that shows the distances in system and an interface screen that shows the markets (prices and quantities) of the main station and selected stations closest to the player.
* [[In_System_Trader|In-System trader]] introduces a "living market" to systems with rewards and risks for in-system trading.
* [[Display Current Course]] adds your currently plotted course to any mission map screen, so you can tell whether the destination for the new mission is close to where you are currently heading.
* [[GalCop Galactic Registry]] gives pilots access to chart-wide system data, allowing them to quickly analyse routes and regions, which can aid in plotting trade routes.
* There are plenty of OXP ships that have increased cargo capacity. Check out the [[Largest_Ships_(Oolite)|Largest Ships]] list for some examples.

==Smuggling==
While this could be considered a variation on a trading career, the different play-style required to pursue this option really makes it quite separate.

Smuggling involves trading in illegal goods: slaves, firearms, and narcotics. You can freely dock at any station with these commodities on board, but if you launch your ship with any of them, you will be tagged as an offender, with the size of the penalty related to the amount and type of illegal goods you're carrying.

Illegal goods can sometimes have spectacular profits. Narcotics in particular can be bought in some systems for less than a single credit, and sold in others for over 100. However, these deals are hard to find.

Rock Hermits can provide safe places to dock, and they sometimes have good prices on illegal goods.

===OXP's to help with or enhance smuggling===
* Any of the additional station OXP's can provide extra docking options for smugglers. See the [http://wiki.alioth.net/index.php/Category:Dockables_OXPs Dockables] page for some examples.
* [[Smugglers - The Galactic Underworld]] introduces smuggling compartments, bribing docking authorities, while at the same time can potentially make any commodity illegal.
* [[Illegal_Goods_Tweak_OXP|Illegal Goods Tweak]] changes the way illegal goods are processed when you dock at stations.

==Courier==
Parcel couriers take small packages from one system to another for a given price. These opportunities are offered via the [[Contracts#Parcel_Contracts|parcel contracts]] page. As you complete more and more of these contracts, your reputation will increase and better contracts will be offered.

Because of their small size, there is no limit to the number of parcel contracts you can accept, if you believe you can deliver them on time. Parcels will be stored with your [[Escape_Pod|escape pod]] if you have one installed and are forced to eject. Be aware, though, that a lot of time can pass when an escape pod is used, which might make it hard (or even impossible) to reach the destinations on time.

The biggest threat to couriers are assassins. Sometimes, someone doesn't want a parcel delivered, and they will instruct assassins to hunt down and kill anyone attempting to do so. You will normally encounter these ships somewhere around the witchpoint of a system, where they lie in wait for targets. Assassins will generally have a "clean" status, which can cause complications with the police should a battle be observed by them. Depending on a number of factors, police may decide that you are the guilty party, not the assassin, and slap you with a bounty. The best advice in these situations is to (a) keep a watch for police ships when you get into a fight with assassins, and (b) if you see any, make sure the police can see the assassins shooting at you, and don't shoot at the assassins until they have shot and hit your ship.

Some courier contracts are more dangerous than others, but with careful observation it should become clear which contracts are likely to attract unwanted attention.

Speed is your friend, and many pilots who really pursue a courier career find changing their ship to something faster, like an [[Asp_(Oolite)|Asp]], can be beneficial. [[Witchdrive_Fuel_Injectors|Fuel Injectors]] are also a valuable piece of kit, enabling you to outrun many of the threats you will encounter.

===OXP's to help with or enhance courier contracts===
* [[Display Current Course]] adds your currently plotted course to any mission map screen, so you can tell whether the destination for the new mission is close to where you are currently heading.
* [[GalCop Galactic Registry]] gives pilots access to chart-wide system data, allowing them to quickly analyse routes and regions, which can aid in determining where dangerous routes might lie and how to avoid them.
* There are plenty of OXP ships that have a high maximum speed. Check out the [[Fastest_Ships_(Oolite)|Fastest Ships]] list for some examples.

==Passenger Transporting==
Passenger transporting involves taking sentient beings from one system to another. These opportunities are offered via the [[Contracts#Passenger_Contracts|passenger contracts]] page. In order to accept any passenger contract, you must have at least one free [[Passenger_Berth|passenger berth]], which can be purchased from any TL6 or greater system for 825cr. Each berth takes up 5t of cargo space.

As you complete passenger contracts, your reputation will increase, which will result in better contracts being offered.

Passengers will be auto-transferred to your escape pod in the event you are forced to use it. As noted above, be aware that a lot of time can pass when an escape pod is used, which might make it hard (or even impossible) to reach the destinations on time.

Assassins can also target particular passengers, so the advice for couriers applies here as well. Again, with careful observation it should become clear which contracts are likely to be the dangerous ones.

===OXP's to help with or enhance passenger contracts===
* [[Display Current Course]] adds your currently plotted course to any mission map screen, so you can tell whether the destination for the new mission is close to where you are currently heading.
* [[GalCop Galactic Registry]] gives pilots access to chart-wide system data, allowing them to quickly analyse routes and regions, which can aid in determining where dangerous routes might lie and how to avoid them.
* [[Taxi Galactica]] adds some additional specialised passenger contracts.
* [[In-System Taxi]] adds passenger contracts that are only for travel between stations in the current system.
* [[Enhanced Passenger Contracts]] adds some extra flavour to passenger contracts, with additional contract stipulations and in-game communications.

==Miner==
Mining asteroids involves first finding some, then shooting at the large ones to reduce them to boulders, then shooting the boulders to reduce them to splinters, and then scooping the splinters and selling the results. Two pieces of equipment are required: a [[Mining_Laser|mining laser]], which can be purchased in TL11 systems for 800cr, and a [[Fuel_Scoops|fuel scoop]], which can be purchased in TL6 systems for 525cr. You can technically use any laser to shoot the asteroids, but only a mining laser will reliably give you splinters to scoop.

Sometimes, the hardest part of the job is finding asteroids to shoot at. The planet-to-sun spacelane is probably your best starting point for searching.

Once you have some splinters scooped, your next task is selling them. Given you haven't spent any money getting them (other than the setup costs for your ship), you can sell them anywhere and get a profit. But mining is a slow process, so it's still in your best interests to do your mining in systems that have good prices on alloys and minerals.

===OXP's to help with or enhance mining===
* [[Asteroid Tweaks]] can help with ensuring there are always asteroids to mine.
* [[Ore Processor]] helps by refining them splinters as you scoop them
* [[Waypoint Here]] can help by letting you mark points in a system (for instance, where a large asteroid field is located) so you can easily find your way back.
* [http://aegidian.org/bb/viewtopic.php?f=4&t=19010 Mining IFF Scanner Upgrade] changes the colours of boulders and splinters on the scanner, making them easier to identify.
* [[Mining_Contracts_OXP|Mining Contracts]] offers contracts to players, in which they need to mine a certain quantity of minerals or alloys by a certain time.
* [[Miner Cobra]] is a ship set up specifically with mining in mind. It will be offered for sale at some stations.
* [[Start Choices]] give players the option of starting out in a ship set up for mining.
* [[Laser Mount Switching System]] helps overcome the issue of which mount will you place your mining laser, by allowing you to have a normal laser and a mining laser installed in one position, and then swapping between them during flight.
* [[Bulk Cargo Processor]] can help quickly get rid of worthless commodities that might be filling up your cargo hold.

==Bounty Hunter==
A bounty hunter tracks down and destroys ships that currently have a legal status of offender or fugitive. When the ship is destroyed, the bounty on that ship is paid to you. Identifying ships that have a bounty can be tricky, especially without the [[Scanner Targeting Enhancement]]. Look for groups of ships loitering on the witchpoint-to-planet spacelane - there is a high chance these ships will be pirates.

While a career in bounty hunting can be started at almost any time, it is highly advisable to have some upgraded attack and defence options on your ship: a beam laser, some shield and energy enhancements. It is also highly recommended that the Scanner Targeting Enhancement is purchased, as this can provide some crucial information to the HUD to help with identifying potential targets. The [[Scanner_Targeting_Enhancement|STE]] can be purchased from any TL12 system for 450cr.

===OXP's to help with or enhance bounty hunting===
* [[Bounty System]] introduces a Warrant Scanner, which can scan ships in search of any bounties those ships might have picked up in other systems.
* [[Random Hits]] adds "Seedy Space Bars" to Anarchy systems, and from these stations you can take on contract kills. You will be given a target, and be told where to find that target. Your job will be to travel to the destination, find the target and kill them.
* [[GalCop's Most Wanted]] is an addition to the [[Bounty System]] OXP, and adds persisent NPC ships that can be tracked around the chart. These NPC's have large bounties on their heads, so finding them can be quite rewarding. Note that the Bounty system changes the way bounties are recorded by making crimes persist (that is, your offender status will not degrade slowly with each jump).

==Pirate==
Piracy involves shooting at peaceful, clean-rated trading ships so that they dump some of their cargo for you to scoop. Completely destroying ships can also be profitable, especially larger trade-focused vessels like [[Python_(Oolite)|Pythons]], [[Boa_(Oolite)|Boas]] and [[Anaconda_(Oolite)|Anacondas]], as cargo will often float free of the wreck. In both cases, [[Fuel_Scoops|fuel scoops]] are essential in order to collect all of this drifting cargo. Fuel scoops can be purchased in any TL6 system for 525cr.

Theoretically, this career is open to players as soon as they start the game, as long as they're careful who they shoot at, but to have any chance at a long life as a pirate you really need an upgraded ship. Shields, energy banks, lasers, injectors, everything you can get your hands on really. A successful pirate is an "Iron-Assed" pirate.

Pirates usually get involved in [[Career_Options#Smuggling|smuggling]] activities, as illegal goods can fetch good prices, and are regularly left behind by fleeing traders.

The life of a pirate is a hard one. There aren't many "clean" pirates out there - the longer you pursue this life, the more likely it is you'll end up as an offender or a fugitive. This makes you a target for bounty hunters and police, and can make docking at a main station a tricky endeavour. Rock Hermits are your friends here, and learning how to find them will be one of the first things you will need to do. However, your bounty will decrease with each jump, so it will not take long to return to a "clean" state. Having a [[Fuel_Scoops|fuel scoop]] can be extremely valuable, as it can let you refuel your ship without needing to dock at the main station, simply by scooping fuel from the sun.

One of the benefits of being a pirate, is that pirates will be less likely to attack you, and may even side with you in a skirmish.

===OXP's to help with or enhance piracy===
* [[Manifest Scanner]] allows you to scan a target ship and see what cargo they have on board, to help with the decision-making process of whether to attack this ship or not.
* [[Rock Hermit Locator]] helps pilots find Rock Hermits in each system.
* [[Spicy Hermits]] makes Rock Hermits more interesting and worthwhile.
* [[BroadcastComms MFD]] has options to transmit a demand for cargo, which could avoid the need to send the same message with a laser.

==OXP Careers==
Many OXP's have sought to expand on existing career paths, or create entirely new ones, in order to deepen the game experience. What follows are some OXP's you might want to consider if you want to broaden the career options in your game.

===Rescue Stations===
[[RRS_Group|Rescue Stations]] adds the RRS stations to various safer systems, and offers a variety of rescue and recovery missions to the player.

===Galactic Navy Reservist===
If you have the ship for it (meaning, you’ve upgraded most of it), you can join the [[Galactic Navy]] reserves and participate in various sorties and SecOps missions. [[Thargoid Wars]] also gives you the opportunity to work with the Navy in their battles against the Thargoids.

===Salvage Operator===
A salvager looks for wrecked, derelict ships, then either tows them (using a [[Towbar]]), or attaches a drone to it, to get the hulk to a station or to a [[Deep Space Dredger]], where the derelict can be sold for parts and a worthwhile profit.

===Ship Escort Services===
Traders travelling to dangerous systems often need extra protection. [[Escort Contracts]] give players a chance to join a convoy and protect the mothership from all attackers, to see them safely to their destination.

[[Category:Oolite]]

Oolite JavaScript Reference: Mission

2020-06-29T18:24:34Z

Milo: /* runScreen */ fix link

'''Prototype:''' <code>Object</code> 
'''Subtypes:''' none

The '''mission''' global object is used to run mission screens, and perform other actions related to mission scripting.

== Properties ==

=== <code>displayModel</code> ===
'''displayModel''' : {{oojsclass|Ship}}
If currently running a mission screen with a <code>model</code>, the ship entity used to display the model. This can be animated by setting its position and orientation from a [[Oolite JavaScript Reference: Global#addFrameCallback|frame callback]]. Uses role to identify ship, so be sure to use a unique role if you want a specific ship to be showed.

=== <code>exitScreen</code> ===
{{oolite-prop-added|1.77}}
'''exitScreen''' : [[Oolite JavaScript Reference: Global#guiScreen|guiScreen]] (read/write)

This can be used to set a new exit screen for the current mission screen. Outside of a callback function, the value of this is meaningless, and setting it has no useful effect.

=== <code>markedSystems</code> ===
{{oolite-prop-added|1.77}}
'''markedSystems''' : Array (read-only)

An array of the objects currently being used to mark systems. The objects will have the same properties as those used by <code>markSystem</code> and <code>unmarkSystem</code>.

=== <code>screenID</code> ===
{{oolite-prop-added|1.77}}
'''screenID''' : String (read-only)

If there is currently a mission screen running, and it defined a screenID, then that screenID. Otherwise, this is null.

== Methods ==

=== <code>addMessageText</code> ===
function '''addMessageText'''(message : String)

Appends text to the currently running mission screen. Can also be used to add text to other screens like the system data (F7) screen.

=== <code>addMessageTextKey</code> ===
function '''addMessageTextKey'''(messageKey : String)

Like <code>[[#addMessageText|addMessageText()]]</code>, but looks up the specified <code>messageKey</code> in [[missiontext.plist]].

=== <code>markSystem</code> ===
function '''markSystem'''(systemNumber : Number)

Mark a system on the long range chart. Multiple systems may be marked at once, as in <code>mission.markSystem(4, 54, 222)</code>. In 1.76 and earlier a system cannot be marked twice, so:
mission.markSystem(7);
mission.markSystem(7);
mission.unmarkSystem(7);
will leave the system unmarked.

In 1.77 or later, the parameters may be objects instead of numbers. This allows control over the marker's appearance, and allows multiple markers to be placed on the same system. The object takes the following parameters:
* <code>system</code> : The system ID. This is the only required parameter.
* <code>name</code> : A string identifying the group this marker belongs to (which may be the script's name, or something more specific). If omitted, which is not recommended, this defaults to "__oolite_legacy_destinations" which is also used for marking with numbers and marking carried out by legacy scripts.
* <code>markerColor</code> : A string specifying a colour. e.g. "redColor" or "1.0 0.5 0.0". If omitted, "redColor" will be used.
* <code>markerScale</code> : A number between 0.5 and 2.0 specifying the relative size of the marker. Defaults to 1.0.
* <code>markerShape</code> : A string describing the shape of the marker. Valid values are MARKER_X, MARKER_PLUS, MARKER_SQUARE and MARKER_DIAMOND. If this value is invalid or omitted, MARKER_X will be used.

Multiple markers may be placed on the same system, provided that they have different names. If a marker with the same system and name already exists, it will be replaced.

mission.markSystem({
system: 55,
name: "my_oxp",
markerColor: "cyanColor",
markerScale: 1.5,
markerShape: "MARKER_DIAMOND"
});

'''See also:''' <code>[[#unmarkSystem|unmarkSystem()]]</code>

=== <code>runShipLibrary</code> ===
{{oolite-method-added|1.81}}
function '''runShipLibrary()'''
Display the ship library based on [[shiplibrary.plist]], including processing of condition scripts.

This is mainly useful for scenarios which override the standard scripts.

=== <code>runScreen</code> ===
function '''runScreen(parameters : Object [, callback : Function [, this : Object]])'''
Present a mission screen.

The appearance of the mission screen is defined by the properties of the <code>parameters</code> object. The currently defined properties are:
* <code>title : String</code>
* <code>titleKey : String</code> (Key in [[missiontext.plist]])
* <code>music : String</code> (name of a music file)
* <code>overlay : ''guiTextureSpecifier''</code> (name of an image used as overlay)
* <code>background : ''guiTextureSpecifier''</code> (name of a picture used as background)
* <code>backgroundSpecial: String</code> ({{oolite-prop-added|1.77}}, special background layer)
* <code>model : String</code> (Role of a ship that will be shown as rotating ship)
* <code>modelPersonality : Int</code> ({{oolite-prop-added|1.77}}, the entityPersonality assigned to the <code>model</code>. If unspecified, or in 1.76 or earlier, a random personality is used)
* <code>message : String</code>
* <code>messageKey : String</code> (Key in [[missiontext.plist]])
* <code>spinModel: Boolean</code> (If <code>false</code>, the model is shown from the top with no automatic animation.)
* <code>choices: Object</code> ({{oolite-prop-added|1.77}}, Object describing [[Oolite_JavaScript_Reference:_Mission#Advanced_choices_.281.77_or_later_only.29|advanced choices]])
* <code>choicesKey : String</code> (Key in [[missiontext.plist]])
* <code>initialChoicesKey : String</code> ({{oolite-prop-added|1.77}}, the key from <code>choicesKey</code> which is initially selected)
* <code>allowInterrupt : Boolean</code> ({{oolite-prop-added|1.77}}. If <code>true</code> (default: false), the mission screen can be interrupted with function keys, which does not call the callback function. Mainly intended for interfaces.)
* <code>exitScreen : ''guiScreen''</code> ({{oolite-prop-added|1.77}}, a GUI screen to exit on. If omitted, an invalid value is given, or the player is not docked, this will revert to "GUI_SCREEN_STATUS". Not all GUI screens are selectable for this: only those reachable with function keys F3 to F8)
* <code>screenID : String</code> ({{oolite-prop-added|1.77}}, an optional string which can be read later from <code>[[#screenID|mission.screenID]]</code>)
* <code>textEntry : Boolean</code> ({{oolite-prop-added|1.79}}, if it's true, then you get the text prompt and 'choices' and 'choicesKey' are ignored. Whatever's typed there gets passed as the parameter to the callback function. The [https://github.com/OoliteProject/oolite/blob/master/Resources/Scripts/oolite-registership.js ship registry code] has a simple example.)
* <code>customChartZoom : decimal</code> ({{oolite-prop-added|1.87}}, zoom level of the 'CUSTOM_CHART' backgroundSpecial map)
* <code>customChartCentre: Vector3D</code> ({{oolite-prop-added|1.87}}, centre position of the 'CUSTOM_CHART' backgroundSpecial map, using the internal coordinate system. The z component is always zero. Discouraged in favour of customChartCentreInLY)
* <code>customChartCentreLY: Vector3D</code> ({{oolite-prop-added|1.87}}, centre position of the 'CUSTOM_CHART' backgroundSpecial map, in LY. e.g. for Lave: (8, 34.6, 0). The z component is always zero.)
Some of these are mutually exclusive; for instance, “title” overrides “titleKey”. See [[Oolite JavaScript Reference: Global#setScreenBackground|setScreenBackground()]] for a discussion of ''guiTextureSpecifier''.

There are 21 lines available for display of the message and choices combined. (In 1.77, this is extended to 27 lines if the player's HUD is hidden)

==== runScreen callbacks ====
The callback function is a function that is called when the player makes a choice. Every runScreen can have its own specific callback function, or you can design a single function to handle multiple mission screens instead. The optional <code>this</code> parameter will be used as the <code>this</code> property of the mission screen callback. It is usually unnecessary to specify this, but if you intend the function which calls runScreen to be called from a different script, and the callback references <code>this</code>, you will need to use it.

'''Example:''' 
A simple mission screen:
mission.runScreen({
title: "My first mission screen",
message: "This am a mission screen wot is good",
choicesKey: "me_firstmission_choices"
},
function (choice)
{
if (choice === "1_YES") player.commsMessage("Yay!");
else if (choice === "2_NO") player.commsMessage("Boo.");
else player.commsMessage("Whut?");
});
In [[missiontext.plist]], you’ll need the following. The numbers are used because choices are sorted by key.
{
"me_firstmission_choices" =
{
"1_YES" = "Yes.";
"2_NO" = "No.";
"3_MAYBE" = "Maybe.";
};
}

The call does not have to be laid out as above. The parameters object can be manipulated in any way you want beforehand, and the callback function can be written out of line. For example, the following is equivalent:
var parameters = new Object();
parameters.title = "My first mission screen";
parameters.message = "This am";
parameters.choicesKey = "me_firstmission_choices";
parameters.message += " a mission screen wot is good";

function callback(choice)
{
if (choice === "1_YES") player.commsMessage("Yay!");
else if (choice === "2_NO") player.commsMessage("Boo.");
else player.commsMessage("Whut?");
}

mission.runScreen(parameters, callback);

This form is more complicated, and the ordering is less intuitive. However, it does allow you to make complex decisions about the parameters in code, and writing the callback out of line can be preferable if it’s long. It is recommended that you start out with the first approach, but keep in mind that there are other options if it becomes too limiting.

In 1.77, if <code>allowInterrupt</code> is set to true, it is possible that the callback function will not be called. It should therefore only be set for mission screens which can safely be interrupted without the callback. Regardless of this setting, all mission screens may be interrupted by the player launching from the station, and this possibility should be considered (in such case callback function will be called with <code>null</code> argument).

==== runScreen special backgrounds (1.77 or later only) ====

In 1.77 or later, 'backgroundSpecial' may be given the following special string values:
* <code>SHORT_RANGE_CHART</code>: Uses the short range chart (as if the player had pressed F6). The first 18 lines of the mission text will overlap the chart if used.
* <code>LONG_RANGE_CHART</code>: Uses the current long range chart (as if the player had pressed F6 twice). The first 16 lines of the mission text will overlap the chart if used.
* <code>LONG_RANGE_CHART_SHORTEST</code>: As LONG_RANGE_CHART, but if the player has a working [[Advanced Navigational Array]] then the shortest (fewest jumps, not necessarily shortest distance) route to their current destination system will be displayed.
* <code>LONG_RANGE_CHART_QUICKEST</code>: As LONG_RANGE_CHART, but if the player has a working [[Advanced Navigational Array]] then the quickest route to their current destination system will be displayed.

In 1.87 or later, 'backgroundSpecial' has these additional special string values:
* <code>SHORT_RANGE_CHART_SHORTEST</code>: As SHORT_RANGE_CHART, but if the player has a working [[Advanced Navigational Array]] then the shortest (fewest jumps, not necessarily shortest distance) route to their current destination system will be displayed.
* <code>SHORT_RANGE_CHART_QUICKEST</code>: As SHORT_RANGE_CHART, but if the player has a working [[Advanced Navigational Array]] then the quickest route to their current destination system will be displayed.
* <code>CUSTOM_CHART</code>: Displays a chart where zoom and centre position can be customised using the 'customChartZoom' and 'customChartCentreInLY' properties. The first 18 lines of the mission text will overlap the chart if used.
* <code>CUSTOM_CHART_SHORTEST</code>: As CUSTOM_CHART, but if the player has a working [[Advanced Navigational Array]] then the shortest (fewest jumps, not necessarily shortest distance) route to their current destination system will be displayed.
* <code>CUSTOM_CHART_QUICKEST</code>: As CUSTOM_CHART, but if the player has a working [[Advanced Navigational Array]] then the quickest route to their current destination system will be displayed.

With all special chart backgrounds, changes made to destination system, or to markers, will be updated immediately. 
These backgrounds will be displayed above the '<code>background</code>' (if any) but below everything else.

==== Advanced choices (1.77 or later only) ====

In 1.77 or later, choices may be set either with the 'choicesKey' parameter from missiontext.plist as before, or with the 'choices' parameter. (If both are set, 'choicesKey' will be ignored)
'''Example''' 
var options = {
"01_AGREE" : "Take the job",
"02_DECLINE" : "Politely decline"
};
if (player.bounty == 0) // only clean players have this option
{
options["03_REPORT"] = "Call the police";
}

mission.runScreen({
// title, message, etc.
choices: options
},function(choice) {
// choice handling
});

This is useful where the options available (perhaps depending on the player's ship or equipment, or on previous events in the mission) may vary in a complex fashion, to avoid the need to have a separate missiontext.plist entry for every possibility.

The value (either in <code>choicesKey</code>'s missiontext entry or <code>choices</code>) may either be a text string as in previous versions, or an object itself. If it is an object, it can take three parameters:
* 'text' is the displayed text for this key.
* 'alignment' can be 'LEFT', 'RIGHT' or 'CENTER' (the default).
* 'unselectable' can be <code>true</code> or <code>false</code> (the default for non-blank text). Unselectable rows are printed, but are skipped when moving through the options. This can be useful for keeping a consistent interface.
* 'color' can be any color specification (e.g. "orangeColor"). The default is "yellowColor", or "darkGrayColor" for unselectable rows.
For example (missiontext.plist):
"my_choice_1" = {
"01_AGREE" = {
text = "Take the job";
alignment = "LEFT";
color = "greenColor";
};
// more options
};

In 1.77, the behaviour for choices which have no text is slightly changed. These will now leave a blank and unselectable line in the option list.

==== Safe usage of runScreen ====

One warning: <code>runScreen()</code> will overwrite any existing missionscreen or GUI screen. The only safe place is using it inside a <code>missionScreenOpportunity</code> handler or the callback function from a previous mission screen (or in 1.77 onwards, inside an interface callback function), because that handler only fires when it is allowed to show such a screen. When using the command at other places, first make sure with <code>guiScreen != "GUI_SCREEN_MISSION"</code> that there is currently no missionscreen on display by another oxp.

==== Known issues ====

From Oolite 1.79, only the A-Z, a-z, 0-9 and (space) characters may be reliably entered in the 'textEntry' field. A wider selection, for boring internal reasons, is available on the Mac, and is hoped to also be available on other platforms in later releases.

=== <code>setInstructions</code> ===
function '''setInstructions(instructions : String, [worldScriptName : String])'''

Specify a message to put on the Manifest screen (usually short instructions for current mission), under the title “Missions”.

When not called from within a world script, the name of a world script must be specified so that Oolite knows which script the message belongs to. Clear the message by calling <code>setInstructions(null)</code>.

It is recommended that <code>setInstructions()</code> is used only when you need to customise the text for a specific scenario. For static text, use <code>[[#setInstructionsKey|setInstructionsKey()]]</code> instead.

In Oolite 1.81 onwards, the following variant is available

{{oolite-method-added|1.81}}
function '''setInstructions(instructions : Array, [worldScriptName : String])'''

If this version is used, the first array element will be a heading on the Manifest screen, and the remaining elements will be entered underneath it, rather than being entered under the "Missions" heading.

'''Example''': <code>mission.setInstructions(["Ship Companion:",expandMissionText("myoxp_currentpet"),...]);</code> will display Ship Companion: in yellow text on the F5F5 screen, and beneath it will show the [[String expansion|expanded]] value of the key "myoxp_currentpet" from the [[missiontext.plist]] associated with the calling world script. If not called from a world script, the worldScriptName (this.name from the script) must be provided also: <code>mission.setInstructions(["Ship Companion:",expandMissionText("myoxp_currentpet"),...], "myoxp's script name");</code>

Note that the line or lines to be added must be enclosed in square brackets, comma separated. Also note the optional use of expandMissionText to retrieve text from [[missiontext.plist]]. It is also possible to construct the array before calling setInstructions, for example:<pre>
if(myoxp_petslist.length == 0) {
mission.setInstructions(null); // clear any text previously displayed by this world script on the F5F5 screen
} else {
var textArray = [];
textArray.push("Ship Companion" + (myoxp_petslist.length > 1 ? "s:" : ":")); // "Ship Companion:" or "Ship Companions:" if more than one
var i = myoxp_petslist.length - 1; // pointer to last entry in myoxp_petslist
while(i--) { // for each pet in the list, starting from the bottom (probably newest to oldest)
textArray.push(myoxp_petslist[i].name); // add the name of the pet to the text we will show on the F5F5 screen
}
mission.setInstructions(textArray); // our pets list will now be visible on the F5F5 screen until further notice (the next time we call setInstructions or one of its variants, it will replace this)
}
</pre>

'''See also:''' <code>[[#setInstructionsKey|setInstructionsKey()]]</code>

=== <code>setInstructionsKey</code> ===
function '''setInstructionsKey(messageKey : String, [worldScript : String])'''

Like <code>[[#setInstructions|setInstructions()]]</code>, but looks up the specified <code>messageKey</code> in [[missiontext.plist]].

'''See also:''' <code>[[#setInstructions|setInstructions()]]</code>

=== <code>unmarkSystem</code> ===
function '''unmarkSystem'''(systemNumbers : Number)

Remove a mark set with <code>[[#markSystem|markSystem()]]</code>. Multiple systems may be unmarked at once, as in <code>mission.unmarkSystem(4, 54, 222)</code>.

In 1.76 and earlier versions, any script can unmark a system, regardless of which script marked it or how many times it was previously marked.

In 1.77, each marker has a name, and if a system has multiple markers each marker must be removed separately. Parameters in 1.77 may be numbers or objects. Numbers remove the "__oolite_legacy_destinations" markers. Objects are the same format as in <code>markSystem</code> and remove the marker of the corresponding name (the marker style options are ignored when unmarking). In 1.77, this function will return true if all requested markers existed and were removed, or false if any of the requested markers did not exist.

'''See also:''' <code>[[#markSystem|markSystem()]]</code>

[[Category:Oolite JavaScript Reference]]

String expansion

2020-06-24T16:17:10Z

Milo: corrected operator examples

== Format ==
Oolite has a mechanism to replace text in strings with other text. At certain times before displaying text (details below), Oolite searches for % symbols and square brackets [ ]. If it finds them, it checks if what immediately follows the % symbols, or what is between the square brackets, has a recognized special meaning, and if so, substitutes replacement text. Oolite also recognizes vertical bars ('|') and colons (':') inside square brackets as special characters. When you do not want Oolite to replace text, use a double % ('%%') to display a single %, and put a backslash ('\') before each square bracket to display the brackets and text inside them without substitution ('\[example\]' will be displayed as '[example]'). Additionally, the special value '\n' will be replaced by a new line, which can be prevented by preceding it with an extra slash ('\\n' will display '\n').

== What is switched ==
'''Recognized % codes:'''

* %H - Current System name, e.g., Lave
* %I - Current System name with "ian" appended, e.g., Laveian
* %Jxxx - Name of System corresponding with ID number xxx in the current galaxy (must be a 3-digit number), e.g., %J007 is Lave while in Galaxy 1 (feature added in Oolite 1.73)
* %Gxxxyyy - Name of System corresponding with ID number xxx in galaxy number yyy (both must be 3-digit numbers), e.g. %G007000 is Lave (feature added in Oolite 1.87)
* %N - Random name (repetitions of %N in the same string generate the same result)
* %R - Random word (repetitions of %R in the same string generate unique results)

'''Text in brackets:'''

* If there are only numbers between the brackets (e.g., [0] or [35]), the corresponding Nth sub-array (counting from zero) is retrieved from the <code>system_description</code> array in [[descriptions.plist]], which is expected to contain only sub-arrays of strings. When a sub-array is retrieved, one string is selected from it at random and the result is expanded recursively (if it contains %-codes or bracket expressions, those will be replaced too). As of Oolite 1.87, there are 36 entries in the system_description array (the last is [35]). This is used to generate planet descriptions but may be used in OXPs if the strings are suitable. For example, [10] is replaced with a random beverage.
* Otherwise, the text between the brackets (hereafter called the "key") is evaluated recursively in the following priority order to find a replacement:
*# Overrides (context-specific expansions, special keys that are only recognized in certain situations, and can also be used from JavaScript)
*#* In comms messages, [self:name] and [target:name] will be replaced respectively with the sender's displayName and the target's displayName (or the "unknown-target" description from [[descriptions.plist]], if the scanner is jammed).
*#* In [[Oolite_JavaScript_Reference:_Global#expandDescription|expandDescription]] and [[Oolite_JavaScript_Reference:_Global#expandMissionText|expandMissionText]] you can provide a dictionary of keys and replacement values (which can be JavaScript expressions calculated at run-time).
*# Special keys (these are hard-coded)
*#* [commander_name]
*#* [commander_shipname]
*#* [commander_shipdisplayname]
*#* [commander_rank]
*#* [commander_kills]
*#* [commander_legal_status]
*#* [commander_bounty]
*#* [credits_number]
*# [[Descriptions.plist]] (if there is a matching key, substitutes the associated value, which may be a single string or an array of string; if it is an array of strings, then one is selected at random.) Because [[descriptions.plist]] entries from all OXPs are merged at run-time with the ones in the game's Resources folder, it is '''recommended''' that OXP-specific entries in [[descriptions.plist]] have an OXP or creator-specific prefix to ensure uniqueness.
*#* For example, [nom] will match the "nom" key in [[descriptions.plist]], the value of which is an array of two strings ("%R", "[nom1]"), one of which will be randomly selected, and then evaluated again.
*# Keyboard bindings (will be replaced with corresponding key name; however, [[descriptions.plist]] overrides keybindings and is evaluated first, so using these keys in OXPs is '''discouraged'''; instead, look for the comment "translations of special keys" in [[descriptions.plist]] and use the keys there)
*#* [oolite_key_tab], [oolite_key_esc], [oolite_key_space], [oolite_key_f1], [oolite_key_f2], [oolite_key_f3], [oolite_key_f4], [oolite_key_f5], [oolite_key_f6], [oolite_key_f7], [oolite_key_f8], [oolite_key_f9], [oolite_key_f10, [oolite_key_f11]
*#* [oolite_key_right], [oolite_key_left], [oolite_key_down], [oolite_key_up], [oolite_key_home], [oolite_key_end], [oolite_key_insert], [oolite_key_delete], [oolite_key_pageup], [oolite_key_pagedown]
*#* [oolite_key_numpad0], [oolite_key_numpad1], [oolite_key_numpad2], [oolite_key_numpad3], [oolite_key_numpad4], [oolite_key_numpad5], [oolite_key_numpad6], [oolite_key_numpad7], [oolite_key_numpad8], [oolite_key_numpad9]
*# Mission variables (<code>[mission_FOO]</code> substitutes the value contained in <code>missionVariables.FOO</code>)
*#* These are commonly used in OXPs as a method of including dynamic information in displayed text.
*# Legacy local variables (<code>[local_FOO]</code> substitutes the value contained in <code>worldScripts.scriptname.FOO</code> with the scriptname depending on the context where the text is being evaluated)
*#* A local variable is a property defined on a world script (e.g., a script.js in Config/, or any script listed in a [[Scripting Oolite with JavaScript|world-scripts.plist]]). this.name from a script.js in Config/ is used as the key for that script in the global worldScripts dictionary. As of Oolite 1.87, none of the core game texts use local variables.
*#* In [[Oolite_JavaScript_Reference:_Mission#addMessageText]] and [[Oolite_JavaScript_Reference:_Mission#addMessageTextKey]], the applicable scriptname is the calling script. As an example, if your script has a local variable <code>this.calculatedvalue</code> you could display the content of that variable with other text by calling <code>mission.addMissionText("various text [local_calculatedvalue] various other text");</code>
*# Legacy script query methods
*#* As a last resort, Oolite attempts to expand a key by treating it as a legacy script query method and invoking it. Only [[whitelist.plist|whitelisted]] query_methods and query_method_aliases are permitted. Examples: [systemGovernment_string] (a whitelisted query method), [fuelLevel_number] (a whitelisted query method) or [fuel_level_number] (a whitelisted alias for [fuelLevel_number])
* If no suitable replacement is found, the text will be displayed unchanged and a warning will be logged.

'''Operators:'''

If a vertical bar ('|') is found between square brackets, Oolite will interpret whatever is on the left side of the bar as the ''key'' and whatever is on the right side of the bar as an ''operator''. An ''operator'' tells Oolite to apply a change after the key has been expanded. Some operators also require an input value, a colon (':'). The available ''operators'' are:
* cr - displays the text as a credit value, interpreting the value as floating point credits (e.g., if the value is 1007.7, display 1007.7 ₢)
* dcr - displays the text as a credit value, interpreting the value as floating point deci-credits (e.g., if the value is 1007.7, display 100.7 ₢)
* icr - displays the text as a credit value, interpreting the value as integer credits (e.g., if the value is 1007.7, display 1007 ₢)
* idcr - displays the text as a credit value, interpreting the value as integer deci-credits, rounded (e.g., if the value is 1007.7, display 101 ₢)
* precision - displays the text as a floating point value with an integer-specified number of decimal places, must be specified as ''precision'':number (e.g., [distance|precision:2])
* multiply - displays the text as a floating point value multiplied with another floating point value, which must be provided as ''multiply'':othervalue (e.g., [fuelLevel_number|multiply:0.5])
* add - displays the text as a floating point value added to another floating point value, which must be provided as ''add'':othervalue (e.g., [fuelLevel_number|add:1.5])

Multiple ''operators'' can be applied sequentially to the same key, each separated by a vertical bar. For example: [distance|multiply:0.5|precision:1].

== When are things switched ==
Oolite calls the switching routine only at certain places ('''this is not a complete list'''):
*The most often used place is in [[missiontext.plist]]. Every text line is evaluated for string replacement. Most commonly this is used to replace text in brackets with the content of a variable or a [[descriptions.plist]] entry.
*Inside a [[descriptions.plist]] entry you can also use brackets. This way you can get a recursive process. Look for example in the descriptions.plist in Oolite's Resources\Config folder where it generates random names in a recursive way. (Recursion is limited to 32 times to prevent infinite looping.). Because of the random number generator used for expansion, the use of deep recursion may cause correlations which are not random - consider for example that "mud" is always followed by "tennis" or "hockey" in planetary descriptions, never anything else. In Oolite 1.79, certain ways of expanding descriptions from JavaScript will use a higher quality random number generator, which does not have correlation problems.
*During evaluation of a [[OXP howto AI|plist-based AI]], it only uses switching on the content of a "commsMessage".
*During evaluation of a [[script.plist]] all the lines in the DO or ELSE part of a condition statement are switched. Nothing is switched in the CONDITIONS part of a command so you cannot use anything in brackets there.
*In [[Oolite_JavaScript_Reference:_Global#expandDescription|expandDescription]] and [[Oolite_JavaScript_Reference:_Global#expandMissionText|expandMissionText]].

The way things work means that you can create complicated structures. You can use for example:
addSystemShips: my_ship 1 0.[d100_number]

Oolite first offers the above line to the replacement routine. That replaces [d100_number] by a random number. e.g. 46. Than the routine returns:
addSystemShips: my_ship 1 0.46

This line will then be executed and the ship is placed at the calculated random position. You can also define a [[descriptions.plist]] entry of my_random_ship and define a list of several ship roles. When you then use:
addSystemShips: [my_random_ship] 1 0.[d100_number]
the system will randomly pick a ship from the list and replace the d100_number with a value and return the expanded string. This will than be executed.

[[Category:Oolite scripting]]

Oolite JavaScript Reference: World script event handlers

2020-06-24T12:50:58Z

Milo: minor elaboration

This page provides a list of event handlers which can be implemented inside world scripts [[Scripting Oolite with JavaScript|JavaScript scripts for Oolite]]. Additionally, ship script handlers called on the player's ship will cause an equivalent world script event.

Most event handlers can be used both in world scripts and in ship scripts. Generally speaking, handlers starting with "ship" can be used for both scripts and those starting with "player" are meant only for the player (= can only be used in a world script). Exceptions on this rule are mentioned with the individual handlers below.

World scripts can be either found inside Config\script.js, or be distinctly named .js files inside the Scripts directory - in the latter case, the worldScript.plist will list the active world scripts.

World scripts are always active.

The list of event handlers will change from version to version (usually additions of extra handlers). For this reason, any variables or functions you create as <code>this.variable</code> should have a name beginning with '_' or '$' - e.g. <code>this._variable</code> or <code>this.$variable</code> - to avoid potential conflicts with future event handlers (which will never start with '_' or '$').

=== Game State ===

==== <code>gamePaused</code> ====
{{oolite-method-added|1.81}}

This event is called when the game is paused. This is mainly useful for pausing sound playback which should not continue while the game is paused.

this.gamePaused = function()
{
// Your code here
}

==== <code>gameResumed</code> ====
{{oolite-method-added|1.81}}

This event is called when the game is resumed from pause. This is mainly useful for resuming sound playback paused in a <code>gamePaused</code> handler.

this.gameResumed = function()
{
// Your code here
}

==== <code>playerWillSaveGame</code> ====

The <code>playerWillSaveGame</code> handler is called whenever the player saves a game. The transferred message is one of the following strings: 'standardSave', 'autoSave' or 'quickSave'

this.playerWillSaveGame = function(message : String)
{
// Your code here
}

Using this event is useful for storing temporary variables in missionVariables, just before the game gets saved. missionVariables are slow in use compared to normal JS variables, therefor their use should be minimised for efficient code. The main benefit of using missionVariables is that they are saved in a saved game.

==== <code>startUp</code> ====

The <code>startUp</code> handler is called after all OXPs have been loaded. This also means that it is called every time the player loads a game, begins a new game or presses space after dying. It can be used to do one-off initialisation such as copying mission variables into <code>this.*</code> properties for efficiency or setting up data arrays to be used by the script in other handlers. (world script only)

this.startUp = function()
{
// Your code here
}

Note that from Oolite 1.79 onwards the player will be in the main station while this function is run, but may be moved from there to another station soon after.

==== <code>startUpComplete</code> ====
{{oolite-method-added|1.79}}

The <code>startUpComplete</code> handler is run at game startup after the initial population of the system has been complete, and after the player has been moved to the station recorded in their save game. The order of world events at game start is therefore:
* <code>startUp</code>
* <code>systemWillPopulate</code> (or an alternative handler specified by the system info)
* <code>startUpComplete</code>

=== Docking ===

==== <code>shipWillDockWithStation</code> ====

The <code>shipWillDockWithStation</code> handler is called at the beginning of the docking tunnel effect.

this.shipWillDockWithStation = function(station)
{
// Your code here
}
At this moment "ship.dockedStation == null", "ship.docked == true", "ship.status == STATUS_DOCKING"

==== <code>shipDockedWithStation</code> ====

The <code>shipDockedWithStation</code> handler is called at the end of the docking tunnel effect.

this.shipDockedWithStation = function(station)
{
// Your code here
}
At this moment "ship.dockedStation == the station", "ship.docked == true", "ship.status == STATUS_DOCKED" and "gui_screen" is either GUI_SCREEN_STATUS or GUI_SCREEN_REPORT. However, any identical handler from an other oxp could have changed those values. Never count on it but double check when important.

==== <code>shipWillLaunchFromStation</code> ====

The <code>shipWillLaunchFromStation</code> handler is called at the beginning of the launch tunnel effect.

this.shipWillLaunchFromStation = function(station)
{
// Your code here
}
At this moment "ship.dockedStation == the station", "ship.docked == false", "ship.status == STATUS_LAUNCHING".

==== <code>shipLaunchedFromStation</code> ====

The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect. The argument passed to the handler function is the station entity from which the ship was launched.

this.shipLaunchedFromStation = function(stationLaunchedFrom)
{
// Your code here
}

At this moment "ship.dockedStation == null", "ship.docked == false", "ship.status == STATUS_IN_FLIGHT".

==== <code>playerStartedAutoPilot</code> ====

The <code>playerStartedAutoPilot</code> handler is called when the player starts autopilot docking. It is not called for the instantaneous dock command. The handler is called with an argument containing the station entity that is the docking target.

this.playerStartedAutoPilot = function(stationForDocking)
{
// Your code here
}

==== <code>playerCancelledAutoPilot</code> ====

The <code>playerCancelledAutoPilot</code> handler is called when the player cancels autopilot docking.

this.playerCancelledAutoPilot = function()
{
// Your code here
}

==== <code>playerDockingClearanceCancelled</code> ====
{{oolite-method-added|1.85}}

The <code>playerDockingClearanceCancelled</code> handler is called when the player withdraws their request to dock at a station.

this.playerDockingClearanceCancelled = function()
{
// Your code here
}

==== <code>playerDockingClearanceExpired</code> ====
{{oolite-method-added|1.83}}

The <code>playerDockingClearanceExpired</code> handler is called when the player exceeds the two minute window without requesting an extension

this.playerDockingClearanceExpired = function()
{
// Your code here
}

==== <code>playerDockingClearanceGranted</code> ====
{{oolite-method-added|1.85}}

The <code>playerDockingClearanceGranted</code> handler is called when the player is given permission to dock at a station. If the player is given immediate clearance to dock, this event will be called immediately after the <code>playerRequestedDockingClearance</code> event. If, however, the station is unable to give immediate clearance, then there will be some delay between the request to dock and permission being granted. This event will be called when the station actually gives docking clearance.

this.playerDockingClearanceGranted = function()
{
// Your code here
}

==== <code>playerDockingRefused</code> ====

The <code>playerDockingRefused</code> handler is called when a station refuses to provide autopilot docking instructions.

this.playerDockingRefused = function()
{
// Your code here
}

==== <code>playerRequestedDockingClearance</code> ====

The <code>playerRequestedDockingClearance</code> handler is called when a station answers on a docking request of the player by targeting the station and pressing L (shift-l).

this.playerRequestedDockingClearance = function(message)
{
// Your code here
}

Message is a string and can take the values: "DOCKING_CLEARANCE_GRANTED", "DOCKING_CLEARANCE_DENIED_TRAFFIC_OUTBOUND", "DOCKING_CLEARANCE_DENIED_TRAFFIC_INBOUND", "DOCKING_CLEARANCE_DENIED_SHIP_FUGITIVE", "DOCKING_CLEARANCE_NOT_REQUIRED", "DOCKING_CLEARANCE_EXTENDED" or "DOCKING_CLEARANCE_CANCELLED".

==== <code>playerRescuedEscapePod</code> ====
{{oolite-method-added|1.81}}

The <code>playerRescuedEscapePod</code> handler is called when the player rescues an escape pod which does not have scripted content (all consequences of scripted content escape pods are assumed to be dealt with by the specified script instead). It has three parameters:
# the rescue fee, in decicredits
# the fee reason, which can be "insurance", "bounty" or "slave" (in the latter case, the fee will always be zero)
# a dictionary like those in the <code>ship.crew</code> property describing the pod occupant

this.playerRescuedEscapePod = function(fee, reason, occupant)
{
// Your code here
}

This method is called after the escape pod has been processed, but slightly before the arrival report screen giving the results of the processing is displayed to the player.

==== <code>playerCompletedContract</code> ====
{{oolite-method-added|1.81}}

The <code>playerCompletedContract</code> handler is called when a passenger, parcel or cargo contract ends, either successfully or by defaulting on it. It is not called when all contracts are cancelled on a galactic jump. It has four parameters:
# The type of contract, which can be "cargo", "parcel" or "passenger"
# The result of the contract, which can be "success", "late", "failed", or for cargo contracts only "short"
# The fee paid for the contract in decicredits
# The contract information dictionary
Note that the fee actually paid for the contract will often ''not'' match the originally agreed fee in the contract information dictionary, as penalties for late delivery or bonuses for good service are included in the fee parameter.

this.playerCompletedContract = function(type, result, fee, contract)
{
// Your code here
}

This method is called after the contract has been processed, but slightly before the arrival report screen giving the results of the processing is displayed to the player.

==== <code>playerEnteredContract</code> ====
{{oolite-method-added|1.81}}

The <code>playerEnteredContract</code> handler is called when a passenger, parcel or cargo contract starts, just after the items have been transferred to the player ship. It has two parameters:
# The type of contract, which can be "cargo", "parcel" or "passenger"
# The contract information dictionary

this.playerEnteredContract = function(type, contract)
{
// Your code here
}

=== Witchspace Jumps ===

==== <code>playerStartedJumpCountdown</code> ====

The <code>playerStartedJumpCountdown</code> handler is called when the user starts a witchspace or galactic witchspace jump countdown. The <code>type</code> parameter is a string specifying which type of jump is occuring; currently, the possible values are “standard” and “galactic”. Other values may be added in future. The <code>seconds</code> parameter is a number specifying the number of seconds the countdown is running for.

this.playerStartedJumpCountdown = function(type, seconds)
{
// Your code here
}

==== <code>playerCancelledJumpCountdown</code> ====

The <code>playerCancelledJumpCountdown</code> handler is called when the user cancels a witchspace or galactic witchspace jump countdown.

this.playerCancelledJumpCountdown = function()
{
// Your code here
}

==== <code>playerJumpFailed</code> ====

The <code>playerJumpFailed</code> handler is called at the end of a witchspace or galactic witchspace countdown, if the jump is not possible. The <code>reason</code> parameter is a string specifying why the jump failed. The current values are:
* '''"insufficient fuel"''' - the ship no longer has enough fuel to make the jump (e.g. injector use or fuel leak).
* '''"blocked"''' - a heavy ship is near the player (specifically <code>object mass</code> / <code>object distance</code>2 >= 10.0, and <code>object distance</code> <= scanner range).
* '''"malfunction"''' - the jump malfunctioned in a way that leaves the player ship in the current system.
* '''"malfunction"''' - the Galactic Hyperdrive is damaged or removed during a galactic jump countdown.

Also theoretically possible but unlikely in current Oolite:
* '''"too far"''' - the jump destination is outside the 7LY range (but wasn't when the countdown started).
* '''"no target"''' - the jump destination is the current location (but wasn't when the countdown started).

this.playerJumpFailed = function(reason)
{
// Your code here
}

==== <code>shipWillEnterWitchspace</code> ====

The <code>shipWillEnterWitchspace</code> handler is called immediately before a witchspace jump, while the player is still in the starting system. The <code>cause</code> parameter is a string specifying what sort of jump is occuring; currently, the possible values are “standard jump”, “galactic jump” and “wormhole”. Other values may be added in future.

// 1.80 or earlier
this.shipWillEnterWitchspace = function(cause)
{
// Your code here
}

In 1.81 or later the handler gains a second parameter, describing the jump destination. For standard and wormhole jumps, this will be the system ID of the destination system. For galactic jumps, this will be the galaxy ID of the destination galaxy. (As [[Oolite JavaScript Reference: PlayerShip#galacticHyperspaceBehaviour|player.ship.galacticHyperspaceBehaviour]] may be changed during <code>shipWillEnterWitchspace</code>, it is not possible to predict in advance of a galactic jump being made what the resulting system ID in the destination galaxy will be)

// 1.81 or later
this.shipWillEnterWitchspace = function(cause, destination)
{
// Your code here
}

==== <code>shipWillExitWitchspace</code> ====

The <code>shipWillExitWitchspace</code> handler is called as a witchspace jump concludes. When it is called, the player is (from a program perspective) in the destination system, but the tunnel effect has not yet been shown. Use this event to set up elements which need to be present in-system after the player exits witchspace.

this.shipWillExitWitchspace = function()
{
// Your code here
}

==== <code>shipExitedWitchspace</code> ====

The <code>shipExitedWitchspace</code> handler is called after a witchspace jump has concluded and the tunnel effect has been shown.

this.shipExitedWitchspace = function()
{
// Your code here
}

==== <code>playerEnteredNewGalaxy</code> ====

The <code>playerEnteredNewGalaxy</code> handler is called just before shipWillExitWitchspace.

the sequence of events for a player jumping to a different galaxy is as follows:

shipWillEnterWitchspace (world event) 
playerWillEnterWitchspace (NPC ship event) 
playerEnteredNewGalaxy (world event) 
shipWillExitWitchspace (world event) 
shipExitedWitchspace (world event) 

this.playerEnteredNewGalaxy = function(galaxyNumber)
{
// Your code here
}

=== Enter/Exit Aegis ===

==== <code>shipEnteredStationAegis</code> ====

The <code>shipEnteredStationAegis</code> handler is called when the player enters the aegis of the main-station (2x scanner range from main-station). Other stations than the main-station don't give aegis messages.

this.shipEnteredStationAegis = function(station)
{
// Your code here
}

==== <code>shipExitedStationAegis</code> ====

The <code>shipExitedStationAegis</code> handler is called when the player leaves the aegis of the main-station (2x scanner range from main-station).

this.shipExitedStationAegis = function(station)
{
// Your code here
}

==== <code>shipEnteredPlanetaryVicinity</code> ====

The <code>shipEnteredPlanetaryVicinity</code> handler is called when the player enters the planet aegis (3x planet radius).

this.shipEnteredPlanetaryVicinity = function(planet)
{
// Your code here
}

==== <code>shipExitedPlanetaryVicinity</code> ====

The <code>shipExitedPlanetaryVicinity</code> handler is called when the player leaves the planet aegis (3x planet radius).

this.shipExitedPlanetaryVicinity = function(planet)
{
// Your code here
}

==== <code>shipApproachingPlanetSurface</code> ====

The <code>shipApproachingPlanetSurface</code> handler is called when the player is very close to the planet (crosses a border ± 500 meter above the surface).

this.shipApproachingPlanetSurface = function(planet)
{
// Your code here
}

==== <code>shipLeavingPlanetSurface</code> ====

The <code>shipLeavingPlanetSurface</code> handler is called when the player leaves the planet (crosses a border ± 500 meter above the surface).

this.shipLeavingPlanetSurface = function(planet)
{
// Your code here
}

=== Combat ===

==== <code>alertConditionChanged</code> ====

The <code>alertConditionChanged</code> handler is called when the player’s alert status (<code>[[Oolite JavaScript Reference: Player#alertCondition|player.alertCondition]]</code>) changes. Only the player and stations have an alert condition. (world script and station scripts)

this.alertConditionChanged = function(newCondition, oldCondition)
{
// Your code here
}

==== <code>playerTargetedMissile</code> ====

The <code>playerTargetedMissile</code> handler is called when the player targets the nearest missile by pressing T (shift-t) on the keybord.

this.playerTargetedMissile = function(missile)
{
// Your code here
}

==== <code>shipAttackedOther</code> ====

The <code>shipAttackedOther</code> handler is called when the player hits another with a laser shot. <code>other</code> is the identity of the ship being hit.

this.shipAttackedOther = function(other)
{
// Your code here
}

==== <code>shipAttackedWithMissile</code> ====

The <code>shipAttackedWithMissile</code> handler is called when a missile is fired. <code>missile</code> contains the missile entity and <code>whom</code> the identity of the ship that launched the missile.

this.shipAttackedWithMissile = function(missile, whom)
{
// Your code here
}

==== <code>shipBeingAttacked</code> ====

The <code>shipBeingAttacked</code> handler is called when a laser shot hits. <code>whom</code> the identity of the ship that attacked.

this.shipBeingAttacked = function(whom)
{
// Your code here
}

==== <code>shipBeingAttackedByCloaked</code> ====

The <code>shipBeingAttackedByCloaked</code> handler is called when a laser shot from a cloaked ship hits. Guess what, there is no parameter because he is cloaked!

this.shipBeingAttackedByCloaked = function()
{
// Your code here
}

==== <code>shipKilledOther</code> ====
{{oolite-method-added|1.75}}

The <code>shipKilledOther</code> handler is called when a ship kills an other ship. <code>whom</code> the identity of the ship that was killed. <code>damageType</code> is the type of damage.

this.shipKilledOther = function(whom : ship, damageType : string)
{
// Your code here
}

==== <code>shipReleasedEquipment</code> ====

The <code>shipReleasedEquipment</code> handler is called when a ship launches a mine (a pylon-mounted equipment item whose key ends with "_MINE"). <code>mine</code> contains the launched mine entity.

this.shipReleasedEquipment = function(mine)
{
// Your code here
}

==== <code>shipTargetDestroyed</code> ====

The <code>shipTargetDestroyed</code> handler is called when the target gets destroyed by the player. <code>target</code> contains the destroyed target entity. This command is always preceded by the <code>shipTargetLost</code> handler.

this.shipTargetDestroyed = function(target)
{
// Your code here
}

==== <code>shipDied</code> ====

The <code>shipDied</code> handler is called when the ship or player dies. Expect a <code>reset()</code> shortly when it is the player ship.

this.shipDied = function(whom, why)
{
// Your code here
}
'''whom''' contains the entity that caused the kill. '''why''' is the cause written as string and is one of: "removed", "hit a planet", "energy damage", "scrape damage", "heat damage", "cascade weapon". 
("cascade weapon" is new in 1.74 and "removed" / "energy damage" were accidentally switched in 1.73)

==== <code>shipFiredMissile</code> ====

The <code>shipFiredMissile</code> handler is called when a missile is fired. <code>missile</code> contains the missile entity and <code>target</code> the identity of the target. The handler is send to the ship that launched the missile.

this.shipFiredMissile = function(missile, target)
{
// Your code here
}

==== <code>shipTargetLost</code> ====

The <code>shipTargetLost</code> handler is called when the target gets lost. <code>target</code> contains the lost target entity.

this.shipTargetLost = function(target)
{
// Your code here
}

==== <code>shipTargetCloaked</code> ====

The <code>shipTargetCloaked</code> handler is called when the target cloakes.

this.shipTargetCloaked = function()
{
// Your code here
}

==== <code>weaponsSystemsToggled</code> ====
{{oolite-method-added|1.85}}

The <code>weaponsSystemsToggled</code> handler is called whenever the player toggles their weapons systems on or off. The <code>state</code> parameter contains the new state of the weapons systems

this.weaponsSystemsToggled = function(state : boolean)
{
// Your code here
}

=== Equipment and Cargo ===

==== <code>equipmentAdded</code> ====
{{Oolite-method-added|1.81}}

The <code>equipmentAdded</code> handler is called whenever the player ship gains an item of equipment. This includes "gaining" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is damaged. This event will fire regardless of the reason for the equipment being added to the ship.

this.equipmentAdded = function(equipmentKey)
{
// Your code here
}

This is often more convenient than monitoring both <code>equipmentRepaired</code> and <code>playerBoughtEquipment</code>, and will also detect equipment addition by script.

==== <code>equipmentDamaged</code> ====

The <code>equipmentDamaged</code> handler is called when equipment gets damaged. (world script only)

this.equipmentDamaged = function(equipment)
{
// Your code here
}

==== <code>equipmentRemoved</code> ====
{{Oolite-method-added|1.81}}

The <code>equipmentRemoved</code> handler is called whenever the player ship loses an item of equipment. This includes "losing" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is repaired. This event will fire regardless of the reason for the equipment being removed from the ship.

this.equipmentRemoved = function(equipmentKey)
{
// Your code here
}

==== <code>equipmentRepaired</code> ====
{{Oolite-method-added|1.77}}

The <code>equipmentRepaired</code> handler is called when equipment gets repaired. (world script only)

this.equipmentRepaired = function(equipment)
{
// Your code here
}

==== <code>playerBoughtCargo</code> ====
{{Oolite-method-added|1.77}}

The <code>playerBoughtCargo</code> handler is called when cargo is bought at the market screen. <code>commodity</code> contains the non-localised name for the cargo. You can get the localised name using <code>expandDescription("[commodity-name "+commodity+"]");</code>. <code>price</code> is price per unit in tenths of a credit.

this.playerBoughtCargo = function(commodity, units, price)
{
// Your code here
}

==== <code>playerBoughtEquipment</code> ====

The <code>playerBoughtEquipment</code> handler is called when equipment is bought at the outfit screen.

this.playerBoughtEquipment = function(equipment, paid)
{
// Your code here
}

The 'paid' parameter is added from 1.89 onwards. This is the amount of credits the player paid for the equipment, including any refunds that might have been applied during the purchase (eg when purchasing a laser and installing it in a position where a laser is already fitted, the cost of the current laser will be refunded to the player during the purchase).

==== <code>playerBoughtNewShip</code> ====

The <code>playerBoughtNewShip</code> handler is called when a new ship is bought. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerBoughtNewShip = function(ship, price)
{
// Your code here
}

The 'price' parameter is added from 1.81 onwards. It is the cost of the ship (not counting any trade-in value of the player's old ship) in credits, or zero for changes using [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip</code>]]

'''Note:''' In a future release of Oolite, <code>playerBoughtNewShip</code> will no longer be fired when the ship is replaced using the [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip</code>]] function. Instead, the <code>[[#playerReplacedShip|playerReplacedShip]]</code> event should be used. At the moment, both events (<code>playerBoughtNewShip</code> and <code>playerReplacedShip</code>) will fire.

'''See also:''' <code>[[#playerWillBuyNewShip|playerWillBuyNewShip]]</code>

==== <code>playerChangedPrimedEquipment</code> ====
{{Oolite-method-added|1.85}}

The <code>playerChangedPrimedEquipment</code> handler is called whenever the player changes the currently primed equipment (either with shift-n or ctrl-shift-n). The equipment key of the newly primed equipment will be passed as an argument.

this.playerChangedPrimedEquipment = function(equipmentKey)
{
// Your code here
}

==== <code>playerReplacedShip</code> ====
{{Oolite-method-added|1.89}}

The <code>playerReplacedShip</code> handler is called when the player ship is replaced via the JS method [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip</code>]]. May be needed to re-evaluate the old equipment as replacing a ship does not trigger equipment removal.

this.playerReplacedShip = function(ship)
{
// Your code here
}

'''See also:''' <code>[[#playerWillReplaceShip|playerWillReplaceShip]]</code>

==== <code>playerSoldCargo</code> ====
{{Oolite-method-added|1.77}}

The <code>playerSoldCargo</code> handler is called when cargo is sold at the market screen. <code>commodity</code> contains the non-localised name for the cargo. You can get the localised name using <code>expandDescription("[commodity-name "+commodity+"]");</code>. <code>price</code> is price per unit in tenths of a credit.

this.playerSoldCargo = function(commodity, units, price)
{
// Your code here
}

==== <code>shipScoopedFuel</code> ====
{{Oolite-method-added|1.77}}

The <code>shipScoopedFuel</code> handler is called whenever the player's ship transfers 0.1LY of fuel from the scoops to the tank.

this.shipScoopedFuel = function()
{
// Your code here
}

==== <code>shipScoopedOther</code> ====

The <code>shipScoopedOther</code> handler is called when a ship scoops cargo. The scooped item is transferred as argument. If the cargo is scripted cargo, but not otherwise, then the scooped cargo itself gets the handler <code>shipWasScooped</code> with the scooper as argument.

this.shipScoopedOther = function(whom)
{
// Your code here
}

==== <code>playerWillBuyNewShip</code> ====
{{Oolite-method-added|1.89}}

The <code>playerWillBuyNewShip</code> handler is called just before a new ship is bought. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerWillBuyNewShip = function(dataKey, shipyard, price, tradeIn)
{
// Your code here
}

<code>dataKey</code> is the shipdata.plist <code>dataKey</code> for the ship being purchased.

<code>shipyard</code> is a dictionary object containing details about the ship being purchased, with information 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"]
}

<code>price</code> is the amount being paid the for ship.

<code>tradeIn</code> is the trade in value of the current ship.

'''See also:''' <code>[[#playerBoughtNewShip|playerBoughtNewShip]]</code>

==== <code>playerWillReplaceShip</code> ====
{{Oolite-method-added|1.89}}

The <code>playerWillReplaceShip</code> handler is called just before a ship is replaced using the [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip</code>]] function. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerWillReplaceShip = function(dataKey)
{
// Your code here
}

<code>dataKey</code> is the shipdata.plist <code>dataKey</code> for the ship being purchased.

'''See also:''' <code>[[#playerReplacedShip|playerReplacedShip]]</code>

=== Other ===

==== <code>chartHightlightModeChanged</code> ====
{{oolite-method-added|1.87}}

The <code>chartHighlightModeChanged</code> handler is called whenever the highlight mode of the galactic chart is changed, either manually (from player input), or programmatically (by code setting the mode with <code>player.ship.chartHightlightMode</code>. "newMode" is the new mode of the chart highlight, and will be one of the following:

OOLRC_MODE_SUNCOLOR
OOLRC_MODE_ECONOMY
OOLRC_MODE_GOVERNMENT
OOLRC_MODE_TECHLEVEL

this.chartHightlightModeChanged = function(newMode)
{
// Your code here
}

==== <code>compassTargetChanged</code> ====

The <code>compassTargetChanged</code> handler is called when a new target is selected. Mode can be any of the following:

COMPASS_MODE_BASIC
COMPASS_MODE_PLANET
COMPASS_MODE_STATION
COMPASS_MODE_SUN
COMPASS_MODE_TARGET
COMPASS_MODE_BEACONS

script example

this.compassTargetChanged = function(whom, mode)
{
log(' Now targeting ' + whom);
// Your code here
}

==== <code>dayChanged</code> ====
{{oolite-method-added|1.77}}

The <code>dayChanged</code> handler is called each time a new day starts. At very low frame rates while the clock is updating, it is possible for this handler to be called twice in the same frame. Therefore, clock.days will not be correct for one of the calls. Use the day number passed to the function instead.

this.dayChanged = function(newday)
{
// Your code here
}

==== <code>escapePodSequenceOver</code> ====

The <code>escapePodSequenceOver</code> handler is called at the end of the escape pod sequence, after the <code>shipLaunchedEscapePod</code> event and just prior to the <code>shipWillDockWithStation</code> and <code>shipDockedWithStation</code> events.

Use this function if you need to override the destination for the escape pod with the player method [[Oolite_JavaScript_Reference:_Player#setEscapePodDestination|<code>player.setEscapePodDestination()</code>]].

this.escapePodSequenceOver = function()
{
// Your code here
}

==== <code>guiScreenChanged</code> ====

The <code>guiScreenChanged</code> handler is called when the guiScreen changes. "from" is the screen it is changing from and "to" is the screen were it initially switched to. Note that the screen can have changed again in the meantime by the action of other oxps. Therefor, it will generally better to test for the global <code>guiScreen</code> to see which page is really on display instead of using the "to" parameter. (world script only) 
This handler will not fire for every screen the player can switch to, but only when switching to any of the following screens:

1.76: <code>GUI_SCREEN_MAIN, GUI_SCREEN_STATUS, GUI_SCREEN_MANIFEST, GUI_SCREEN_SYSTEM_DATA, GUI_SCREEN_OPTIONS, GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_SHIPYARD, GUI_SCREEN_SHORT_RANGE_CHART, GUI_SCREEN_LONG_RANGE_CHART, GUI_SCREEN_MARKET, GUI_SCREEN_CONTRACTS, GUI_SCREEN_REPORT</code>

1.77: adds <code>GUI_SCREEN_INTERFACES</code> and removes <code>GUI_SCREEN_CONTRACTS</code>

this.guiScreenChanged = function(to, from)
{
// Your code here
}

==== <code>guiScreenWillChange</code> ====

The <code>guiScreenWillChange</code> handler is called when the guiScreen is about to change. It only fires for the screens: <code>GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_MANIFEST, GUI_SCREEN_MARKET, GUI_SCREEN_SHIPYARD</code> and <code>GUI_SCREEN_SYSTEM_DATA</code> (in 1.77, also <code>GUI_SCREEN_STATUS</code>). On these screens a script could change the content of the page to be displayed. (world script only)

this.guiScreenWillChange = function(to, from)
{
// Your code here
}

==== <code>infoSystemChanged</code> ====
{{oolite-method-added|1.83}}

The <code>infoSystemChanged</code> handler is called when the system displayed in F7 is changed, e.g. by moving the small blue cursor along the planned route in the chart.

this.infoSystemChanged = function(to, from)
{
// Your code here
}

==== <code>infoSystemWillChange</code> ====
{{oolite-method-added|1.85}}

The <code>infoSystemWChange</code> handler is called just before the system displayed in F7 is updated, e.g. by moving the small blue cursor along the planned route in the chart.

this.infoSystemWillChange = function(to, from)
{
// Your code here
}

==== <code>mfdKeyChanged</code> ====
{{oolite-method-added|1.85}}

The <code>mfdKeyChanged</code> handler is called whenever the player changes the content of an MFD slot. The <code>activeMFD</code> parameter identifies which MFD slot is being changed, and the <code>mfdKey</code> specifies the key code now in use in this slot.

this.mfdKeyChanged = function(activeMFD : integer, mfdKey : string)
{
// Your code here
}

'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#setMultiFunctionDisplay|PlayerShip.setMultiFunctionDisplay()]]</code>

==== <code>missionChoiceWasReset</code> ====

The <code>missionChoiceWasReset</code> handler is called when the mission choice is set to null via script (either using the legacy script method resetMissionChice, or using mission.choice = null; in javascript)

this.missionChoiceWasReset= function()
{
// Your code here
}

==== <code>missionScreenEnded</code> ====

The <code>missionScreenEnded</code> handler is called when the missionscreen ends. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

this.missionScreenEnded = function()
{
// Your code here
}

==== <code>missionScreenOpportunity</code> ====

The <code>missionScreenOpportunity</code> handler is called if there are no mission / report screens active, and the player is docked to a station. It gets fired at game startup, upon docking, and after a docking report or previous mission screen has ended. (world script only)

this.missionScreenOpportunity= function()
{
// Your code here
}

This handler works a bit different as other handlers. It fires for every installed oxp, until an oxp creates a mission screen during this handler. Than it stops. When the mission screen ends and there is no callback function that created a new mission screen, than the missionScreenOpportunity is send again to all installed oxps, starting with the oxp that used the mission screen as last one. All this means that when this handler fires, it is safe to show a mission screen and no further test are needed.

==== <code>reportScreenEnded</code> ====

The <code>reportScreenEnded</code> handler is called when the last arrival-report screen ends. This is a screen that should not be written by a missionscreen. The code should wait until this eventhandler fires. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

this.reportScreenEnded = function()
{
// Your code here
}

==== <code>selectedMFDChanged</code> ====
{{oolite-method-added|1.85}}

The <code>selectedMFDChanged</code> handler is send whenever the player selects a new MFD slot (normally using the default keypress ";"). The <code>activeMFD</code> paramater is the index of the MFD which is now active.

this.selectedMFDChanged = function(activeMFD : integer)
{
// Your code here
}

==== <code>shipCollided</code> ====

The <code>shipCollided</code> handler is send after a collision with otherShip.

this.shipCollided = function(otherShip)
{
// Your code here
}

==== <code>shipSpawned</code> ====

The <code>shipSpawned</code> handler is called after an NPC ship has been added to the system. After a witchspace jump it means that first all ships are added to the system, then all the relevant shipSpawned events are triggered. 
This handler for the worldScript is new since Oolite 1.74. After the event is sent to the shipScript, it is now also send to the worldScript with the added entity as argument.

this.shipSpawned = function(ship)
{
// Your code here
}

==== <code>shipLaunchedEscapePod</code> ====

The <code>shipLaunchedEscapePod</code> handler is called when the player bails out. This will be followed by the <code>escapePodSequenceOver</code> event, and then a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds.

this.shipLaunchedEscapePod = function(escapepod)
{
// Your code here
}

==== <code>systemInformationChanged</code> ====
{{oolite-method-added|1.79}}

The <code>systemInformationChanged</code> handler is called when system information is modified. It is passed the galaxy and system ID which were changed, and the key and new value in the SystemInfo object.

To avoid problems with recursion, attempting to change the value of any system information property from within this function will fail and log an error. Also note that changes which take place while Oolite is not running (from OXP planetinfo.plist files) will not cause this handler to be called when the game is reloaded.

this.systemInformationChanged = function(galaxy,system,key,newValue)
{
// Your code here
}

==== <code>viewDirectionChanged</code> ====

The <code>viewDirectionChanged</code> handler is called when the player view changes, with a string to indicate which view the player is facing. Amongst its possible values are "VIEW_FORWARD", "VIEW_AFT", "VIEW_PORT", "VIEW_STARBOARD",
"VIEW_CUSTOM",
"VIEW_GUI_DISPLAY".

this.viewDirectionChanged = function(viewString)
{
if (viewString == "VIEW_PORT")
{
// Your code here
}
}

=== System population ===

In Oolite 1.79 and later, functions are called to populate and repopulate the system. These functions do not have fixed names, as they depend on the system, but otherwise act like normal worldscript functions. [[Oolite System Populator|The populator page]] has more documentation on these functions.

=== Defunct ===

==== <code>equipmentDestroyed</code> ====
''Handler no longer exists in current stable version 1.80''

The <code>equipmentDestroyed</code> handler is called when equipment gets destroyed completely beyond repair. (in strict mode, 1.77 or earlier only) (world script only)

this.equipmentDestroyed = function(equipment)
{
// Your code here
}

==== <code>tickle</code> (removed in 1.77) ====

The <code>tickle</code> handler is called periodically-ish, whenever the old [[property list|plist]] scripts are updated. <code>tickle()</code> is deprecated. In new code, use appropriate event handlers or [[Oolite JavaScript Reference: Timer|timers]] instead.

=== Missing Events ===

All the initially planned events have been implemented in 1.74.

If there are other events you would like to be able to respond to, please write a request [http://www.aegidian.org/bb/viewtopic.php?t=3296 on the forum].

'''See also:''' [[Oolite JavaScript Reference: Ship script event handlers|ship script event handlers]]

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: World script event handlers

2020-06-24T11:58:30Z

Milo: playerStartedAutoPilot is called with an argument

This page provides a list of event handlers which can be implemented inside world scripts [[Scripting Oolite with JavaScript|JavaScript scripts for Oolite]]. Additionally, ship script handlers called on the player's ship will cause an equivalent world script event.

Most event handlers can be used both in world scripts and in ship scripts. Generally speaking, handlers starting with "ship" can be used for both scripts and those starting with "player" are meant only for the player (= can only be used in a world script). Exceptions on this rule are mentioned with the individual handlers below.

World scripts can be either found inside Config\script.js, or be distinctly named .js files inside the Scripts directory - in the latter case, the worldScript.plist will list the active world scripts.

World scripts are always active.

The list of event handlers will change from version to version (usually additions of extra handlers). For this reason, any variables or functions you create as <code>this.variable</code> should have a name beginning with '_' or '$' - e.g. <code>this._variable</code> or <code>this.$variable</code> - to avoid potential conflicts with future event handlers (which will never start with '_' or '$').

=== Game State ===

==== <code>gamePaused</code> ====
{{oolite-method-added|1.81}}

This event is called when the game is paused. This is mainly useful for pausing sound playback which should not continue while the game is paused.

this.gamePaused = function()
{
// Your code here
}

==== <code>gameResumed</code> ====
{{oolite-method-added|1.81}}

This event is called when the game is resumed from pause. This is mainly useful for resuming sound playback paused in a <code>gamePaused</code> handler.

this.gameResumed = function()
{
// Your code here
}

==== <code>playerWillSaveGame</code> ====

The <code>playerWillSaveGame</code> handler is called whenever the player saves a game. The transferred message is one of the following strings: 'standardSave', 'autoSave' or 'quickSave'

this.playerWillSaveGame = function(message : String)
{
// Your code here
}

Using this event is useful for storing temporary variables in missionVariables, just before the game gets saved. missionVariables are slow in use compared to normal JS variables, therefor their use should be minimised for efficient code. The main benefit of using missionVariables is that they are saved in a saved game.

==== <code>startUp</code> ====

The <code>startUp</code> handler is called after all OXPs have been loaded. This also means that it is called every time the player loads a game, begins a new game or presses space after dying. It can be used to do one-off initialisation such as copying mission variables into <code>this.*</code> properties for efficiency or setting up data arrays to be used by the script in other handlers. (world script only)

this.startUp = function()
{
// Your code here
}

Note that from Oolite 1.79 onwards the player will be in the main station while this function is run, but may be moved from there to another station soon after.

==== <code>startUpComplete</code> ====
{{oolite-method-added|1.79}}

The <code>startUpComplete</code> handler is run at game startup after the initial population of the system has been complete, and after the player has been moved to the station recorded in their save game. The order of world events at game start is therefore:
* <code>startUp</code>
* <code>systemWillPopulate</code> (or an alternative handler specified by the system info)
* <code>startUpComplete</code>

=== Docking ===

==== <code>shipWillDockWithStation</code> ====

The <code>shipWillDockWithStation</code> handler is called at the beginning of the docking tunnel effect.

this.shipWillDockWithStation = function(station)
{
// Your code here
}
At this moment "ship.dockedStation == null", "ship.docked == true", "ship.status == STATUS_DOCKING"

==== <code>shipDockedWithStation</code> ====

The <code>shipDockedWithStation</code> handler is called at the end of the docking tunnel effect.

this.shipDockedWithStation = function(station)
{
// Your code here
}
At this moment "ship.dockedStation == the station", "ship.docked == true", "ship.status == STATUS_DOCKED" and "gui_screen" is either GUI_SCREEN_STATUS or GUI_SCREEN_REPORT. However, any identical handler from an other oxp could have changed those values. Never count on it but double check when important.

==== <code>shipWillLaunchFromStation</code> ====

The <code>shipWillLaunchFromStation</code> handler is called at the beginning of the launch tunnel effect.

this.shipWillLaunchFromStation = function(station)
{
// Your code here
}
At this moment "ship.dockedStation == the station", "ship.docked == false", "ship.status == STATUS_LAUNCHING".

==== <code>shipLaunchedFromStation</code> ====

The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect.

this.shipLaunchedFromStation = function(station)
{
// Your code here
}
At this moment "ship.dockedStation == null", "ship.docked == false", "ship.status == STATUS_IN_FLIGHT".

==== <code>playerStartedAutoPilot</code> ====

The <code>playerStartedAutoPilot</code> handler is called when the player starts autopilot docking. It is not called for the instantaneous dock command. The handler is called with an argument containing the station entity that is the docking target.

this.playerStartedAutoPilot = function(stationForDocking)
{
// Your code here
}

==== <code>playerCancelledAutoPilot</code> ====

The <code>playerCancelledAutoPilot</code> handler is called when the player cancels autopilot docking.

this.playerCancelledAutoPilot = function()
{
// Your code here
}

==== <code>playerDockingClearanceCancelled</code> ====
{{oolite-method-added|1.85}}

The <code>playerDockingClearanceCancelled</code> handler is called when the player withdraws their request to dock at a station.

this.playerDockingClearanceCancelled = function()
{
// Your code here
}

==== <code>playerDockingClearanceExpired</code> ====
{{oolite-method-added|1.83}}

The <code>playerDockingClearanceExpired</code> handler is called when the player exceeds the two minute window without requesting an extension

this.playerDockingClearanceExpired = function()
{
// Your code here
}

==== <code>playerDockingClearanceGranted</code> ====
{{oolite-method-added|1.85}}

The <code>playerDockingClearanceGranted</code> handler is called when the player is given permission to dock at a station. If the player is given immediate clearance to dock, this event will be called immediately after the <code>playerRequestedDockingClearance</code> event. If, however, the station is unable to give immediate clearance, then there will be some delay between the request to dock and permission being granted. This event will be called when the station actually gives docking clearance.

this.playerDockingClearanceGranted = function()
{
// Your code here
}

==== <code>playerDockingRefused</code> ====

The <code>playerDockingRefused</code> handler is called when a station refuses to provide autopilot docking instructions.

this.playerDockingRefused = function()
{
// Your code here
}

==== <code>playerRequestedDockingClearance</code> ====

The <code>playerRequestedDockingClearance</code> handler is called when a station answers on a docking request of the player by targeting the station and pressing L (shift-l).

this.playerRequestedDockingClearance = function(message)
{
// Your code here
}

Message is a string and can take the values: "DOCKING_CLEARANCE_GRANTED", "DOCKING_CLEARANCE_DENIED_TRAFFIC_OUTBOUND", "DOCKING_CLEARANCE_DENIED_TRAFFIC_INBOUND", "DOCKING_CLEARANCE_DENIED_SHIP_FUGITIVE", "DOCKING_CLEARANCE_NOT_REQUIRED", "DOCKING_CLEARANCE_EXTENDED" or "DOCKING_CLEARANCE_CANCELLED".

==== <code>playerRescuedEscapePod</code> ====
{{oolite-method-added|1.81}}

The <code>playerRescuedEscapePod</code> handler is called when the player rescues an escape pod which does not have scripted content (all consequences of scripted content escape pods are assumed to be dealt with by the specified script instead). It has three parameters:
# the rescue fee, in decicredits
# the fee reason, which can be "insurance", "bounty" or "slave" (in the latter case, the fee will always be zero)
# a dictionary like those in the <code>ship.crew</code> property describing the pod occupant

this.playerRescuedEscapePod = function(fee, reason, occupant)
{
// Your code here
}

This method is called after the escape pod has been processed, but slightly before the arrival report screen giving the results of the processing is displayed to the player.

==== <code>playerCompletedContract</code> ====
{{oolite-method-added|1.81}}

The <code>playerCompletedContract</code> handler is called when a passenger, parcel or cargo contract ends, either successfully or by defaulting on it. It is not called when all contracts are cancelled on a galactic jump. It has four parameters:
# The type of contract, which can be "cargo", "parcel" or "passenger"
# The result of the contract, which can be "success", "late", "failed", or for cargo contracts only "short"
# The fee paid for the contract in decicredits
# The contract information dictionary
Note that the fee actually paid for the contract will often ''not'' match the originally agreed fee in the contract information dictionary, as penalties for late delivery or bonuses for good service are included in the fee parameter.

this.playerCompletedContract = function(type, result, fee, contract)
{
// Your code here
}

This method is called after the contract has been processed, but slightly before the arrival report screen giving the results of the processing is displayed to the player.

==== <code>playerEnteredContract</code> ====
{{oolite-method-added|1.81}}

The <code>playerEnteredContract</code> handler is called when a passenger, parcel or cargo contract starts, just after the items have been transferred to the player ship. It has two parameters:
# The type of contract, which can be "cargo", "parcel" or "passenger"
# The contract information dictionary

this.playerEnteredContract = function(type, contract)
{
// Your code here
}

=== Witchspace Jumps ===

==== <code>playerStartedJumpCountdown</code> ====

The <code>playerStartedJumpCountdown</code> handler is called when the user starts a witchspace or galactic witchspace jump countdown. The <code>type</code> parameter is a string specifying which type of jump is occuring; currently, the possible values are “standard” and “galactic”. Other values may be added in future. The <code>seconds</code> parameter is a number specifying the number of seconds the countdown is running for.

this.playerStartedJumpCountdown = function(type, seconds)
{
// Your code here
}

==== <code>playerCancelledJumpCountdown</code> ====

The <code>playerCancelledJumpCountdown</code> handler is called when the user cancels a witchspace or galactic witchspace jump countdown.

this.playerCancelledJumpCountdown = function()
{
// Your code here
}

==== <code>playerJumpFailed</code> ====

The <code>playerJumpFailed</code> handler is called at the end of a witchspace or galactic witchspace countdown, if the jump is not possible. The <code>reason</code> parameter is a string specifying why the jump failed. The current values are:
* '''"insufficient fuel"''' - the ship no longer has enough fuel to make the jump (e.g. injector use or fuel leak).
* '''"blocked"''' - a heavy ship is near the player (specifically <code>object mass</code> / <code>object distance</code>2 >= 10.0, and <code>object distance</code> <= scanner range).
* '''"malfunction"''' - the jump malfunctioned in a way that leaves the player ship in the current system.
* '''"malfunction"''' - the Galactic Hyperdrive is damaged or removed during a galactic jump countdown.

Also theoretically possible but unlikely in current Oolite:
* '''"too far"''' - the jump destination is outside the 7LY range (but wasn't when the countdown started).
* '''"no target"''' - the jump destination is the current location (but wasn't when the countdown started).

this.playerJumpFailed = function(reason)
{
// Your code here
}

==== <code>shipWillEnterWitchspace</code> ====

The <code>shipWillEnterWitchspace</code> handler is called immediately before a witchspace jump, while the player is still in the starting system. The <code>cause</code> parameter is a string specifying what sort of jump is occuring; currently, the possible values are “standard jump”, “galactic jump” and “wormhole”. Other values may be added in future.

// 1.80 or earlier
this.shipWillEnterWitchspace = function(cause)
{
// Your code here
}

In 1.81 or later the handler gains a second parameter, describing the jump destination. For standard and wormhole jumps, this will be the system ID of the destination system. For galactic jumps, this will be the galaxy ID of the destination galaxy. (As [[Oolite JavaScript Reference: PlayerShip#galacticHyperspaceBehaviour|player.ship.galacticHyperspaceBehaviour]] may be changed during <code>shipWillEnterWitchspace</code>, it is not possible to predict in advance of a galactic jump being made what the resulting system ID in the destination galaxy will be)

// 1.81 or later
this.shipWillEnterWitchspace = function(cause, destination)
{
// Your code here
}

==== <code>shipWillExitWitchspace</code> ====

The <code>shipWillExitWitchspace</code> handler is called as a witchspace jump concludes. When it is called, the player is (from a program perspective) in the destination system, but the tunnel effect has not yet been shown. Use this event to set up elements which need to be present in-system after the player exits witchspace.

this.shipWillExitWitchspace = function()
{
// Your code here
}

==== <code>shipExitedWitchspace</code> ====

The <code>shipExitedWitchspace</code> handler is called after a witchspace jump has concluded and the tunnel effect has been shown.

this.shipExitedWitchspace = function()
{
// Your code here
}

==== <code>playerEnteredNewGalaxy</code> ====

The <code>playerEnteredNewGalaxy</code> handler is called just before shipWillExitWitchspace.

the sequence of events for a player jumping to a different galaxy is as follows:

shipWillEnterWitchspace (world event) 
playerWillEnterWitchspace (NPC ship event) 
playerEnteredNewGalaxy (world event) 
shipWillExitWitchspace (world event) 
shipExitedWitchspace (world event) 

this.playerEnteredNewGalaxy = function(galaxyNumber)
{
// Your code here
}

=== Enter/Exit Aegis ===

==== <code>shipEnteredStationAegis</code> ====

The <code>shipEnteredStationAegis</code> handler is called when the player enters the aegis of the main-station (2x scanner range from main-station). Other stations than the main-station don't give aegis messages.

this.shipEnteredStationAegis = function(station)
{
// Your code here
}

==== <code>shipExitedStationAegis</code> ====

The <code>shipExitedStationAegis</code> handler is called when the player leaves the aegis of the main-station (2x scanner range from main-station).

this.shipExitedStationAegis = function(station)
{
// Your code here
}

==== <code>shipEnteredPlanetaryVicinity</code> ====

The <code>shipEnteredPlanetaryVicinity</code> handler is called when the player enters the planet aegis (3x planet radius).

this.shipEnteredPlanetaryVicinity = function(planet)
{
// Your code here
}

==== <code>shipExitedPlanetaryVicinity</code> ====

The <code>shipExitedPlanetaryVicinity</code> handler is called when the player leaves the planet aegis (3x planet radius).

this.shipExitedPlanetaryVicinity = function(planet)
{
// Your code here
}

==== <code>shipApproachingPlanetSurface</code> ====

The <code>shipApproachingPlanetSurface</code> handler is called when the player is very close to the planet (crosses a border ± 500 meter above the surface).

this.shipApproachingPlanetSurface = function(planet)
{
// Your code here
}

==== <code>shipLeavingPlanetSurface</code> ====

The <code>shipLeavingPlanetSurface</code> handler is called when the player leaves the planet (crosses a border ± 500 meter above the surface).

this.shipLeavingPlanetSurface = function(planet)
{
// Your code here
}

=== Combat ===

==== <code>alertConditionChanged</code> ====

The <code>alertConditionChanged</code> handler is called when the player’s alert status (<code>[[Oolite JavaScript Reference: Player#alertCondition|player.alertCondition]]</code>) changes. Only the player and stations have an alert condition. (world script and station scripts)

this.alertConditionChanged = function(newCondition, oldCondition)
{
// Your code here
}

==== <code>playerTargetedMissile</code> ====

The <code>playerTargetedMissile</code> handler is called when the player targets the nearest missile by pressing T (shift-t) on the keybord.

this.playerTargetedMissile = function(missile)
{
// Your code here
}

==== <code>shipAttackedOther</code> ====

The <code>shipAttackedOther</code> handler is called when the player hits another with a laser shot. <code>other</code> is the identity of the ship being hit.

this.shipAttackedOther = function(other)
{
// Your code here
}

==== <code>shipAttackedWithMissile</code> ====

The <code>shipAttackedWithMissile</code> handler is called when a missile is fired. <code>missile</code> contains the missile entity and <code>whom</code> the identity of the ship that launched the missile.

this.shipAttackedWithMissile = function(missile, whom)
{
// Your code here
}

==== <code>shipBeingAttacked</code> ====

The <code>shipBeingAttacked</code> handler is called when a laser shot hits. <code>whom</code> the identity of the ship that attacked.

this.shipBeingAttacked = function(whom)
{
// Your code here
}

==== <code>shipBeingAttackedByCloaked</code> ====

The <code>shipBeingAttackedByCloaked</code> handler is called when a laser shot from a cloaked ship hits. Guess what, there is no parameter because he is cloaked!

this.shipBeingAttackedByCloaked = function()
{
// Your code here
}

==== <code>shipKilledOther</code> ====
{{oolite-method-added|1.75}}

The <code>shipKilledOther</code> handler is called when a ship kills an other ship. <code>whom</code> the identity of the ship that was killed. <code>damageType</code> is the type of damage.

this.shipKilledOther = function(whom : ship, damageType : string)
{
// Your code here
}

==== <code>shipReleasedEquipment</code> ====

The <code>shipReleasedEquipment</code> handler is called when a ship launches a mine (a pylon-mounted equipment item whose key ends with "_MINE"). <code>mine</code> contains the launched mine entity.

this.shipReleasedEquipment = function(mine)
{
// Your code here
}

==== <code>shipTargetDestroyed</code> ====

The <code>shipTargetDestroyed</code> handler is called when the target gets destroyed by the player. <code>target</code> contains the destroyed target entity. This command is always preceded by the <code>shipTargetLost</code> handler.

this.shipTargetDestroyed = function(target)
{
// Your code here
}

==== <code>shipDied</code> ====

The <code>shipDied</code> handler is called when the ship or player dies. Expect a <code>reset()</code> shortly when it is the player ship.

this.shipDied = function(whom, why)
{
// Your code here
}
'''whom''' contains the entity that caused the kill. '''why''' is the cause written as string and is one of: "removed", "hit a planet", "energy damage", "scrape damage", "heat damage", "cascade weapon". 
("cascade weapon" is new in 1.74 and "removed" / "energy damage" were accidentally switched in 1.73)

==== <code>shipFiredMissile</code> ====

The <code>shipFiredMissile</code> handler is called when a missile is fired. <code>missile</code> contains the missile entity and <code>target</code> the identity of the target. The handler is send to the ship that launched the missile.

this.shipFiredMissile = function(missile, target)
{
// Your code here
}

==== <code>shipTargetLost</code> ====

The <code>shipTargetLost</code> handler is called when the target gets lost. <code>target</code> contains the lost target entity.

this.shipTargetLost = function(target)
{
// Your code here
}

==== <code>shipTargetCloaked</code> ====

The <code>shipTargetCloaked</code> handler is called when the target cloakes.

this.shipTargetCloaked = function()
{
// Your code here
}

==== <code>weaponsSystemsToggled</code> ====
{{oolite-method-added|1.85}}

The <code>weaponsSystemsToggled</code> handler is called whenever the player toggles their weapons systems on or off. The <code>state</code> parameter contains the new state of the weapons systems

this.weaponsSystemsToggled = function(state : boolean)
{
// Your code here
}

=== Equipment and Cargo ===

==== <code>equipmentAdded</code> ====
{{Oolite-method-added|1.81}}

The <code>equipmentAdded</code> handler is called whenever the player ship gains an item of equipment. This includes "gaining" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is damaged. This event will fire regardless of the reason for the equipment being added to the ship.

this.equipmentAdded = function(equipmentKey)
{
// Your code here
}

This is often more convenient than monitoring both <code>equipmentRepaired</code> and <code>playerBoughtEquipment</code>, and will also detect equipment addition by script.

==== <code>equipmentDamaged</code> ====

The <code>equipmentDamaged</code> handler is called when equipment gets damaged. (world script only)

this.equipmentDamaged = function(equipment)
{
// Your code here
}

==== <code>equipmentRemoved</code> ====
{{Oolite-method-added|1.81}}

The <code>equipmentRemoved</code> handler is called whenever the player ship loses an item of equipment. This includes "losing" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is repaired. This event will fire regardless of the reason for the equipment being removed from the ship.

this.equipmentRemoved = function(equipmentKey)
{
// Your code here
}

==== <code>equipmentRepaired</code> ====
{{Oolite-method-added|1.77}}

The <code>equipmentRepaired</code> handler is called when equipment gets repaired. (world script only)

this.equipmentRepaired = function(equipment)
{
// Your code here
}

==== <code>playerBoughtCargo</code> ====
{{Oolite-method-added|1.77}}

The <code>playerBoughtCargo</code> handler is called when cargo is bought at the market screen. <code>commodity</code> contains the non-localised name for the cargo. You can get the localised name using <code>expandDescription("[commodity-name "+commodity+"]");</code>. <code>price</code> is price per unit in tenths of a credit.

this.playerBoughtCargo = function(commodity, units, price)
{
// Your code here
}

==== <code>playerBoughtEquipment</code> ====

The <code>playerBoughtEquipment</code> handler is called when equipment is bought at the outfit screen.

this.playerBoughtEquipment = function(equipment, paid)
{
// Your code here
}

The 'paid' parameter is added from 1.89 onwards. This is the amount of credits the player paid for the equipment, including any refunds that might have been applied during the purchase (eg when purchasing a laser and installing it in a position where a laser is already fitted, the cost of the current laser will be refunded to the player during the purchase).

==== <code>playerBoughtNewShip</code> ====

The <code>playerBoughtNewShip</code> handler is called when a new ship is bought. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerBoughtNewShip = function(ship, price)
{
// Your code here
}

The 'price' parameter is added from 1.81 onwards. It is the cost of the ship (not counting any trade-in value of the player's old ship) in credits, or zero for changes using [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip</code>]]

'''Note:''' In a future release of Oolite, <code>playerBoughtNewShip</code> will no longer be fired when the ship is replaced using the [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip</code>]] function. Instead, the <code>[[#playerReplacedShip|playerReplacedShip]]</code> event should be used. At the moment, both events (<code>playerBoughtNewShip</code> and <code>playerReplacedShip</code>) will fire.

'''See also:''' <code>[[#playerWillBuyNewShip|playerWillBuyNewShip]]</code>

==== <code>playerChangedPrimedEquipment</code> ====
{{Oolite-method-added|1.85}}

The <code>playerChangedPrimedEquipment</code> handler is called whenever the player changes the currently primed equipment (either with shift-n or ctrl-shift-n). The equipment key of the newly primed equipment will be passed as an argument.

this.playerChangedPrimedEquipment = function(equipmentKey)
{
// Your code here
}

==== <code>playerReplacedShip</code> ====
{{Oolite-method-added|1.89}}

The <code>playerReplacedShip</code> handler is called when the player ship is replaced via the JS method [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip</code>]]. May be needed to re-evaluate the old equipment as replacing a ship does not trigger equipment removal.

this.playerReplacedShip = function(ship)
{
// Your code here
}

'''See also:''' <code>[[#playerWillReplaceShip|playerWillReplaceShip]]</code>

==== <code>playerSoldCargo</code> ====
{{Oolite-method-added|1.77}}

The <code>playerSoldCargo</code> handler is called when cargo is sold at the market screen. <code>commodity</code> contains the non-localised name for the cargo. You can get the localised name using <code>expandDescription("[commodity-name "+commodity+"]");</code>. <code>price</code> is price per unit in tenths of a credit.

this.playerSoldCargo = function(commodity, units, price)
{
// Your code here
}

==== <code>shipScoopedFuel</code> ====
{{Oolite-method-added|1.77}}

The <code>shipScoopedFuel</code> handler is called whenever the player's ship transfers 0.1LY of fuel from the scoops to the tank.

this.shipScoopedFuel = function()
{
// Your code here
}

==== <code>shipScoopedOther</code> ====

The <code>shipScoopedOther</code> handler is called when a ship scoops cargo. The scooped item is transferred as argument. If the cargo is scripted cargo, but not otherwise, then the scooped cargo itself gets the handler <code>shipWasScooped</code> with the scooper as argument.

this.shipScoopedOther = function(whom)
{
// Your code here
}

==== <code>playerWillBuyNewShip</code> ====
{{Oolite-method-added|1.89}}

The <code>playerWillBuyNewShip</code> handler is called just before a new ship is bought. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerWillBuyNewShip = function(dataKey, shipyard, price, tradeIn)
{
// Your code here
}

<code>dataKey</code> is the shipdata.plist <code>dataKey</code> for the ship being purchased.

<code>shipyard</code> is a dictionary object containing details about the ship being purchased, with information 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"]
}

<code>price</code> is the amount being paid the for ship.

<code>tradeIn</code> is the trade in value of the current ship.

'''See also:''' <code>[[#playerBoughtNewShip|playerBoughtNewShip]]</code>

==== <code>playerWillReplaceShip</code> ====
{{Oolite-method-added|1.89}}

The <code>playerWillReplaceShip</code> handler is called just before a ship is replaced using the [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip</code>]] function. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerWillReplaceShip = function(dataKey)
{
// Your code here
}

<code>dataKey</code> is the shipdata.plist <code>dataKey</code> for the ship being purchased.

'''See also:''' <code>[[#playerReplacedShip|playerReplacedShip]]</code>

=== Other ===

==== <code>chartHightlightModeChanged</code> ====
{{oolite-method-added|1.87}}

The <code>chartHighlightModeChanged</code> handler is called whenever the highlight mode of the galactic chart is changed, either manually (from player input), or programmatically (by code setting the mode with <code>player.ship.chartHightlightMode</code>. "newMode" is the new mode of the chart highlight, and will be one of the following:

OOLRC_MODE_SUNCOLOR
OOLRC_MODE_ECONOMY
OOLRC_MODE_GOVERNMENT
OOLRC_MODE_TECHLEVEL

this.chartHightlightModeChanged = function(newMode)
{
// Your code here
}

==== <code>compassTargetChanged</code> ====

The <code>compassTargetChanged</code> handler is called when a new target is selected. Mode can be any of the following:

COMPASS_MODE_BASIC
COMPASS_MODE_PLANET
COMPASS_MODE_STATION
COMPASS_MODE_SUN
COMPASS_MODE_TARGET
COMPASS_MODE_BEACONS

script example

this.compassTargetChanged = function(whom, mode)
{
log(' Now targeting ' + whom);
// Your code here
}

==== <code>dayChanged</code> ====
{{oolite-method-added|1.77}}

The <code>dayChanged</code> handler is called each time a new day starts. At very low frame rates while the clock is updating, it is possible for this handler to be called twice in the same frame. Therefore, clock.days will not be correct for one of the calls. Use the day number passed to the function instead.

this.dayChanged = function(newday)
{
// Your code here
}

==== <code>escapePodSequenceOver</code> ====

The <code>escapePodSequenceOver</code> handler is called at the end of the escape pod sequence, after the <code>shipLaunchedEscapePod</code> event and just prior to the <code>shipWillDockWithStation</code> and <code>shipDockedWithStation</code> events.

Use this function if you need to override the destination for the escape pod with the player method [[Oolite_JavaScript_Reference:_Player#setEscapePodDestination|<code>player.setEscapePodDestination()</code>]].

this.escapePodSequenceOver = function()
{
// Your code here
}

==== <code>guiScreenChanged</code> ====

The <code>guiScreenChanged</code> handler is called when the guiScreen changes. "from" is the screen it is changing from and "to" is the screen were it initially switched to. Note that the screen can have changed again in the meantime by the action of other oxps. Therefor, it will generally better to test for the global <code>guiScreen</code> to see which page is really on display instead of using the "to" parameter. (world script only) 
This handler will not fire for every screen the player can switch to, but only when switching to any of the following screens:

1.76: <code>GUI_SCREEN_MAIN, GUI_SCREEN_STATUS, GUI_SCREEN_MANIFEST, GUI_SCREEN_SYSTEM_DATA, GUI_SCREEN_OPTIONS, GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_SHIPYARD, GUI_SCREEN_SHORT_RANGE_CHART, GUI_SCREEN_LONG_RANGE_CHART, GUI_SCREEN_MARKET, GUI_SCREEN_CONTRACTS, GUI_SCREEN_REPORT</code>

1.77: adds <code>GUI_SCREEN_INTERFACES</code> and removes <code>GUI_SCREEN_CONTRACTS</code>

this.guiScreenChanged = function(to, from)
{
// Your code here
}

==== <code>guiScreenWillChange</code> ====

The <code>guiScreenWillChange</code> handler is called when the guiScreen is about to change. It only fires for the screens: <code>GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_MANIFEST, GUI_SCREEN_MARKET, GUI_SCREEN_SHIPYARD</code> and <code>GUI_SCREEN_SYSTEM_DATA</code> (in 1.77, also <code>GUI_SCREEN_STATUS</code>). On these screens a script could change the content of the page to be displayed. (world script only)

this.guiScreenWillChange = function(to, from)
{
// Your code here
}

==== <code>infoSystemChanged</code> ====
{{oolite-method-added|1.83}}

The <code>infoSystemChanged</code> handler is called when the system displayed in F7 is changed, e.g. by moving the small blue cursor along the planned route in the chart.

this.infoSystemChanged = function(to, from)
{
// Your code here
}

==== <code>infoSystemWillChange</code> ====
{{oolite-method-added|1.85}}

The <code>infoSystemWChange</code> handler is called just before the system displayed in F7 is updated, e.g. by moving the small blue cursor along the planned route in the chart.

this.infoSystemWillChange = function(to, from)
{
// Your code here
}

==== <code>mfdKeyChanged</code> ====
{{oolite-method-added|1.85}}

The <code>mfdKeyChanged</code> handler is called whenever the player changes the content of an MFD slot. The <code>activeMFD</code> parameter identifies which MFD slot is being changed, and the <code>mfdKey</code> specifies the key code now in use in this slot.

this.mfdKeyChanged = function(activeMFD : integer, mfdKey : string)
{
// Your code here
}

'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#setMultiFunctionDisplay|PlayerShip.setMultiFunctionDisplay()]]</code>

==== <code>missionChoiceWasReset</code> ====

The <code>missionChoiceWasReset</code> handler is called when the mission choice is set to null via script (either using the legacy script method resetMissionChice, or using mission.choice = null; in javascript)

this.missionChoiceWasReset= function()
{
// Your code here
}

==== <code>missionScreenEnded</code> ====

The <code>missionScreenEnded</code> handler is called when the missionscreen ends. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

this.missionScreenEnded = function()
{
// Your code here
}

==== <code>missionScreenOpportunity</code> ====

The <code>missionScreenOpportunity</code> handler is called if there are no mission / report screens active, and the player is docked to a station. It gets fired at game startup, upon docking, and after a docking report or previous mission screen has ended. (world script only)

this.missionScreenOpportunity= function()
{
// Your code here
}

This handler works a bit different as other handlers. It fires for every installed oxp, until an oxp creates a mission screen during this handler. Than it stops. When the mission screen ends and there is no callback function that created a new mission screen, than the missionScreenOpportunity is send again to all installed oxps, starting with the oxp that used the mission screen as last one. All this means that when this handler fires, it is safe to show a mission screen and no further test are needed.

==== <code>reportScreenEnded</code> ====

The <code>reportScreenEnded</code> handler is called when the last arrival-report screen ends. This is a screen that should not be written by a missionscreen. The code should wait until this eventhandler fires. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

this.reportScreenEnded = function()
{
// Your code here
}

==== <code>selectedMFDChanged</code> ====
{{oolite-method-added|1.85}}

The <code>selectedMFDChanged</code> handler is send whenever the player selects a new MFD slot (normally using the default keypress ";"). The <code>activeMFD</code> paramater is the index of the MFD which is now active.

this.selectedMFDChanged = function(activeMFD : integer)
{
// Your code here
}

==== <code>shipCollided</code> ====

The <code>shipCollided</code> handler is send after a collision with otherShip.

this.shipCollided = function(otherShip)
{
// Your code here
}

==== <code>shipSpawned</code> ====

The <code>shipSpawned</code> handler is called after an NPC ship has been added to the system. After a witchspace jump it means that first all ships are added to the system, then all the relevant shipSpawned events are triggered. 
This handler for the worldScript is new since Oolite 1.74. After the event is sent to the shipScript, it is now also send to the worldScript with the added entity as argument.

this.shipSpawned = function(ship)
{
// Your code here
}

==== <code>shipLaunchedEscapePod</code> ====

The <code>shipLaunchedEscapePod</code> handler is called when the player bails out. This will be followed by the <code>escapePodSequenceOver</code> event, and then a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds.

this.shipLaunchedEscapePod = function(escapepod)
{
// Your code here
}

==== <code>systemInformationChanged</code> ====
{{oolite-method-added|1.79}}

The <code>systemInformationChanged</code> handler is called when system information is modified. It is passed the galaxy and system ID which were changed, and the key and new value in the SystemInfo object.

To avoid problems with recursion, attempting to change the value of any system information property from within this function will fail and log an error. Also note that changes which take place while Oolite is not running (from OXP planetinfo.plist files) will not cause this handler to be called when the game is reloaded.

this.systemInformationChanged = function(galaxy,system,key,newValue)
{
// Your code here
}

==== <code>viewDirectionChanged</code> ====

The <code>viewDirectionChanged</code> handler is called when the player view changes, with a string to indicate which view the player is facing. Amongst its possible values are "VIEW_FORWARD", "VIEW_AFT", "VIEW_PORT", "VIEW_STARBOARD",
"VIEW_CUSTOM",
"VIEW_GUI_DISPLAY".

this.viewDirectionChanged = function(viewString)
{
if (viewString == "VIEW_PORT")
{
// Your code here
}
}

=== System population ===

In Oolite 1.79 and later, functions are called to populate and repopulate the system. These functions do not have fixed names, as they depend on the system, but otherwise act like normal worldscript functions. [[Oolite System Populator|The populator page]] has more documentation on these functions.

=== Defunct ===

==== <code>equipmentDestroyed</code> ====
''Handler no longer exists in current stable version 1.80''

The <code>equipmentDestroyed</code> handler is called when equipment gets destroyed completely beyond repair. (in strict mode, 1.77 or earlier only) (world script only)

this.equipmentDestroyed = function(equipment)
{
// Your code here
}

==== <code>tickle</code> (removed in 1.77) ====

The <code>tickle</code> handler is called periodically-ish, whenever the old [[property list|plist]] scripts are updated. <code>tickle()</code> is deprecated. In new code, use appropriate event handlers or [[Oolite JavaScript Reference: Timer|timers]] instead.

=== Missing Events ===

All the initially planned events have been implemented in 1.74.

If there are other events you would like to be able to respond to, please write a request [http://www.aegidian.org/bb/viewtopic.php?t=3296 on the forum].

'''See also:''' [[Oolite JavaScript Reference: Ship script event handlers|ship script event handlers]]

[[Category:Oolite JavaScript Reference]]

IronHide OXP

2020-06-22T03:56:52Z

Milo: version 3.06

==Overview==
The Ships Systems Department of the Aquarian Shipbuilding Corporation introduce their latest development - IronHide armour. This is a simple but effective technology which applies a special treatment to the hull of the customer ship which helps to strengthen it against combat and physical damage in collaboration with the ship's shielding.

In practice the armour helps to absorb damage that gets past (or takes down) the shields, although if a truly concentrated attack occurs then localised penetration and energy damage may still occur. This is especially true of missile attacks, which can still cause internal damage and equipment failure due to concussion effects. The current strength of the armour can be viewed on the ship's manifest (F5-F5) screen, and any damage can be repaired at a suitably high-tech station.

The armour itself is available from all good tech 5 locations, for a recommended retail price of just 750 credits. These stations should also be able to quote for repairs to damaged installations. It should also be noted that insurers class armour as a combat consumable, and so its replacement is not included as part of the insurance for equipment such as escape pods and lifeboats.

A special enhanced upgrade for military uses has also been developed, and may be available to customers at tech 10 systems (the upgrade requires an undamaged civilian-grade installation). The upgrade doubles the effectiveness of the regular armour.

==Acknowledgements==
This OXP came about following a discussion over a beer with ClymAngus, and was one of my fastest-written OXPs (sketch-out concept to beta-test was around 7 hours on a boring day at work with nothing to do).

Thanks also to UK_Eliter and Caracal for beta-testing for me, and their feedback and comments.

== Discussion ==
You can find the IronHide discussion thread on the Oolite Bulletin Boards [http://www.aegidian.org/bb/viewtopic.php?t=8311 here].

==Version history==
<pre>
31/07/2010 - Version 1.00, initial release.

01/08/2010 - Version 1.01, changed shield strength from this. to mission variables to maintain across save games.

19/02/2011 - Version 2.00, upgrade for 1.75 trunk - and operating properly now after shields are gone!

19/06/2020 - Version 3.00, updated by Milo; IronHide OXP now requires Oolite 1.79+; armour durability increased but energy restoration is now proportional to damage absorbed (previously the ship's energy was fully restored after every hit, which could conflict with other OXPs' attempts to regulate energy levels); damage below 5 (10 for military grade) will not degrade IronHide armour; further improved compatibility with other OXPs by checking damage type instead of energy level to decide which damage the armour can absorb.

20/06/2020 - Version 3.01, updated by Milo; IronHide OXP now requires Oolite 1.82+; introduced a new script_info property in equipment.plist (ironHide_percentArmourLostPerDamagePointTaken), which functionally replaces the ironHide_strength mission variable (now unused by IronHide, but kept and returned to its pre-3.00 values because CombatMFD uses it for its SEE indicator); eliminated the "damage below X will not degrade armour" threshold (any damage that gets through shields now will consume armour); set damage_probability to zero so IronHide cannot be made "inoperable" (appear broken on the F5 screen) before it is fully consumed; introduced price variance for installation and repairs proportional to ship surface area (cobra3-player is the baseline); added installation_time of 12 hours for both civilian and military grades and a proportional time advance when repairing (repairing X percent is 25% faster than installing X percent, a small incentive to repair before the armour is destroyed; note that if military grade armour is fully consumed, you must first reinstall civilian grade [12 hrs] and then upgrade to military grade [12 hrs], so it saves even more time if you repair military grade before it breaks; also, while not a change from previous versions, military grade armour costs less to repair than it costs to install).

21/06/2020 - Version 3.02, updated by Milo; doubled price variance for larger ships and applied proportional adjustment to repair costs (they were still using the baseline price); improved compatibility with ShipVersion OXP by not offering IronHide for purchase on ships that ShipVersion does not allow to use it (when ShipVersion OXP is detected, civilian IronHide is only for ships with mass 30t or higher and military IronHide is only for ships with mass 130t or higher).

21/06/2020 - Version 3.03, updated by Milo; added indication on F5F5 screen showing whether current IronHide armour is civilian or military grade.

21/06/2020 - Version 3.04, updated by Milo; improved handling of invalid ironHide_milFlag missionVariable (not zero or one) from old saved game; modified allowAwardEquipment handler to allow other OXPs to add IronHide to player ships (e.g., Ship Storage Helper).

21/06/2020 - Version 3.05, updated by Milo; re-assess damage-to-armour multiplier each time the ship launches, in case another OXP replaced the player ship, awarded IronHide, or changed the grade of the armour.

21/06/2020 - Version 3.06, updated by Milo; if armour percentage is above zero but EQ_IRONHIDE is missing at startUp or at launch, set percentage to zero (in case another OXP removed IronHide without changing percentage); allow other OXPs to awardEquipment("EQ_IRONHIDE") to NPC ships (e.g., Ship Storage Helper using it as a placeholder for player->npc->player transitions), but IronHide does nothing for NPC ships, so outside of scripted additions, do not allow NPC ships to spawn with IronHide armour, and do not allow awardEquipment("EQ_IRONHIDE_MIL" or "EQ_IRONHIDE_REPAIRS") on NPCs because those are used only as script triggers from the F3 purchase screen.
</pre>

== Download Location ==
This OXP requires at least version 1.82 of Oolite.

Download the latest version in OXZ format [[Media:Oolite.oxp.Thargoid.IronHide.3.06.oxz|here]] (downloaded {{#downloads:Oolite.oxp.Thargoid.IronHide.3.06.oxz}} times).

==Links==
*[[User:Thargoid|Thargoid's OXP page]].

{{equipment-OXP}}

File:Oolite.oxp.Thargoid.IronHide.3.06.oxz

2020-06-22T03:56:09Z

Milo: version 3.06

version 3.06

IronHide OXP

2020-06-22T02:48:49Z

Milo: version 3.05

==Overview==
The Ships Systems Department of the Aquarian Shipbuilding Corporation introduce their latest development - IronHide armour. This is a simple but effective technology which applies a special treatment to the hull of the customer ship which helps to strengthen it against combat and physical damage in collaboration with the ship's shielding.

In practice the armour helps to absorb damage that gets past (or takes down) the shields, although if a truly concentrated attack occurs then localised penetration and energy damage may still occur. This is especially true of missile attacks, which can still cause internal damage and equipment failure due to concussion effects. The current strength of the armour can be viewed on the ship's manifest (F5-F5) screen, and any damage can be repaired at a suitably high-tech station.

The armour itself is available from all good tech 5 locations, for a recommended retail price of just 750 credits. These stations should also be able to quote for repairs to damaged installations. It should also be noted that insurers class armour as a combat consumable, and so its replacement is not included as part of the insurance for equipment such as escape pods and lifeboats.

A special enhanced upgrade for military uses has also been developed, and may be available to customers at tech 10 systems (the upgrade requires an undamaged civilian-grade installation). The upgrade doubles the effectiveness of the regular armour.

==Acknowledgements==
This OXP came about following a discussion over a beer with ClymAngus, and was one of my fastest-written OXPs (sketch-out concept to beta-test was around 7 hours on a boring day at work with nothing to do).

Thanks also to UK_Eliter and Caracal for beta-testing for me, and their feedback and comments.

== Discussion ==
You can find the IronHide discussion thread on the Oolite Bulletin Boards [http://www.aegidian.org/bb/viewtopic.php?t=8311 here].

==Version history==
<pre>
31/07/2010 - Version 1.00, initial release.

01/08/2010 - Version 1.01, changed shield strength from this. to mission variables to maintain across save games.

19/02/2011 - Version 2.00, upgrade for 1.75 trunk - and operating properly now after shields are gone!

19/06/2020 - Version 3.00, updated by Milo; IronHide OXP now requires Oolite 1.79+; armour durability increased but energy restoration is now proportional to damage absorbed (previously the ship's energy was fully restored after every hit, which could conflict with other OXPs' attempts to regulate energy levels); damage below 5 (10 for military grade) will not degrade IronHide armour; further improved compatibility with other OXPs by checking damage type instead of energy level to decide which damage the armour can absorb.

20/06/2020 - Version 3.01, updated by Milo; IronHide OXP now requires Oolite 1.82+; introduced a new script_info property in equipment.plist (ironHide_percentArmourLostPerDamagePointTaken), which functionally replaces the ironHide_strength mission variable (now unused by IronHide, but kept and returned to its pre-3.00 values because CombatMFD uses it for its SEE indicator); eliminated the "damage below X will not degrade armour" threshold (any damage that gets through shields now will consume armour); set damage_probability to zero so IronHide cannot be made "inoperable" (appear broken on the F5 screen) before it is fully consumed; introduced price variance for installation and repairs proportional to ship surface area (cobra3-player is the baseline); added installation_time of 12 hours for both civilian and military grades and a proportional time advance when repairing (repairing X percent is 25% faster than installing X percent, a small incentive to repair before the armour is destroyed; note that if military grade armour is fully consumed, you must first reinstall civilian grade [12 hrs] and then upgrade to military grade [12 hrs], so it saves even more time if you repair military grade before it breaks; also, while not a change from previous versions, military grade armour costs less to repair than it costs to install).

21/06/2020 - Version 3.02, updated by Milo; doubled price variance for larger ships and applied proportional adjustment to repair costs (they were still using the baseline price); improved compatibility with ShipVersion OXP by not offering IronHide for purchase on ships that ShipVersion does not allow to use it (when ShipVersion OXP is detected, civilian IronHide is only for ships with mass 30t or higher and military IronHide is only for ships with mass 130t or higher).

21/06/2020 - Version 3.03, updated by Milo; added indication on F5F5 screen showing whether current IronHide armour is civilian or military grade.

21/06/2020 - Version 3.04, updated by Milo; improved handling of invalid ironHide_milFlag missionVariable (not zero or one) from old saved game; modified allowAwardEquipment handler to allow other OXPs to add IronHide to player ships (e.g., Ship Storage Helper).

21/06/2020 - Version 3.05, updated by Milo; re-assess damage-to-armour multiplier each time the ship launches, in case another OXP replaced the player ship, awarded IronHide, or changed the grade of the armour.
</pre>

== Download Location ==
This OXP requires at least version 1.82 of Oolite.

Download the latest version in OXZ format [[Media:Oolite.oxp.Thargoid.IronHide.3.05.oxz|here]] (downloaded {{#downloads:Oolite.oxp.Thargoid.IronHide.3.05.oxz}} times).

==Links==
*[[User:Thargoid|Thargoid's OXP page]].

{{equipment-OXP}}

File:Oolite.oxp.Thargoid.IronHide.3.05.oxz

2020-06-22T02:48:21Z

Milo: version 3.05

version 3.05

IronHide OXP

2020-06-22T02:06:08Z

Milo: update to version 3.04

==Overview==
The Ships Systems Department of the Aquarian Shipbuilding Corporation introduce their latest development - IronHide armour. This is a simple but effective technology which applies a special treatment to the hull of the customer ship which helps to strengthen it against combat and physical damage in collaboration with the ship's shielding.

In practice the armour helps to absorb damage that gets past (or takes down) the shields, although if a truly concentrated attack occurs then localised penetration and energy damage may still occur. This is especially true of missile attacks, which can still cause internal damage and equipment failure due to concussion effects. The current strength of the armour can be viewed on the ship's manifest (F5-F5) screen, and any damage can be repaired at a suitably high-tech station.

The armour itself is available from all good tech 5 locations, for a recommended retail price of just 750 credits. These stations should also be able to quote for repairs to damaged installations. It should also be noted that insurers class armour as a combat consumable, and so its replacement is not included as part of the insurance for equipment such as escape pods and lifeboats.

A special enhanced upgrade for military uses has also been developed, and may be available to customers at tech 10 systems (the upgrade requires an undamaged civilian-grade installation). The upgrade doubles the effectiveness of the regular armour.

==Acknowledgements==
This OXP came about following a discussion over a beer with ClymAngus, and was one of my fastest-written OXPs (sketch-out concept to beta-test was around 7 hours on a boring day at work with nothing to do).

Thanks also to UK_Eliter and Caracal for beta-testing for me, and their feedback and comments.

== Discussion ==
You can find the IronHide discussion thread on the Oolite Bulletin Boards [http://www.aegidian.org/bb/viewtopic.php?t=8311 here].

==Version history==
<pre>
31/07/2010 - Version 1.00, initial release.

01/08/2010 - Version 1.01, changed shield strength from this. to mission variables to maintain across save games.

19/02/2011 - Version 2.00, upgrade for 1.75 trunk - and operating properly now after shields are gone!

19/06/2020 - Version 3.00, updated by Milo; IronHide OXP now requires Oolite 1.79+; armour durability increased but energy restoration is now proportional to damage absorbed (previously the ship's energy was fully restored after every hit, which could conflict with other OXPs' attempts to regulate energy levels); damage below 5 (10 for military grade) will not degrade IronHide armour; further improved compatibility with other OXPs by checking damage type instead of energy level to decide which damage the armour can absorb.

20/06/2020 - Version 3.01, updated by Milo; IronHide OXP now requires Oolite 1.82+; introduced a new script_info property in equipment.plist (ironHide_percentArmourLostPerDamagePointTaken), which functionally replaces the ironHide_strength mission variable (now unused by IronHide, but kept and returned to its pre-3.00 values because CombatMFD uses it for its SEE indicator); eliminated the "damage below X will not degrade armour" threshold (any damage that gets through shields now will consume armour); set damage_probability to zero so IronHide cannot be made "inoperable" (appear broken on the F5 screen) before it is fully consumed; introduced price variance for installation and repairs proportional to ship surface area (cobra3-player is the baseline); added installation_time of 12 hours for both civilian and military grades and a proportional time advance when repairing (repairing X percent is 25% faster than installing X percent, a small incentive to repair before the armour is destroyed; note that if military grade armour is fully consumed, you must first reinstall civilian grade [12 hrs] and then upgrade to military grade [12 hrs], so it saves even more time if you repair military grade before it breaks; also, while not a change from previous versions, military grade armour costs less to repair than it costs to install).

21/06/2020 - Version 3.02, updated by Milo; doubled price variance for larger ships and applied proportional adjustment to repair costs (they were still using the baseline price); improved compatibility with ShipVersion OXP by not offering IronHide for purchase on ships that ShipVersion does not allow to use it (when ShipVersion OXP is detected, civilian IronHide is only for ships with mass 30t or higher and military IronHide is only for ships with mass 130t or higher).

21/06/2020 - Version 3.03, updated by Milo; added indication on F5F5 screen showing whether current IronHide armour is civilian or military grade.

21/06/2020 - Version 3.04, updated by Milo; improved handling of invalid ironHide_milFlag missionVariable (not zero or one) from old saved game; modified allowAwardEquipment handler to allow other OXPs to add IronHide to player ships (e.g., Ship Storage Helper).
</pre>

== Download Location ==
This OXP requires at least version 1.82 of Oolite.

Download the latest version in OXZ format [[Media:Oolite.oxp.Thargoid.IronHide.3.04.oxz|here]] (downloaded {{#downloads:Oolite.oxp.Thargoid.IronHide.3.04.oxz}} times).

==Links==
*[[User:Thargoid|Thargoid's OXP page]].

{{equipment-OXP}}

File:Oolite.oxp.Thargoid.IronHide.3.04.oxz

2020-06-22T02:05:58Z

Milo: version 3.04

version 3.04

Oolite JavaScript Reference: Mission

2020-06-22T01:28:14Z

Milo: added examples for mission.setInstructions

'''Prototype:''' <code>Object</code> 
'''Subtypes:''' none

The '''mission''' global object is used to run mission screens, and perform other actions related to mission scripting.

== Properties ==

=== <code>displayModel</code> ===
'''displayModel''' : {{oojsclass|Ship}}
If currently running a mission screen with a <code>model</code>, the ship entity used to display the model. This can be animated by setting its position and orientation from a [[Oolite JavaScript Reference: Global#addFrameCallback|frame callback]]. Uses role to identify ship, so be sure to use a unique role if you want a specific ship to be showed.

=== <code>exitScreen</code> ===
{{oolite-prop-added|1.77}}
'''exitScreen''' : [[Oolite JavaScript Reference: Global#guiScreen|guiScreen]] (read/write)

This can be used to set a new exit screen for the current mission screen. Outside of a callback function, the value of this is meaningless, and setting it has no useful effect.

=== <code>markedSystems</code> ===
{{oolite-prop-added|1.77}}
'''markedSystems''' : Array (read-only)

An array of the objects currently being used to mark systems. The objects will have the same properties as those used by <code>markSystem</code> and <code>unmarkSystem</code>.

=== <code>screenID</code> ===
{{oolite-prop-added|1.77}}
'''screenID''' : String (read-only)

If there is currently a mission screen running, and it defined a screenID, then that screenID. Otherwise, this is null.

== Methods ==

=== <code>addMessageText</code> ===
function '''addMessageText'''(message : String)

Appends text to the currently running mission screen. Can also be used to add text to other screens like the system data (F7) screen.

=== <code>addMessageTextKey</code> ===
function '''addMessageTextKey'''(messageKey : String)

Like <code>[[#addMessageText|addMessageText()]]</code>, but looks up the specified <code>messageKey</code> in [[missiontext.plist]].

=== <code>markSystem</code> ===
function '''markSystem'''(systemNumber : Number)

Mark a system on the long range chart. Multiple systems may be marked at once, as in <code>mission.markSystem(4, 54, 222)</code>. In 1.76 and earlier a system cannot be marked twice, so:
mission.markSystem(7);
mission.markSystem(7);
mission.unmarkSystem(7);
will leave the system unmarked.

In 1.77 or later, the parameters may be objects instead of numbers. This allows control over the marker's appearance, and allows multiple markers to be placed on the same system. The object takes the following parameters:
* <code>system</code> : The system ID. This is the only required parameter.
* <code>name</code> : A string identifying the group this marker belongs to (which may be the script's name, or something more specific). If omitted, which is not recommended, this defaults to "__oolite_legacy_destinations" which is also used for marking with numbers and marking carried out by legacy scripts.
* <code>markerColor</code> : A string specifying a colour. e.g. "redColor" or "1.0 0.5 0.0". If omitted, "redColor" will be used.
* <code>markerScale</code> : A number between 0.5 and 2.0 specifying the relative size of the marker. Defaults to 1.0.
* <code>markerShape</code> : A string describing the shape of the marker. Valid values are MARKER_X, MARKER_PLUS, MARKER_SQUARE and MARKER_DIAMOND. If this value is invalid or omitted, MARKER_X will be used.

Multiple markers may be placed on the same system, provided that they have different names. If a marker with the same system and name already exists, it will be replaced.

mission.markSystem({
system: 55,
name: "my_oxp",
markerColor: "cyanColor",
markerScale: 1.5,
markerShape: "MARKER_DIAMOND"
});

'''See also:''' <code>[[#unmarkSystem|unmarkSystem()]]</code>

=== <code>runShipLibrary</code> ===
{{oolite-method-added|1.81}}
function '''runShipLibrary()'''
Display the ship library based on [[shiplibrary.plist]], including processing of condition scripts.

This is mainly useful for scenarios which override the standard scripts.

=== <code>runScreen</code> ===
function '''runScreen(parameters : Object [, callback : Function [, this : Object]])'''
Present a mission screen.

The appearance of the mission screen is defined by the properties of the <code>parameters</code> object. The currently defined properties are:
* <code>title : String</code>
* <code>titleKey : String</code> (Key in [[missiontext.plist]])
* <code>music : String</code> (name of a music file)
* <code>overlay : ''guiTextureSpecifier''</code> (name of an image used as overlay)
* <code>background : ''guiTextureSpecifier''</code> (name of a picture used as background)
* <code>backgroundSpecial: String</code> ({{oolite-prop-added|1.77}}, special background layer)
* <code>model : String</code> (Role of a ship that will be shown as rotating ship)
* <code>modelPersonality : Int</code> ({{oolite-prop-added|1.77}}, the entityPersonality assigned to the <code>model</code>. If unspecified, or in 1.76 or earlier, a random personality is used)
* <code>message : String</code>
* <code>messageKey : String</code> (Key in [[missiontext.plist]])
* <code>spinModel: Boolean</code> (If <code>false</code>, the model is shown from the top with no automatic animation.)
* <code>[[Oolite JavaScript Reference: Mission#Advanced choices ({{oolite-prop-added|1.77}})|choices]]: Object</code> (1.77 or later. Object describing choices)
* <code>choicesKey : String</code> (Key in [[missiontext.plist]])
* <code>initialChoicesKey : String</code> ({{oolite-prop-added|1.77}}, the key from <code>choicesKey</code> which is initially selected)
* <code>allowInterrupt : Boolean</code> ({{oolite-prop-added|1.77}}. If <code>true</code> (default: false), the mission screen can be interrupted with function keys, which does not call the callback function. Mainly intended for interfaces.)
* <code>exitScreen : ''guiScreen''</code> ({{oolite-prop-added|1.77}}, a GUI screen to exit on. If omitted, an invalid value is given, or the player is not docked, this will revert to "GUI_SCREEN_STATUS". Not all GUI screens are selectable for this: only those reachable with function keys F3 to F8)
* <code>screenID : String</code> ({{oolite-prop-added|1.77}}, an optional string which can be read later from <code>[[#screenID|mission.screenID]]</code>)
* <code>textEntry : Boolean</code> ({{oolite-prop-added|1.79}}, if it's true, then you get the text prompt and 'choices' and 'choicesKey' are ignored. Whatever's typed there gets passed as the parameter to the callback function. The [https://github.com/OoliteProject/oolite/blob/master/Resources/Scripts/oolite-registership.js ship registry code] has a simple example.)
* <code>customChartZoom : decimal</code> ({{oolite-prop-added|1.87}}, zoom level of the 'CUSTOM_CHART' backgroundSpecial map)
* <code>customChartCentre: Vector3D</code> ({{oolite-prop-added|1.87}}, centre position of the 'CUSTOM_CHART' backgroundSpecial map, using the internal coordinate system. The z component is always zero. Discouraged in favour of customChartCentreInLY)
* <code>customChartCentreLY: Vector3D</code> ({{oolite-prop-added|1.87}}, centre position of the 'CUSTOM_CHART' backgroundSpecial map, in LY. e.g. for Lave: (8, 34.6, 0). The z component is always zero.)
Some of these are mutually exclusive; for instance, “title” overrides “titleKey”. See [[Oolite JavaScript Reference: Global#setScreenBackground|setScreenBackground()]] for a discussion of ''guiTextureSpecifier''.

There are 21 lines available for display of the message and choices combined. (In 1.77, this is extended to 27 lines if the player's HUD is hidden)

==== runScreen callbacks ====
The callback function is a function that is called when the player makes a choice. Every runScreen can have its own specific callback function, or you can design a single function to handle multiple mission screens instead. The optional <code>this</code> parameter will be used as the <code>this</code> property of the mission screen callback. It is usually unnecessary to specify this, but if you intend the function which calls runScreen to be called from a different script, and the callback references <code>this</code>, you will need to use it.

'''Example:''' 
A simple mission screen:
mission.runScreen({
title: "My first mission screen",
message: "This am a mission screen wot is good",
choicesKey: "me_firstmission_choices"
},
function (choice)
{
if (choice === "1_YES") player.commsMessage("Yay!");
else if (choice === "2_NO") player.commsMessage("Boo.");
else player.commsMessage("Whut?");
});
In [[missiontext.plist]], you’ll need the following. The numbers are used because choices are sorted by key.
{
"me_firstmission_choices" =
{
"1_YES" = "Yes.";
"2_NO" = "No.";
"3_MAYBE" = "Maybe.";
};
}

The call does not have to be laid out as above. The parameters object can be manipulated in any way you want beforehand, and the callback function can be written out of line. For example, the following is equivalent:
var parameters = new Object();
parameters.title = "My first mission screen";
parameters.message = "This am";
parameters.choicesKey = "me_firstmission_choices";
parameters.message += " a mission screen wot is good";

function callback(choice)
{
if (choice === "1_YES") player.commsMessage("Yay!");
else if (choice === "2_NO") player.commsMessage("Boo.");
else player.commsMessage("Whut?");
}

mission.runScreen(parameters, callback);

This form is more complicated, and the ordering is less intuitive. However, it does allow you to make complex decisions about the parameters in code, and writing the callback out of line can be preferable if it’s long. It is recommended that you start out with the first approach, but keep in mind that there are other options if it becomes too limiting.

In 1.77, if <code>allowInterrupt</code> is set to true, it is possible that the callback function will not be called. It should therefore only be set for mission screens which can safely be interrupted without the callback. Regardless of this setting, all mission screens may be interrupted by the player launching from the station, and this possibility should be considered (in such case callback function will be called with <code>null</code> argument).

==== runScreen special backgrounds (1.77 or later only) ====

In 1.77 or later, 'backgroundSpecial' may be given the following special string values:
* <code>SHORT_RANGE_CHART</code>: Uses the short range chart (as if the player had pressed F6). The first 18 lines of the mission text will overlap the chart if used.
* <code>LONG_RANGE_CHART</code>: Uses the current long range chart (as if the player had pressed F6 twice). The first 16 lines of the mission text will overlap the chart if used.
* <code>LONG_RANGE_CHART_SHORTEST</code>: As LONG_RANGE_CHART, but if the player has a working [[Advanced Navigational Array]] then the shortest (fewest jumps, not necessarily shortest distance) route to their current destination system will be displayed.
* <code>LONG_RANGE_CHART_QUICKEST</code>: As LONG_RANGE_CHART, but if the player has a working [[Advanced Navigational Array]] then the quickest route to their current destination system will be displayed.

In 1.87 or later, 'backgroundSpecial' has these additional special string values:
* <code>SHORT_RANGE_CHART_SHORTEST</code>: As SHORT_RANGE_CHART, but if the player has a working [[Advanced Navigational Array]] then the shortest (fewest jumps, not necessarily shortest distance) route to their current destination system will be displayed.
* <code>SHORT_RANGE_CHART_QUICKEST</code>: As SHORT_RANGE_CHART, but if the player has a working [[Advanced Navigational Array]] then the quickest route to their current destination system will be displayed.
* <code>CUSTOM_CHART</code>: Displays a chart where zoom and centre position can be customised using the 'customChartZoom' and 'customChartCentreInLY' properties. The first 18 lines of the mission text will overlap the chart if used.
* <code>CUSTOM_CHART_SHORTEST</code>: As CUSTOM_CHART, but if the player has a working [[Advanced Navigational Array]] then the shortest (fewest jumps, not necessarily shortest distance) route to their current destination system will be displayed.
* <code>CUSTOM_CHART_QUICKEST</code>: As CUSTOM_CHART, but if the player has a working [[Advanced Navigational Array]] then the quickest route to their current destination system will be displayed.

With all special chart backgrounds, changes made to destination system, or to markers, will be updated immediately. 
These backgrounds will be displayed above the '<code>background</code>' (if any) but below everything else.

==== Advanced choices (1.77 or later only) ====

In 1.77 or later, choices may be set either with the 'choicesKey' parameter from missiontext.plist as before, or with the 'choices' parameter. (If both are set, 'choicesKey' will be ignored)
'''Example''' 
var options = {
"01_AGREE" : "Take the job",
"02_DECLINE" : "Politely decline"
};
if (player.bounty == 0) // only clean players have this option
{
options["03_REPORT"] = "Call the police";
}

mission.runScreen({
// title, message, etc.
choices: options
},function(choice) {
// choice handling
});

This is useful where the options available (perhaps depending on the player's ship or equipment, or on previous events in the mission) may vary in a complex fashion, to avoid the need to have a separate missiontext.plist entry for every possibility.

The value (either in <code>choicesKey</code>'s missiontext entry or <code>choices</code>) may either be a text string as in previous versions, or an object itself. If it is an object, it can take three parameters:
* 'text' is the displayed text for this key.
* 'alignment' can be 'LEFT', 'RIGHT' or 'CENTER' (the default).
* 'unselectable' can be <code>true</code> or <code>false</code> (the default for non-blank text). Unselectable rows are printed, but are skipped when moving through the options. This can be useful for keeping a consistent interface.
* 'color' can be any color specification (e.g. "orangeColor"). The default is "yellowColor", or "darkGrayColor" for unselectable rows.
For example (missiontext.plist):
"my_choice_1" = {
"01_AGREE" = {
text = "Take the job";
alignment = "LEFT";
color = "greenColor";
};
// more options
};

In 1.77, the behaviour for choices which have no text is slightly changed. These will now leave a blank and unselectable line in the option list.

==== Safe usage of runScreen ====

One warning: <code>runScreen()</code> will overwrite any existing missionscreen or GUI screen. The only safe place is using it inside a <code>missionScreenOpportunity</code> handler or the callback function from a previous mission screen (or in 1.77 onwards, inside an interface callback function), because that handler only fires when it is allowed to show such a screen. When using the command at other places, first make sure with <code>guiScreen != "GUI_SCREEN_MISSION"</code> that there is currently no missionscreen on display by another oxp.

==== Known issues ====

From Oolite 1.79, only the A-Z, a-z, 0-9 and (space) characters may be reliably entered in the 'textEntry' field. A wider selection, for boring internal reasons, is available on the Mac, and is hoped to also be available on other platforms in later releases.

=== <code>setInstructions</code> ===
function '''setInstructions(instructions : String, [worldScriptName : String])'''

Specify a message to put on the Manifest screen (usually short instructions for current mission), under the title “Missions”.

When not called from within a world script, the name of a world script must be specified so that Oolite knows which script the message belongs to. Clear the message by calling <code>setInstructions(null)</code>.

It is recommended that <code>setInstructions()</code> is used only when you need to customise the text for a specific scenario. For static text, use <code>[[#setInstructionsKey|setInstructionsKey()]]</code> instead.

In Oolite 1.81 onwards, the following variant is available

{{oolite-method-added|1.81}}
function '''setInstructions(instructions : Array, [worldScriptName : String])'''

If this version is used, the first array element will be a heading on the Manifest screen, and the remaining elements will be entered underneath it, rather than being entered under the "Missions" heading.

'''Example''': <code>mission.setInstructions(["Ship Companion:",expandMissionText("myoxp_currentpet"),...]);</code> will display Ship Companion: in yellow text on the F5F5 screen, and beneath it will show the [[String expansion|expanded]] value of the key "myoxp_currentpet" from the [[missiontext.plist]] associated with the calling world script. If not called from a world script, the worldScriptName (this.name from the script) must be provided also: <code>mission.setInstructions(["Ship Companion:",expandMissionText("myoxp_currentpet"),...], "myoxp's script name");</code>

Note that the line or lines to be added must be enclosed in square brackets, comma separated. Also note the optional use of expandMissionText to retrieve text from [[missiontext.plist]]. It is also possible to construct the array before calling setInstructions, for example:<pre>
if(myoxp_petslist.length == 0) {
mission.setInstructions(null); // clear any text previously displayed by this world script on the F5F5 screen
} else {
var textArray = [];
textArray.push("Ship Companion" + (myoxp_petslist.length > 1 ? "s:" : ":")); // "Ship Companion:" or "Ship Companions:" if more than one
var i = myoxp_petslist.length - 1; // pointer to last entry in myoxp_petslist
while(i--) { // for each pet in the list, starting from the bottom (probably newest to oldest)
textArray.push(myoxp_petslist[i].name); // add the name of the pet to the text we will show on the F5F5 screen
}
mission.setInstructions(textArray); // our pets list will now be visible on the F5F5 screen until further notice (the next time we call setInstructions or one of its variants, it will replace this)
}
</pre>

'''See also:''' <code>[[#setInstructionsKey|setInstructionsKey()]]</code>

=== <code>setInstructionsKey</code> ===
function '''setInstructionsKey(messageKey : String, [worldScript : String])'''

Like <code>[[#setInstructions|setInstructions()]]</code>, but looks up the specified <code>messageKey</code> in [[missiontext.plist]].

'''See also:''' <code>[[#setInstructions|setInstructions()]]</code>

=== <code>unmarkSystem</code> ===
function '''unmarkSystem'''(systemNumbers : Number)

Remove a mark set with <code>[[#markSystem|markSystem()]]</code>. Multiple systems may be unmarked at once, as in <code>mission.unmarkSystem(4, 54, 222)</code>.

In 1.76 and earlier versions, any script can unmark a system, regardless of which script marked it or how many times it was previously marked.

In 1.77, each marker has a name, and if a system has multiple markers each marker must be removed separately. Parameters in 1.77 may be numbers or objects. Numbers remove the "__oolite_legacy_destinations" markers. Objects are the same format as in <code>markSystem</code> and remove the marker of the corresponding name (the marker style options are ignored when unmarking). In 1.77, this function will return true if all requested markers existed and were removed, or false if any of the requested markers did not exist.

'''See also:''' <code>[[#markSystem|markSystem()]]</code>

[[Category:Oolite JavaScript Reference]]

File:Oolite.oxp.Thargoid.IronHide.3.03.oxz

2020-06-22T01:00:31Z

Milo: Milo uploaded a new version of File:Oolite.oxp.Thargoid.IronHide.3.03.oxz

version 3.03

IronHide OXP

2020-06-22T00:59:53Z

Milo: version 3.03

==Overview==
The Ships Systems Department of the Aquarian Shipbuilding Corporation introduce their latest development - IronHide armour. This is a simple but effective technology which applies a special treatment to the hull of the customer ship which helps to strengthen it against combat and physical damage in collaboration with the ship's shielding.

In practice the armour helps to absorb damage that gets past (or takes down) the shields, although if a truly concentrated attack occurs then localised penetration and energy damage may still occur. This is especially true of missile attacks, which can still cause internal damage and equipment failure due to concussion effects. The current strength of the armour can be viewed on the ship's manifest (F5-F5) screen, and any damage can be repaired at a suitably high-tech station.

The armour itself is available from all good tech 5 locations, for a recommended retail price of just 750 credits. These stations should also be able to quote for repairs to damaged installations. It should also be noted that insurers class armour as a combat consumable, and so its replacement is not included as part of the insurance for equipment such as escape pods and lifeboats.

A special enhanced upgrade for military uses has also been developed, and may be available to customers at tech 10 systems (the upgrade requires an undamaged civilian-grade installation). The upgrade doubles the effectiveness of the regular armour.

==Acknowledgements==
This OXP came about following a discussion over a beer with ClymAngus, and was one of my fastest-written OXPs (sketch-out concept to beta-test was around 7 hours on a boring day at work with nothing to do).

Thanks also to UK_Eliter and Caracal for beta-testing for me, and their feedback and comments.

== Discussion ==
You can find the IronHide discussion thread on the Oolite Bulletin Boards [http://www.aegidian.org/bb/viewtopic.php?t=8311 here].

==Version history==
<pre>
31/07/2010 - Version 1.00, initial release.

01/08/2010 - Version 1.01, changed shield strength from this. to mission variables to maintain across save games.

19/02/2011 - Version 2.00, upgrade for 1.75 trunk - and operating properly now after shields are gone!

19/06/2020 - Version 3.00, updated by Milo; IronHide OXP now requires Oolite 1.79+; armour durability increased but energy restoration is now proportional to damage absorbed (previously the ship's energy was fully restored after every hit, which could conflict with other OXPs' attempts to regulate energy levels); damage below 5 (10 for military grade) will not degrade IronHide armour; further improved compatibility with other OXPs by checking damage type instead of energy level to decide which damage the armour can absorb.

20/06/2020 - Version 3.01, updated by Milo; IronHide OXP now requires Oolite 1.82+; introduced a new script_info property in equipment.plist (ironHide_percentArmourLostPerDamagePointTaken), which functionally replaces the ironHide_strength mission variable (now unused by IronHide, but kept and returned to its pre-3.00 values because CombatMFD uses it for its SEE indicator); eliminated the "damage below X will not degrade armour" threshold (any damage that gets through shields now will consume armour); set damage_probability to zero so IronHide cannot be made "inoperable" (appear broken on the F5 screen) before it is fully consumed; introduced price variance for installation and repairs proportional to ship surface area (cobra3-player is the baseline); added installation_time of 12 hours for both civilian and military grades and a proportional time advance when repairing (repairing X percent is 25% faster than installing X percent, a small incentive to repair before the armour is destroyed; note that if military grade armour is fully consumed, you must first reinstall civilian grade [12 hrs] and then upgrade to military grade [12 hrs], so it saves even more time if you repair military grade before it breaks; also, while not a change from previous versions, military grade armour costs less to repair than it costs to install).

21/06/2020 - Version 3.02, updated by Milo; doubled price variance for larger ships and applied proportional adjustment to repair costs (they were still using the baseline price); improved compatibility with ShipVersion OXP by not offering IronHide for purchase on ships that ShipVersion does not allow to use it (when ShipVersion OXP is detected, civilian IronHide is only for ships with mass 30t or higher and military IronHide is only for ships with mass 130t or higher).

21/06/2020 - Version 3.03, updated by Milo; added indication on F5F5 screen showing whether current IronHide armour is civilian or military grade.
</pre>

== Download Location ==
This OXP requires at least version 1.82 of Oolite.

Download the latest version in OXZ format [[Media:Oolite.oxp.Thargoid.IronHide.3.03.oxz|here]] (downloaded {{#downloads:Oolite.oxp.Thargoid.IronHide.3.03.oxz}} times).

==Links==
*[[User:Thargoid|Thargoid's OXP page]].

{{equipment-OXP}}

File:Oolite.oxp.Thargoid.IronHide.3.03.oxz

2020-06-22T00:58:30Z

Milo: version 3.03

version 3.03

IronHide OXP

2020-06-21T20:30:03Z

Milo: add version number to filename

==Overview==
The Ships Systems Department of the Aquarian Shipbuilding Corporation introduce their latest development - IronHide armour. This is a simple but effective technology which applies a special treatment to the hull of the customer ship which helps to strengthen it against combat and physical damage in collaboration with the ship's shielding.

In practice the armour helps to absorb damage that gets past (or takes down) the shields, although if a truly concentrated attack occurs then localised penetration and energy damage may still occur. This is especially true of missile attacks, which can still cause internal damage and equipment failure due to concussion effects. The current strength of the armour can be viewed on the ship's manifest (F5-F5) screen, and any damage can be repaired at a suitably high-tech station.

The armour itself is available from all good tech 5 locations, for a recommended retail price of just 750 credits. These stations should also be able to quote for repairs to damaged installations. It should also be noted that insurers class armour as a combat consumable, and so its replacement is not included as part of the insurance for equipment such as escape pods and lifeboats.

A special enhanced upgrade for military uses has also been developed, and may be available to customers at tech 10 systems (the upgrade requires an undamaged civilian-grade installation). The upgrade doubles the effectiveness of the regular armour.

==Acknowledgements==
This OXP came about following a discussion over a beer with ClymAngus, and was one of my fastest-written OXPs (sketch-out concept to beta-test was around 7 hours on a boring day at work with nothing to do).

Thanks also to UK_Eliter and Caracal for beta-testing for me, and their feedback and comments.

== Discussion ==
You can find the IronHide discussion thread on the Oolite Bulletin Boards [http://www.aegidian.org/bb/viewtopic.php?t=8311 here].

==Version history==
<pre>
31/07/2010 - Version 1.00, initial release.

01/08/2010 - Version 1.01, changed shield strength from this. to mission variables to maintain across save games.

19/02/2011 - Version 2.00, upgrade for 1.75 trunk - and operating properly now after shields are gone!

19/06/2020 - Version 3.00, updated by Milo; IronHide OXP now requires Oolite 1.79+; armour durability increased but energy restoration is now proportional to damage absorbed (previously the ship's energy was fully restored after every hit, which could conflict with other OXPs' attempts to regulate energy levels); damage below 5 (10 for military grade) will not degrade IronHide armour; further improved compatibility with other OXPs by checking damage type instead of energy level to decide which damage the armour can absorb.

20/06/2020 - Version 3.01, updated by Milo; IronHide OXP now requires Oolite 1.82+; introduced a new script_info property in equipment.plist (ironHide_percentArmourLostPerDamagePointTaken), which functionally replaces the ironHide_strength mission variable (now unused by IronHide, but kept and returned to its pre-3.00 values because CombatMFD uses it for its SEE indicator); eliminated the "damage below X will not degrade armour" threshold (any damage that gets through shields now will consume armour); set damage_probability to zero so IronHide cannot be made "inoperable" (appear broken on the F5 screen) before it is fully consumed; introduced price variance for installation and repairs proportional to ship surface area (cobra3-player is the baseline); added installation_time of 12 hours for both civilian and military grades and a proportional time advance when repairing (repairing X percent is 25% faster than installing X percent, a small incentive to repair before the armour is destroyed; note that if military grade armour is fully consumed, you must first reinstall civilian grade [12 hrs] and then upgrade to military grade [12 hrs], so it saves even more time if you repair military grade before it breaks; also, while not a change from previous versions, military grade armour costs less to repair than it costs to install).

21/06/2020 - Version 3.02, updated by Milo; doubled price variance for larger ships and applied proportional adjustment to repair costs (they were still using the baseline price); improved compatibility with ShipVersion OXP by not offering IronHide for purchase on ships that ShipVersion does not allow to use it (when ShipVersion OXP is detected, civilian IronHide is only for ships with mass 30t or higher and military IronHide is only for ships with mass 130t or higher).
</pre>

== Download Location ==
This OXP requires at least version 1.82 of Oolite.

Download the latest version in OXZ format [[Media:Oolite.oxp.Thargoid.IronHide.3.02.oxz|here]] (downloaded {{#downloads:Oolite.oxp.Thargoid.IronHide.3.02.oxz}} times).

==Links==
*[[User:Thargoid|Thargoid's OXP page]].

{{equipment-OXP}}

File:Oolite.oxp.Thargoid.IronHide.3.02.oxz

2020-06-21T20:28:08Z

Milo: Milo moved page File:Oolite.oxp.Thargoid.IronHide.oxz to File:Oolite.oxp.Thargoid.IronHide.3.02.oxz: add version number

version 3.00

File:Oolite.oxp.Thargoid.IronHide.oxz

2020-06-21T20:28:08Z

Milo: Milo moved page File:Oolite.oxp.Thargoid.IronHide.oxz to File:Oolite.oxp.Thargoid.IronHide.3.02.oxz: add version number

#REDIRECT [[File:Oolite.oxp.Thargoid.IronHide.3.02.oxz]]

IronHide OXP

2020-06-21T20:14:51Z

Milo: update IronHide to 3.02

==Overview==
The Ships Systems Department of the Aquarian Shipbuilding Corporation introduce their latest development - IronHide armour. This is a simple but effective technology which applies a special treatment to the hull of the customer ship which helps to strengthen it against combat and physical damage in collaboration with the ship's shielding.

In practice the armour helps to absorb damage that gets past (or takes down) the shields, although if a truly concentrated attack occurs then localised penetration and energy damage may still occur. This is especially true of missile attacks, which can still cause internal damage and equipment failure due to concussion effects. The current strength of the armour can be viewed on the ship's manifest (F5-F5) screen, and any damage can be repaired at a suitably high-tech station.

The armour itself is available from all good tech 5 locations, for a recommended retail price of just 750 credits. These stations should also be able to quote for repairs to damaged installations. It should also be noted that insurers class armour as a combat consumable, and so its replacement is not included as part of the insurance for equipment such as escape pods and lifeboats.

A special enhanced upgrade for military uses has also been developed, and may be available to customers at tech 10 systems (the upgrade requires an undamaged civilian-grade installation). The upgrade doubles the effectiveness of the regular armour.

==Acknowledgements==
This OXP came about following a discussion over a beer with ClymAngus, and was one of my fastest-written OXPs (sketch-out concept to beta-test was around 7 hours on a boring day at work with nothing to do).

Thanks also to UK_Eliter and Caracal for beta-testing for me, and their feedback and comments.

== Discussion ==
You can find the IronHide discussion thread on the Oolite Bulletin Boards [http://www.aegidian.org/bb/viewtopic.php?t=8311 here].

==Version history==
<pre>
31/07/2010 - Version 1.00, initial release.

01/08/2010 - Version 1.01, changed shield strength from this. to mission variables to maintain across save games.

19/02/2011 - Version 2.00, upgrade for 1.75 trunk - and operating properly now after shields are gone!

19/06/2020 - Version 3.00, updated by Milo; IronHide OXP now requires Oolite 1.79+; armour durability increased but energy restoration is now proportional to damage absorbed (previously the ship's energy was fully restored after every hit, which could conflict with other OXPs' attempts to regulate energy levels); damage below 5 (10 for military grade) will not degrade IronHide armour; further improved compatibility with other OXPs by checking damage type instead of energy level to decide which damage the armour can absorb.

20/06/2020 - Version 3.01, updated by Milo; IronHide OXP now requires Oolite 1.82+; introduced a new script_info property in equipment.plist (ironHide_percentArmourLostPerDamagePointTaken), which functionally replaces the ironHide_strength mission variable (now unused by IronHide, but kept and returned to its pre-3.00 values because CombatMFD uses it for its SEE indicator); eliminated the "damage below X will not degrade armour" threshold (any damage that gets through shields now will consume armour); set damage_probability to zero so IronHide cannot be made "inoperable" (appear broken on the F5 screen) before it is fully consumed; introduced price variance for installation and repairs proportional to ship surface area (cobra3-player is the baseline); added installation_time of 12 hours for both civilian and military grades and a proportional time advance when repairing (repairing X percent is 25% faster than installing X percent, a small incentive to repair before the armour is destroyed; note that if military grade armour is fully consumed, you must first reinstall civilian grade [12 hrs] and then upgrade to military grade [12 hrs], so it saves even more time if you repair military grade before it breaks; also, while not a change from previous versions, military grade armour costs less to repair than it costs to install).

21/06/2020 - Version 3.02, updated by Milo; doubled price variance for larger ships and applied proportional adjustment to repair costs (they were still using the baseline price); improved compatibility with ShipVersion OXP by not offering IronHide for purchase on ships that ShipVersion does not allow to use it (when ShipVersion OXP is detected, civilian IronHide is only for ships with mass 30t or higher and military IronHide is only for ships with mass 130t or higher).
</pre>

== Download Location ==
This OXP requires at least version 1.82 of Oolite.

Download the latest version in OXZ format [[Media:Oolite.oxp.Thargoid.IronHide.oxz|here]] (downloaded {{#downloads:Oolite.oxp.Thargoid.IronHide.oxz}} times).

==Links==
*[[User:Thargoid|Thargoid's OXP page]].

{{equipment-OXP}}

File:Oolite.oxp.Thargoid.IronHide.3.02.oxz

2020-06-21T20:13:57Z

Milo: Milo uploaded a new version of File:Oolite.oxp.Thargoid.IronHide.oxz

version 3.00

File:Oolite.oxp.Thargoid.IronHide.3.02.oxz

2020-06-21T05:17:07Z

Milo: Milo uploaded a new version of File:Oolite.oxp.Thargoid.IronHide.oxz

version 3.00

IronHide OXP

2020-06-21T03:56:36Z

Milo: IronHide OXP 3.01 update

==Overview==
The Ships Systems Department of the Aquarian Shipbuilding Corporation introduce their latest development - IronHide armour. This is a simple but effective technology which applies a special treatment to the hull of the customer ship which helps to strengthen it against combat and physical damage in collaboration with the ship's shielding.

In practice the armour helps to absorb damage that gets past (or takes down) the shields, although if a truly concentrated attack occurs then localised penetration and energy damage may still occur. This is especially true of missile attacks, which can still cause internal damage and equipment failure due to concussion effects. The current strength of the armour can be viewed on the ship's manifest (F5-F5) screen, and any damage can be repaired at a suitably high-tech station.

The armour itself is available from all good tech 5 locations, for a recommended retail price of just 750 credits. These stations should also be able to quote for repairs to damaged installations. It should also be noted that insurers class armour as a combat consumable, and so its replacement is not included as part of the insurance for equipment such as escape pods and lifeboats.

A special enhanced upgrade for military uses has also been developed, and may be available to customers at tech 10 systems (the upgrade requires an undamaged civilian-grade installation). The upgrade doubles the effectiveness of the regular armour.

==Acknowledgements==
This OXP came about following a discussion over a beer with ClymAngus, and was one of my fastest-written OXPs (sketch-out concept to beta-test was around 7 hours on a boring day at work with nothing to do).

Thanks also to UK_Eliter and Caracal for beta-testing for me, and their feedback and comments.

== Discussion ==
You can find the IronHide discussion thread on the Oolite Bulletin Boards [http://www.aegidian.org/bb/viewtopic.php?t=8311 here].

==Version history==
<pre>
31/07/2010 - Version 1.00, initial release.
01/08/2010 - Version 1.01, changed shield strength from this. to mission variables to maintain across save games.
19/02/2011 - Version 2.00, upgrade for 1.75 trunk - and operating properly now after shields are gone!
19/06/2020 - Version 3.00, updated by Milo; IronHide OXP now requires Oolite 1.79+; armour durability increased but energy restoration is now proportional to damage absorbed (previously the ship's energy was fully restored after every hit, which could conflict with other OXPs' attempts to regulate energy levels); damage below 5 (10 for military grade) will not degrade IronHide armour; further improved compatibility with other OXPs by checking damage type instead of energy level to decide which damage the armour can absorb.
20/06/2020 - Version 3.01, updated by Milo; IronHide OXP now requires Oolite 1.82+; introduced a new script_info property in equipment.plist (ironHide_percentArmourLostPerDamagePointTaken), which functionally replaces the ironHide_strength mission variable (now unused by IronHide, but kept and returned to its pre-3.00 values because CombatMFD uses it for its SEE indicator); eliminated the "damage below X will not degrade armour" threshold (any damage that gets through shields now will consume armour); set damage_probability to zero so IronHide cannot be made "inoperable" (appear broken on the F5 screen) before it is fully consumed; introduced price variance for installation and repairs proportional to ship surface area (cobra3-player is the baseline); added installation_time of 12 hours for both civilian and military grades and a proportional time advance when repairing (repairing X percent is 25% faster than installing X percent, a small incentive to repair before the armour is destroyed; note that if military grade armour is fully consumed, you must first reinstall civilian grade [12 hrs] and then upgrade to military grade [12 hrs], so it saves even more time if you repair military grade before it breaks; also, while not a change from previous versions, military grade armour costs less to repair than it costs to install)
</pre>

== Download Location ==
This OXP requires at least version 1.82 of Oolite.

Download the latest version in OXZ format [[Media:Oolite.oxp.Thargoid.IronHide.oxz|here]] (downloaded {{#downloads:Oolite.oxp.Thargoid.IronHide.oxz}} times).

==Links==
*[[User:Thargoid|Thargoid's OXP page]].

{{equipment-OXP}}

File:Oolite.oxp.Thargoid.IronHide.3.02.oxz

2020-06-21T03:54:56Z

Milo: Milo uploaded a new version of File:Oolite.oxp.Thargoid.IronHide.oxz

version 3.00

Missiontext.plist

2020-06-20T21:09:26Z

Milo: linked to string expansion page, added note about not using oolite_key_

This is the filename of the file that contains all the text relevant to scripted missions. It should be placed inside the /Config - folder (see [[OXP_howto#Structure|OXP HowTo]]). See the [[Property_list|Property List]] page for more detail on plists.

== Structure ==
The file is organised as a dictionary { }.
Every entry consists of the key name, followed by a '=' and then the text in quotes.

Example:
conhunt_short_desc1 = "Hunt for the constrictor stolen from Xeer.";

==Special Expansions==

These can be included in your text, inside the quotation marks in openStep, to automatically insert the following details:

[commander_name] - Displays the name of the saved game file.

[commander_shipname] - Displays the name of the player's ship, as specified by [[shipdata.plist]].

[commander_shipdisplayname] - Could be different from commander_shipname.

[commander_rank] - Displays the player's Elite rating.

[commander_legal_status] - Displays the player's current legal status.

[commander_bounty] - Displays the current bounty on the player. ''(Oolite v1.74 & up)''

[mission_xxxx] - displays the missionVariables.xxxxx.

[nom] - Generate a random surname.

[thanks-for-assist] - Err, thanks the player for their assistance.

[police-thanks-for-assist] - the police thanks the player personally.

[describe-pirate] - Random description for an outlaw.

[describe-Pirate] - Capitalized random description for an outlaw.

[thargoid_curses] - Random Thargoid curses.

[police_warning] - Random impending fines notifications.

[police_attack_warning] - Random warning of immediate(?) attack.

%H - Will display the current system name i.e. Isinor.

%I - Displays the current system name with "ian" attached i.e. Isinorian.

%R - Random word. (Use %N for a better result)

%N - Random name. More variation than with %R. Multiple repetitions of %N in the same string generate the same expansion. (Feature added with Oolite 1.73)

%Jxxx - Will display the system name of system with ID number "xxx". xxx must be a 3 digit number or no replacement takes place. e.g. %J007 is Lave. This replacement follows any system renaming by other OXPs. (Feature added with Oolite 1.73)

%Gxxxyyy - Will display the system name of system with ID number "xxx" in galaxy with ID "yyy". xxx and yyy must be 3 digit numbers or no replacement takes place. e.g. %G007000 is Lave. This replacement follows any system renaming by other OXPs. (Feature added with Oolite 1.87)

[oolite_key_FOO] - A human-readable description of the [[Oolite_Keyboard_Controls|keyconfig.plist]] entry <code>key_FOO</code>, if one exists. (Feature added with Oolite 1.79) It is '''discouraged''' for OXPs to use these, instead it is '''recommended''' to use <code>oolite-keycode-</code> prefixed entries found in [[descriptions.plist]].

If the message contains elements enclosed in square brackets [like_this] that correspond to mission_variable names or keys in [[descriptions.plist]], or several [[String expansion|other variations]], then these also will be expanded and substituted into the original message.

== Layout ==
Several spacial characters are used in determining the layout of the text, just as in Wiki.

*'''\"''' Enables the use of colons.
*'''\\n''' Insers a hard Enter.

In XML:
*'''\n''' Inserts a hard Enter.

Example:
trumble_offer = "Commander,\\n\\nYou look like someone who could use a Trumble!...";

== Choices ==
Most missions offer a choice, that is the spirit of elite.

Example:
nova_yesno = {
YES = "Okay, I'll help";
NO = "No, sorry.";
}
On the missionscreen the choices are sorted by key.

[[Category:Oolite]]
[[Category:Oolite scripting]]

String expansion

2020-06-20T21:00:42Z

Milo: more detailed explanation of string expansion

== Format ==
Oolite has a mechanism to replace text in strings with other text. At certain times before displaying text (details below), Oolite searches for % symbols and square brackets [ ]. If it finds them, it checks if what immediately follows the % symbols, or what is between the square brackets, has a recognized special meaning, and if so, substitutes replacement text. Oolite also recognizes vertical bars ('|') and colons (':') inside square brackets as special characters. When you do not want Oolite to replace text, use a double % ('%%') to display a single %, and put a backslash ('\') before each square bracket to display the brackets and text inside them without substitution ('\[example\]' will be displayed as '[example]'). Additionally, the special value '\n' will be replaced by a new line, which can be prevented by preceding it with an extra slash ('\\n' will display '\n').

== What is switched ==
'''Recognized % codes:'''

* %H - Current System name, e.g., Lave
* %I - Current System name with "ian" appended, e.g., Laveian
* %Jxxx - Name of System corresponding with ID number xxx in the current galaxy (must be a 3-digit number), e.g., %J007 is Lave while in Galaxy 1 (feature added in Oolite 1.73)
* %Gxxxyyy - Name of System corresponding with ID number xxx in galaxy number yyy (both must be 3-digit numbers), e.g. %G007000 is Lave (feature added in Oolite 1.87)
* %N - Random name (repetitions of %N in the same string generate the same result)
* %R - Random word (repetitions of %R in the same string generate unique results)

'''Text in brackets:'''

* If there are only numbers between the brackets (e.g., [0] or [35]), the corresponding Nth sub-array (counting from zero) is retrieved from the <code>system_description</code> array in [[descriptions.plist]], which is expected to contain only sub-arrays of strings. When a sub-array is retrieved, one string is selected from it at random and the result is expanded recursively (if it contains %-codes or bracket expressions, those will be replaced too). As of Oolite 1.87, there are 36 entries in the system_description array (the last is [35]). This is used to generate planet descriptions but may be used in OXPs if the strings are suitable. For example, [10] is replaced with a random beverage.
* Otherwise, the text between the brackets (hereafter called the "key") is evaluated recursively in the following priority order to find a replacement:
*# Overrides (context-specific expansions, special keys that are only recognized in certain situations, and can also be used from JavaScript)
*#* In comms messages, [self:name] and [target:name] will be replaced respectively with the sender's displayName and the target's displayName (or the "unknown-target" description from [[descriptions.plist]], if the scanner is jammed).
*#* In [[Oolite_JavaScript_Reference:_Global#expandDescription|expandDescription]] and [[Oolite_JavaScript_Reference:_Global#expandMissionText|expandMissionText]] you can provide a dictionary of keys and replacement values (which can be JavaScript expressions calculated at run-time).
*# Special keys (these are hard-coded)
*#* [commander_name]
*#* [commander_shipname]
*#* [commander_shipdisplayname]
*#* [commander_rank]
*#* [commander_kills]
*#* [commander_legal_status]
*#* [commander_bounty]
*#* [credits_number]
*# [[Descriptions.plist]] (if there is a matching key, substitutes the associated value, which may be a single string or an array of string; if it is an array of strings, then one is selected at random.) Because [[descriptions.plist]] entries from all OXPs are merged at run-time with the ones in the game's Resources folder, it is '''recommended''' that OXP-specific entries in [[descriptions.plist]] have an OXP or creator-specific prefix to ensure uniqueness.
*#* For example, [nom] will match the "nom" key in [[descriptions.plist]], the value of which is an array of two strings ("%R", "[nom1]"), one of which will be randomly selected, and then evaluated again.
*# Keyboard bindings (will be replaced with corresponding key name; however, [[descriptions.plist]] overrides keybindings and is evaluated first, so using these keys in OXPs is '''discouraged'''; instead, look for the comment "translations of special keys" in [[descriptions.plist]] and use the keys there)
*#* [oolite_key_tab], [oolite_key_esc], [oolite_key_space], [oolite_key_f1], [oolite_key_f2], [oolite_key_f3], [oolite_key_f4], [oolite_key_f5], [oolite_key_f6], [oolite_key_f7], [oolite_key_f8], [oolite_key_f9], [oolite_key_f10, [oolite_key_f11]
*#* [oolite_key_right], [oolite_key_left], [oolite_key_down], [oolite_key_up], [oolite_key_home], [oolite_key_end], [oolite_key_insert], [oolite_key_delete], [oolite_key_pageup], [oolite_key_pagedown]
*#* [oolite_key_numpad0], [oolite_key_numpad1], [oolite_key_numpad2], [oolite_key_numpad3], [oolite_key_numpad4], [oolite_key_numpad5], [oolite_key_numpad6], [oolite_key_numpad7], [oolite_key_numpad8], [oolite_key_numpad9]
*# Mission variables (<code>[mission_FOO]</code> substitutes the value contained in <code>missionVariables.FOO</code>)
*#* These are commonly used in OXPs as a method of including dynamic information in displayed text.
*# Legacy local variables (<code>[local_FOO]</code> substitutes the value contained in <code>worldScripts.scriptname.FOO</code> with the scriptname depending on the context where the text is being evaluated)
*#* A local variable is a property defined on a world script (e.g., a script.js in Config/, or any script listed in a [[Scripting Oolite with JavaScript|world-scripts.plist]]). this.name from a script.js in Config/ is used as the key for that script in the global worldScripts dictionary. As of Oolite 1.87, none of the core game texts use local variables.
*#* In [[Oolite_JavaScript_Reference:_Mission#addMessageText]] and [[Oolite_JavaScript_Reference:_Mission#addMessageTextKey]], the applicable scriptname is the calling script. As an example, if your script has a local variable <code>this.calculatedvalue</code> you could display the content of that variable with other text by calling <code>mission.addMissionText("various text [local_calculatedvalue] various other text");</code>
*# Legacy script query methods
*#* As a last resort, Oolite attempts to expand a key by treating it as a legacy script query method and invoking it. Only [[whitelist.plist|whitelisted]] query_methods and query_method_aliases are permitted. Examples: [systemGovernment_string] (a whitelisted query method), [fuelLevel_number] (a whitelisted query method) or [fuel_level_number] (a whitelisted alias for [fuelLevel_number])
* If no suitable replacement is found, the text will be displayed unchanged and a warning will be logged.

'''Operators:'''

If a vertical bar ('|') is found between square brackets, Oolite will interpret whatever is on the left side of the bar as the ''key'' and whatever is on the right side of the bar as an ''operator''. An ''operator'' tells Oolite to apply a change after the key has been expanded. Some operators also require an input value, a colon (':'). The available ''operators'' are:
* dcr - displays the text as a credit value, interpreting the value as floating point deci-credits (e.g., if the value is 100.7, display 10.7 credits)
* cr - displays the text as a credit value, interpreting the value as floating point credits (e.g., if the value is 100.7, display 100.7 credits)
* icr - displays the text as a credit value, interpreting the value as integer credits (e.g., if the value is 100.7, display 100.0 credits)
* idcr - displays the text as a credit value, interpreting the value as integer deci-credits, rounded (e.g., if the value is 100.7, display 10.0 credits)
* precision - displays the text as a floating point value with an integer-specified number of decimal places, must be specified as ''precision'':number (e.g., [distance|precision:2])
* multiply - displays the text as a floating point value multiplied with another floating point value, which must be provided as ''multiply'':othervalue (e.g., [fuelLevel_number|multiply:0.5])
* add - displays the text as a floating point value added to another floating point value, which must be provided as ''add'':othervalue (e.g., [fuelLevel_number|add:1.5])

Multiple ''operators'' can be applied sequentially to the same key, each separated by a vertical bar. For example: [distance|multiply:0.5|precision:1].

== When are things switched ==
Oolite calls the switching routine only at certain places ('''this is not a complete list'''):
*The most often used place is in [[missiontext.plist]]. Every text line is evaluated for string replacement. Most commonly this is used to replace text in brackets with the content of a variable or a [[descriptions.plist]] entry.
*Inside a [[descriptions.plist]] entry you can also use brackets. This way you can get a recursive process. Look for example in the descriptions.plist in Oolite's Resources\Config folder where it generates random names in a recursive way. (Recursion is limited to 32 times to prevent infinite looping.). Because of the random number generator used for expansion, the use of deep recursion may cause correlations which are not random - consider for example that "mud" is always followed by "tennis" or "hockey" in planetary descriptions, never anything else. In Oolite 1.79, certain ways of expanding descriptions from JavaScript will use a higher quality random number generator, which does not have correlation problems.
*During evaluation of a [[OXP howto AI|plist-based AI]], it only uses switching on the content of a "commsMessage".
*During evaluation of a [[script.plist]] all the lines in the DO or ELSE part of a condition statement are switched. Nothing is switched in the CONDITIONS part of a command so you cannot use anything in brackets there.
*In [[Oolite_JavaScript_Reference:_Global#expandDescription|expandDescription]] and [[Oolite_JavaScript_Reference:_Global#expandMissionText|expandMissionText]].

The way things work means that you can create complicated structures. You can use for example:
addSystemShips: my_ship 1 0.[d100_number]

Oolite first offers the above line to the replacement routine. That replaces [d100_number] by a random number. e.g. 46. Than the routine returns:
addSystemShips: my_ship 1 0.46

This line will then be executed and the ship is placed at the calculated random position. You can also define a [[descriptions.plist]] entry of my_random_ship and define a list of several ship roles. When you then use:
addSystemShips: [my_random_ship] 1 0.[d100_number]
the system will randomly pick a ship from the list and replace the d100_number with a value and return the expanded string. This will than be executed.

[[Category:Oolite scripting]]

Scripting Oolite with JavaScript

2020-06-20T19:49:04Z

Milo: changed world-scripts.plist to a link

[[Oolite]] 1.68 and later supports scripts written in [http://en.wikipedia.org/wiki/ECMAScript ECMAScript] (more commonly known as [http://en.wikipedia.org/wiki/JavaScript JavaScript]) in addition to its traditional model based on [[property lists]]. This page provides an overview of how JavaScript is used in Oolite. The page [[Oolite JavaScript Reference: object model]] provides reference for Oolite-specific objects and methods. The page [[Oolite JavaScript Reference: World script event handlers]] provides reference for the event handlers Oolite supports. The language standards and some tutorials can be found through the Wiki links provided above.

== Using JavaScript ==

Currently, JavaScript is supported for “worldScripts”, that is, as a replacement for scripts in ''script.plist'' and shipScripts, that acts as expansion for the ships AI. While a ''script.plist'' file may contain any number of separate scripts, a single JavaScript file may contain only one script.

If your OXP only uses one script, place a JavaScript file named ''script.js'' (or ''script.es'') in the OXP’s ''Config'' directory. If you wish to use multiple scripts, you may instead create file named ''world-scripts.plist'' in the ''Config'' directory. This [[property list]] file should consist of an array of worldScript names; the named scripts should exist in a directory named ''Scripts'' inside your OXP. As with most “atomic” files (files which cannot be merged), such script files must have a unique name to avoid conflicts with other OXPs. Using the [[world-scripts.plist]] method, you can combine JavaScript, plist and OOS scripts however you wish.

Whereas plist scripts are based on polling – all scripts are run at semi-regular intervals, whether they need to be or not – scripts written in JavaScript are “event driven” – different functions, or ''event handlers'', in the script are called in response to state changes in the game, or when other events of interest happen. For instance, <code>willExitWitchSpace</code> is called just before player exits witchspace, and <code>alertConditionChanged</code> is called whenever the alert condition changes. See the [[Oolite JavaScript event handler reference|event handler reference]] for a full list of handlers and when Oolite will call them.

=== script.js File Template ===

Copy and paste this template into a file called script.js in the OXP Config directory. Ensure you change at least the Name value. '''Every script must have a unique name.''' If multiple scripts with the same name are encountered, Oolite will arbitrarily select one and discard the others.

<pre>this.name = "My OXP Script";
this.author = "Your Name Here";
this.copyright = "(C) 2013 Me.";
this.licence = "CC-NC-by-SA 2.0";
this.description = "This OXP doesn't do very much yet.";
this.version = "1.0 alpha 1";

"use strict";

/* You can copy and paste this function and just change the "startUp"
to another event name to handle other OXP events (eg "shipDockedWithStation",
"alertConditionChanged", etc).
*/
this.startUp = function()
{
log(this.name, "Initialising OXP " + this.name);
}
</pre>

== See Also ==
* [https://developer.mozilla.org/en/JavaScript/Reference Mozilla JavaScript reference pages]
* [[Oolite JavaScript event handler reference]]
* [[Oolite JavaScript object model]]

* [[Variables in Oolite JavaScripts]]
* [[Javascript Operators]]
* [[Handling OXP Dependencies with JavaScript]]
* [[Optimization tips]]

[[Category:Oolite]]
[[Category:Oolite scripting]]

Worldscripts plist

2020-06-20T19:45:07Z

Milo: create redirect for worldscripts plist variant spelling

#REDIRECT [[Misc plists#world-scripts.plist]]