https://wiki.alioth.net/api.php?action=feedcontributions&user=Cim&feedformat=atomElite Wiki - User contributions [en]2024-03-29T01:41:13ZUser contributionsMediaWiki 1.31.12https://wiki.alioth.net/index.php?title=System_Features_Sunspots&diff=53814System Features Sunspots2016-10-01T09:04:01Z<p>Cim: /* Download */</p>
<hr />
<div>[[File:SystemFeaturesSunspots.png|right|frame|Occasional Solar Activity]]<br />
This OXP occasionally adds sunspots to stars. Systems with "solar activity" in their description are more likely to get sunspots, and more likely to have a larger number of them at once.<br />
<br />
== Download ==<br />
Download [http://cim.sotl.org.uk/games/files/oolite/System_Features_Sunspots_1.5.oxz System Features: Sunspots 1.5]. (Requires Oolite 1.80 or later)<br />
<br />
== Requirements ==<br />
A shader-supporting graphics card is required.<br />
<br />
<br style='clear:both'><br />
==Quick Facts==<br />
{{OXPLevel|0}}{{Infobox OXPb| title = System Features: Sunspots<br />
|version = 1.5<br />
|release = 2014-04-25<br />
|features = Sunspots<br />
|category = Ambience OXPs<br />
|author = [[User:cim|cim]]<br />
|download = [[#Download|See Download]]<br />
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=12544 Bulletin Board thread]<br />
}}</div>Cimhttps://wiki.alioth.net/index.php?title=System_Features_Rings&diff=53813System Features Rings2016-10-01T09:03:48Z<p>Cim: /* Download */</p>
<hr />
<div>This OXP adds some dust rings to a few planets in each galaxy. Whether those rings are traditional gas giant rings or debris rings from industry or long-past battles depends on your planet texture OXP.<br />
[[File:SystemFeaturesRings2.jpg|right]]<br />
<br />
== Download ==<br />
Download [http://cim.sotl.org.uk/games/files/oolite/System_Features_Rings_1.2.oxz System Features: Rings 1.2]. (Requires Oolite 1.80 or later)<br />
<br />
* 1.0: Initial non-beta release<br />
* 1.1: Improved ring texture and appearance contributed by ZygoUgo.<br />
* 1.2: Use 1.80 features, repackage<br />
<br />
== Requirements ==<br />
A shader-supporting graphics card is required, the more recent the better. Older shader-supporting cards may be too slow to render the rings at an adequate framerate.<br />
[[File:SystemFeaturesRings1.jpg|left]]<br />
<br style='clear:both'><br />
==Quick Facts==<br />
{{OXPLevel|0}}{{Infobox OXPb| title = System Features: Rings<br />
|version = 1.2<br />
|release = 2014-04-25<br />
|license = CC-BY-SA 3.0<br />
|features = Ring system<br />
|category = Ambience OXPs<br />
|author = [[User:cim|cim]]<br />
|download = [[#Download|See Download]]<br />
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=12544 Bulletin Board thread]<br />
}}</div>Cimhttps://wiki.alioth.net/index.php?title=Skilled_NPCs_OXP&diff=53812Skilled NPCs OXP2016-10-01T09:03:36Z<p>Cim: /* Download */</p>
<hr />
<div>The pirates and bounty hunters of the spacelanes can easily challenge an inexperienced commander. But once you're climbing the Elite Rankings and buying that iron ass, you might find them starting to get a little too easy. This OXP improves their combat skills so that you don't get too overconfident.<br />
<br />
== Download ==<br />
<br />
For Oolite 1.79 or later, download [http://cim.sotl.org.uk/games/files/oolite/Skilled_NPCs_1.2.oxz Skilled NPCs 1.2] and place the OXZ in your AddOns folder.<br />
<br />
== Difficulty ==<br />
<br />
You won't necessarily need a full iron-ass to deal with the new pilots - but you will need to know how to fly your ship. Still, without basic combat equipment such as ECM, beam lasers, and injectors you'll find it even harder to survive than normal. Even a fully-equipped ship won't keep you alive in the worst Anarchy systems, unless you earned that Elite Ranking.<br />
<br />
=== Configuration ===<br />
{{OXPConfig-small}}<br />
In its default configuration, this OXP replaces some but not all of the pilots with trained pilots at various levels of skill. The best will probably be as good as a Competent or even Dangerous player, and there'll be more than one of them. If they're still not tough enough for you, the difficulty can be increased on a sliding scale from 0 to 10 (0 is the default and still a noticeable change). This can be done either by editing the OXP script directly, or by using [[OXPConfig]] (2.2.4 or later). Each step up will give a significant increase in difficulty - by step 10, all pilots will be as skilled as Oolite can make them.<br />
<br />
== Compatibility with other OXPs ==<br />
Only ships with a standard role ("police", "trader", "hunter", "pirate", "escort", "thargoid", etc.) will be upgraded. Ships added by OXPs with a different role will not be upgraded unless this setting is modified by the player, and ships given a trained pilot by a different OXP will not have their pilot replaced here.<br />
<br />
You can set a <code>"skilled_npc_role"</code> property in <code>script_info</code>, and the value of this property will be used instead of the ship's role to decide what accuracy boosts to apply (therefore, in general it should be a standard role). If set to <code>"off"</code>, Skilled NPCs will never change the ship's accuracy, regardless of the selected configuration.<br />
<br />
In version 1.2 or later, only ships with <code>auto_weapons</code> set will ever have their accuracy changed.<br />
<br />
== Quick Facts ==<br />
<br />
{{OXPLevel|4|6}}{{Infobox OXPb| title = Skilled NPCs<br />
|version = 1.2<br />
|release = 2014-04-12<br />
|license = CC-BY-SA 3.0<br />
|features = Mechanics<br />
|category = Mechanics OXPs<br />
|author = [[User:cim|cim]]<br />
|download = [[#Download|See Download]]<br />
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=13308 Bulletin Board thread]<br />
}}</div>Cimhttps://wiki.alioth.net/index.php?title=New_Cargoes&diff=53811New Cargoes2016-10-01T09:03:22Z<p>Cim: /* Installation */</p>
<hr />
<div>New Cargoes adds over 100 new trade goods to the 8 galaxies. Each new good is a more specific<br />
variety of one of the generic cargoes: valuable to the right buyer,<br />
largely worthless otherwise. In addition, a variety of new trading<br />
opportunities are available.<br />
<br />
New Cargoes is designed to allow other OXPs to add cargoes, traders,<br />
and events to the universe as a framework, in addition to the cargoes and opportunities including in New Cargoes itself.<br />
<br />
==Installation==<br />
The current version of New Cargoes is 1.2.3. [http://cim.sotl.org.uk/games/files/oolite/New_Cargoes_1.2.3.oxz Download 1.2.3] and install in the usual way. This moves access to the New Cargoes trading to the new Interfaces screen (F4)<br />
<br />
===Other OXPs===<br />
Other OXPs that affect cargo handling are compatible with New Cargoes.<br />
* [[HyperCargo_OXP|HyperCargo]], if installed, should be at least version 1.07. If you take an open contract, you should take care to avoid placing the open contract's cargo in the HyperCargo at any time, as you may lose it if you do.<br />
* [[Illegal_Goods_Tweak_OXP|Illegal Goods Tweak]], if installed, should be at least version 1.7<br />
<br />
==Using New Cargoes==<br />
[[Image:New_Cargoes.png|250px|right]]<br />
<br />
Once New Cargoes is installed, load your saved game or start a new<br />
one. If this is the first time you have loaded the game since<br />
installing or upgrading New Cargoes, you should wait a couple of seconds before<br />
continuing, to ensure that all New Cargoes data is initialised<br />
properly.<br />
<br />
'''In version 1.1.0 or earlier''': At a main station, press F8 three times to get to the New Cargoes trade interface. At a supported non-main station, press F2 then F8 instead. When you have finished, select "Exit specialist cargo trading" to return to your ship.<br />
<br />
'''In version 1.2.0 or later''': At any supported station, press F4 to bring up the Interface screen, then select "Speciality Cargo Trading" from the "Commerce" category.<br />
<br />
===Buying and selling cargo===<br />
<br />
Your first option allows you to buy special cargo from the station's<br />
market. This will be available in moderate quantities for a set price,<br />
similar to the standard trade goods. As usual, you must have room in<br />
your hold and enough credits on hand to buy the cargo. It will then<br />
appear on your ship's manifest as 1TC of the appropriate generic cargo<br />
type. For instance, if you buy "Goat Soup", it will appear as "Food"<br />
on your manifest.<br />
<br />
The second option allows you to sell carried cargo to buyers at the<br />
station. Again, the price is set automatically for this service. Make<br />
sure you sell special cargo in this way rather than through the<br />
general F8 screen, or you will make a significant loss.<br />
<br />
The trick, of course, is to buy the cargo cheaply at a system where it<br />
is plentiful, and then take it to sell for massive profits at a system<br />
where it is rare but desired. For most goods there will only be a<br />
small number of systems in each galaxy that really want to buy them.<br />
<br />
===Gathering trade route information===<br />
<br />
The third option tells you the exports and imports of the current system, and then takes you to the trader bars to gather<br />
gossip about other systems. Traders are sometimes happy to chat about their recent<br />
successes and failures, and intentionally giving misinformation is<br />
rare. Do remember, however, that just because one trader made a<br />
massive profit taking cargo from A to B doesn't mean you'll<br />
automatically be able to do the same. Try to confirm any information<br />
you pick up here before acting on it.<br />
<br />
===Trade deals===<br />
<br />
The fourth option takes you to the trade floor. In most main stations<br />
there will be someone here offering a more interesting deal - an<br />
auction, a special contract, a permit to legally carry controlled<br />
goods, or something else. Be careful, as not everyone here will have<br />
your best interests in mind. Make sure that you can fulfil your side<br />
of the deal before signing any agreements.<br />
<br />
===Detailed manifest===<br />
<br />
The fifth option shows your manifest in more detail, on multiple pages<br />
if needed. The origin of goods you have collected will be shown to aid<br />
your memory and help you assess your profit margins.<br />
<br />
===Contracts and permits===<br />
<br />
The sixth option shows you details of the contracts you have entered<br />
into, any permits you are carrying, and any special regulations<br />
applying to trade in this system.<br />
<br />
===TraderNet===<br />
<br />
If you have bought a TraderNet subscription, you can view recent TraderNet bulletins with the seventh option. These contain information on places to buy and sell trade goods, upcoming events, and regional fluctuations in prices.<br />
<br />
==How to trade well==<br />
<br />
The concise summary:<br />
* Look at as many sources of information as you can about trade goods, and look for patterns in what can be bought and sold where.<br />
* Plan your route in advance. If you don't have a full hold, maybe there's a short detour that would be profitable on the way.<br />
* Get a TraderNet subscription (from the shipyard), and keep it renewed. If you hear about something nearby, act quickly.<br />
<br />
[[New_Cargoes_Trading_Advice|More detailed trading advice]].<br />
<br />
==Difficulty==<br />
<br />
If you choose to trade mostly or exclusively in new cargoes,<br />
then making a trading profit will become much less reliable (though<br />
there are higher profits when you succeed), and may require you to<br />
travel through more dangerous systems.<br />
<br />
Also, New Cargoes makes some OXP stations - the ones which are most friendly to Galcop - use Galcop's rules for import and export of illegal goods. This can surprise you even if you aren't carrying new cargoes, so be careful.<br />
<br />
==New Cargoes for OXP writers==<br />
<br />
New Cargoes provides a flexible framework for other OXPs to add extra cargoes and trade opportunities. See the [[NewCargoesAPI|New Cargoes API reference]] for more information.<br />
<br />
==Change log==<br />
* 1.2.3: Fix bugs with save/load of regional data and pricing of fetch contracts. Thanks to Solonar and Keeper for reports.<br />
* 1.2.2: Fix serious bug with losing cargo on launch. Thanks to Solonar for patient diagnosis.<br />
* 1.2.1: Fix bug with permits<br />
* 1.2.0: Oolite 1.77 required. Move access to the Interfaces screen. Some internal improvements, and a few more trade routes.<br />
* 1.1.0: Removed Snoopers dependency, some interface improvements suggested by JazHaz, by popular demand introduced a few easier ways to find out where trade goods can be exported and imported at a decent profit, and made import prices slightly more generous.<br />
* 1.0.6: Fix bugs with the handling of permits, Kiota stations, and open contracts found by Capt. Murphy, BuggyBY and XLA <br />
* 1.0.5: Fix bug with world script startup order found by Eric Walch.<br />
* 1.0.4: Fix bugs with Ore Processor and with open contracts; thanks to Wardy and BuggyBY<br />
* 1.0.3: Fix bug with import/export laws at some OXP stations; add new API functions.<br />
* 1.0.2: Fix bug with permits and misjumps; thanks to Capt. Murphy for report.<br />
* 1.0.1: Extra API function for [[HyperCargo_OXP|HyperCargo]] compatibility<br />
* 1.0.0: Initial release version<br />
<br />
==Quick Facts==<br />
{{OXPLevel|1}}{{Infobox OXPb| title = New Cargoes<br />
|version = 1.2.3<br />
|release = 2013-02-09<br />
|features = New cargoes and trade contracts<br />
|license = CC-BY-SA 3<br />
|category = Mechanics OXPs<br />
|author = [[User:cim|cim]]<br />
|download = [[#Download|See Download]]<br />
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=11519 BB-Link]<br />
}}</div>Cimhttps://wiki.alioth.net/index.php?title=Escort_Formations&diff=53810Escort Formations2016-10-01T09:03:08Z<p>Cim: /* Download */</p>
<hr />
<div>[[File:Convoy.png|right|frame|The Convoy formation avoids surprises on the spacelane by placing a fighter group fore and aft of the leader]]<br />
<br />
The Escort Formations OXP adds 19 extra escort formations to the game, which will be used by traders and pirates, and can be used by other ships. The escort formations are divided into two categories - offensive formations, usually used by pirates to give a strong attack or to hide their strength - and defensive formations, usually used by traders to give good scanner coverage and avoid pirate ambushes.<br />
<br />
As this breaks up both trader and pirate formations, it can make it slightly more difficult to tell the difference between traders and pirates on the spacelane.<br />
<br />
==Download==<br />
[http://cim.sotl.org.uk/games/files/oolite/Escort_Formations_1.1.oxz Escort Formations 1.1] is the latest version. Install to your AddOns folder in the usual way.<br />
<br />
==Technical details==<br />
Only ships with a primary role of ''trader'', ''pirate'', ''hunter'' or ''police'' (from the core game) or ''bigTrader'', ''liner'', ''coachwhip'' or ''fuelship'' (from OXPs) will normally be affected by this OXP, and only those ships which are spawned with escorts. Ships which already have their own custom escort formation will not be affected, and some of the remaining eligible ships will keep the standard escort formation.<br />
<br />
You can apply the escort formations defined by this OXP to your own ships with other roles by using the following functions:<br />
To assign a random offensive formation to a different ship, suited to its escort count<br />
worldScripts["Escort Formations Randomiser"].$setupOffensiveEscorts(ship);<br />
<br />
To assign a random defensive formation to a different ship, suited to its escort count<br />
worldScripts["Escort Formations Randomiser"].$setupDefensiveEscorts(ship);<br />
<br />
To assign a specific formation to a ship<br />
worldScripts["Escort Formations Randomiser"].$setupEscortFormation(ship,formation);<br />
<br />
''formation'' is the name of the formation. The 19 formations available in version 1.1 are:<br />
* arrowhead<br />
* bulge<br />
* combat-spread<br />
* convoy<br />
* echelon<br />
* flank<br />
* helix<br />
* near-far<br />
* octahedron<br />
* opencolumn<br />
* planebox<br />
* pyramid<br />
* scouting-spread<br />
* screen<br />
* trail<br />
* twistbox<br />
* vform<br />
* vwide<br />
* wave<br />
If an unrecognised formation name is given, "vform" will be applied, which is similar, though not identical, to the standard escort formation.<br />
<br />
[[File:EscortFormationsArrowhead.png|345px|The Arrowhead formation provides heavy firepower on the initial attack]]<br />
<br />
==Change log==<br />
1.1: Add eight more formations, include some common OXP trader-like roles in the list.<br />
<br />
1.0: Initial public release<br />
<br />
==Quick facts==<br />
{{OXPLevel|1}}{{Infobox OXPb| title = Escort Formations<br />
|version = 1.1<br />
|release = 2012-09-02<br />
|license = CC-BY-SA 3.0<br />
|features = Escort formations<br />
|category = Mechanics OXPs<br />
|author = cim<br />
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=12117 BB-Link]<br />
}}</div>Cimhttps://wiki.alioth.net/index.php?title=Curse_of_the_Black_Sunspot&diff=53809Curse of the Black Sunspot2016-10-01T09:02:59Z<p>Cim: /* Download */</p>
<hr />
<div>Curse of the Black Sunspot is a short mission OXP set in a nondescript backwater of Galaxy 3. <br />
<br />
It will start when the player is in Galaxy 3 with an Elite rating of<br />
at least Dangerous. The mission involves a couple of tricky fights,<br />
but can be completed with a standard Cobra III.<br />
<br />
This is an "informal" mission - no-one is hiring you: there is simply<br />
a situation which you can choose to interact with or avoid. Therefore,<br />
it might take you a while before you find out where to go and what to<br />
do to find the situation. Alternatively, you might accidentally<br />
stumble into it while going about your normal business.<br />
<br />
No other OXPs are required, though [[Randomshipnames_OXP|Random Ship Names]] is strongly<br />
recommended, and users of [[Snoopers]] and [[New Cargoes]] will find a few<br />
additional hints about the situation delivered through the messages in<br />
those OXPs (though nothing you can't find out through other sources).<br />
<br />
Many thanks to Solonar and Diziet Sma for beta testing and feedback.<br />
<br />
==Download==<br />
This OXP requires Oolite 1.80 or later. Shaders are used in a few places for improved graphics, but the OXP can be played without them.<br />
<br />
Download [http://cim.sotl.org.uk/games/files/oolite/Curse_of_the_Black_Sunspot_1.0.2.oxz COTBS 1.0.2] and install to your AddOns folder in the usual way.<br />
<br />
==Quick Facts==<br />
{{OXPLevel|5}}{{Infobox OXPb| title = Curse of the Black Sunspot<br />
|version = 1.0.2<br />
|release = 2013-04-01<br />
|features = "Informal" mission<br />
|license = CC-BY-SA 3<br />
|category = Missions OXPs<br />
|author = [[User:cim|cim]]<br />
|download = [[#Download|See Download]]<br />
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=13588 BB-Link]<br />
}}</div>Cimhttps://wiki.alioth.net/index.php?title=Communications_Pack_A&diff=53808Communications Pack A2016-10-01T09:02:50Z<p>Cim: /* Download */</p>
<hr />
<div>Communications Pack A adds a range of communications messages to the NPCs using the [[Oolite_PriorityAI_Documentation#Global_Configuration|new communications routines]]. 19 different NPC personalities are included so far, each with a range of messages for different situations. Don't forget to set your ship and commander name while docked at a station, so that they can talk to you using them - [[Randomshipnames_OXP|Random Ship Names]] is recommended to add NPC names.<br />
<br />
==Download==<br />
Download via the Addons manager or directly at [http://cim.sotl.org.uk/games/files/oolite/Comms_Pack_A_0.5.oxz Comms Pack A 0.5]. It requires Oolite 1.79 or later.<br />
<br />
==For OXP developers==<br />
Communications Pack A is licensed very freely, and extensively commented inside. It is intended for adaptation and copying of the framework for other authors to make Communications Packs B, C, D, etc. with different personalities and speech patterns. Please ask if you have any questions about how to do this.<br />
<br />
==Quick facts==<br />
{{OXPLevel|0}}{{Infobox OXPb| title = Communications Pack A<br />
|version = 0.5<br />
|release = 2014-06-29<br />
|license = MIT<br />
|features = NPC communications<br />
|category = Ambience OXPs<br />
|author = cim<br />
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=16462 BB-Link]<br />
}}</div>Cimhttps://wiki.alioth.net/index.php?title=Combat_Simulator_OXP&diff=53807Combat Simulator OXP2016-10-01T09:02:41Z<p>Cim: /* Download */</p>
<hr />
<div>After ever-increasing concerns about the number of pilots dying on their first trip due to pirate attacks, a number of systems have funded the installation of simulated combat environments for training purposes. With the simulators being capable of producing fights considerably tougher than the average pirate pack, they're also popular with skilled combateers wanting to show off after a drink or two.<br />
<br />
== Features ==<br />
<br />
This OXP adds a combat simulator to some stations (generally the<br />
higher-tech ones) where you can set up controlled battles against<br />
particular opponents. To start a fight, go to the interfaces screen<br />
(F4) and select "Combat Simulator". Then, select the ships, skill, and<br />
numbers of your opponent(s).<br />
<br />
The fight will end if:<br />
* you defeat all your opponents<br />
* your ship would be destroyed<br />
* the simulator buoy is destroyed<br />
* you leave scanner range of the simulator buoy<br />
<br />
You will not be able to use an escape pod or hyperspace during the<br />
simulation.<br />
<br />
All damage taken, consumable items used, etc. during the fight will<br />
not be applied to your real ship. The ship you fly in the simulator<br />
will be your current ship in whatever state it is currently in.<br />
<br />
There is no charge for using the simulator, but it is a popular<br />
service and there is often a queue. Expect to wait around ten minutes<br />
for your turn.<br />
<br />
==Download==<br />
Download [http://cim.sotl.org.uk/games/files/oolite/Combat_Simulator_1.1.oxz Combat Simulator 1.1]<br />
<br />
This OXP requires Oolite 1.80 and [http://aegidian.org/bb/viewtopic.php?f=4&t=11892 Ship Storage Helper OXP] and will not run otherwise.<br />
<br />
== Difficulty ==<br />
<br />
While some of the simulated fights can be quite tough, and well outside the strength of anything you might normally encounter, this is mitigated by you never having to fight in those fights, and it being impossible for you to actually die as a result. Still, you should probably start with the easy settings, unless you're already a renowned combateer.<br />
<br />
== Quick Facts ==<br />
<br />
{{OXPLevel|0}}{{Infobox OXPb| title = Combat Simulator<br />
|version = 1.1<br />
|release = 2014-04-25<br />
|license = CC-BY-SA 3.0<br />
|features = Activities<br />
|category = Activities OXPs<br />
|author = [[User:cim|cim]]<br />
|download = [[#Download|See Download]]<br />
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=13650 Bulletin Board thread]<br />
}}</div>Cimhttps://wiki.alioth.net/index.php?title=Camera_Drones&diff=53806Camera Drones2016-10-01T09:02:25Z<p>Cim: /* Download */</p>
<hr />
<div>Camera Drones allow you to get a different perspective on the action, by complementing your ship's hull-mounted cameras and sensors. Purchase them for 1000 Cr. at any TL:8 or better shipyard. <br />
<br />
== Usage ==<br />
<br />
While in flight, press Shift-N to cycle through your equipment to the camera drones. Then use the secondary activation key (b) to select the camera you wish to use from the installed list. When you have selected the camera, activate the equipment (n), and switch to your external view (v). To deactivate the drones, and return to your default external view, press 'n' again.<br />
<br />
There are four available cameras:<br />
[[File:CameraDrone_MissileCam.png|right|200px]]<br />
=== Missile camera ===<br />
The Missile Camera tracks your most recently fired missile, following it closely to its target. If you have no missiles currently in flight, this setting cannot be used, and the camera drones will be deactivated.<br />
<br />
=== Fly-by camera ===<br />
This camera begins ahead of your ship, then flies alongside it to a similar distance aft. Then, the sequence begins again, rotated. Useful for checking your hull for damage. Four variations of fly-by are available.<br />
<br />
[[File:CameraDrone_DockingCam.png|right|200px]]<br />
=== Docking camera ===<br />
This camera is positioned in a fixed location near the docking port of the nearest station. Activate the camera, then turn on your docking computer and watch your ship fly in from a new perspective.<br />
<br />
=== Target cameras ===<br />
These cameras provide an approximate simulation of your current target's forward view, or two different nearby views. May give odd results if your current target is not a ship.<br />
<br />
=== Extra drones? ===<br />
Camera Drones allows the definition of extra drone cameras by other OXPs. Read the readme file in the OXP download for more information.<br />
<br />
== Download ==<br />
Download [http://cim.sotl.org.uk/games/files/oolite/Camera_Drones_1.4.oxz Camera Drones 1.4]. (Requires Oolite 1.80 or later)<br />
<br />
==Quick Facts==<br />
{{OXPLevel|0}}{{Infobox OXPb| title = Camera Drones<br />
|version = 1.4<br />
|release = 2014-06-21<br />
|license = CC-BY-SA 3.0<br />
|features = Equipment<br />
|category = Equipment OXPs<br />
|author = [[User:cim|cim]]<br />
|download = [[#Download|See Download]]<br />
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=13297 Bulletin Board thread]<br />
}}</div>Cimhttps://wiki.alioth.net/index.php?title=Shipdata.plist&diff=48481Shipdata.plist2015-08-23T20:08:56Z<p>Cim: /* weapon_position_.. */ 1.83 updates</p>
<hr />
<div>'''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:<br />
<br />
<br />
= Ship keys=<br />
The following keys are used by all ships<br />
==accuracy==<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Example:<br />
"accuracy" = 8.3;<br />
<br />
== aft_eject_position ==<br />
Determines the XYZ point on the model from which cargo is ejected.<br />
<br />
Example:<br />
"aft_eject_position" = "0.0 -4.5 -23.0";<br />
<br />
== aft_weapon_type ==<br />
Assigns the ship's aft laser. <br />
Any weapon type from the [[equipment.plist]] can be used (and WEAPON_NONE). <br />
<br />
Example:<br />
"aft_weapon_type" = "WEAPON_BEAM_LASER";<br />
<br />
== ai_type ==<br />
Assigns an AI to the entity. This may be a previously existing AI, or one custom made for the occasion.<br />
<br />
Example:<br />
"ai_type" = "pirateAI.plist";<br />
<br />
== auto_ai ==<br />
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.<br />
Example:<br />
"auto_ai" = yes;<br />
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.<br />
<br />
== auto_weapons ==<br />
Added in 1.79<br />
<br />
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.<br />
<br />
Example:<br />
"auto_weapons" = yes;<br />
<br />
== beacon ==<br />
A special feature for beacons and navigation aids.<br />
The string can be anything - the first letter is what's displayed in the advanced space compass.<br />
<br />
Example: <br />
"beacon" = "X";<br />
<br />
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.<br />
<br />
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].<br><br />
Example in shipdata:<br />
"beacon" = "fuelStation_location";<br />
Example in descriptions.plist<br />
"fuelStation_location" = (1, 2, -3, 2, -3, -4, 3, -4, 3, 4, -3, 4, -3, 3, 2, 3, 2, -3, 1, -3 );<br />
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.<br />
<br />
== beacon_label ==<br />
(1.79 or later)<br />
<br />
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<br />
"beacon_label" = "%H Station"; // Lave Station, Diso Station, etc.<br />
<br />
== bounty ==<br />
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.<br />
<br />
Example:<br />
"bounty" = 50;<br />
<br />
== cargo_carried ==<br />
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.<br />
<br />
Example:<br />
"cargo_carried" = "Gold";<br />
<br />
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.<br><br />
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.)<br><br />
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)<br />
<br />
'''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.<br />
<br />
== [[cargo_type]] ==<br />
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.)<br><br />
<br />
Example:<br />
"cargo_type" = "CARGO_RANDOM";<br />
<br />
Will create random cargo, often based on availability in the system. When you want fixed cargo you can use:<br />
<br />
Example:<br />
"cargo_type" = "CARGO_CARRIED";<br />
"cargo_carried" = "4 Gold";<br />
<br />
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]].<br />
<br />
Example:<br />
"cargo_type" = "CARGO_NOT_CARGO";<br />
"cargo_carried" = "Computers";<br />
<br />
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.<br><br />
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.<br />
<br />
== cloak_automatic ==<br />
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) Key added with Oolite 1.75<br />
<br />
Example:<br />
"cloak_automatic" = no;<br />
<br />
== cloak_passive ==<br />
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) <br />
<br />
Example:<br />
"cloak_passive" = yes;<br />
<br />
==conditions==<br />
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.<br />
<br />
Example:<br />
"conditions" = (<br />
"systemGovernment_number equal 3",<br />
"systemEconomy_number lessthan 4"<br />
);<br />
<br />
==condition_script==<br />
''Available from Oolite 1.77 onwards''<br />
<br />
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.<br />
<br />
Example:<br />
"condition_script" = "myoxp_conditions.js";<br />
<br />
== counts_as_kill ==<br />
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. Key is added with Oolite 1.75<br />
<br />
Example:<br />
"counts_as_kill" = no;<br />
<br />
== custom_views==<br />
Will add the ability to display custom POVs of the player ship, in game toggled by pressing '''v'''. <br />
<br />
This is an array with any number of entries, one for each view, each with:<br />
*a '''view_description''' - giving a textual description of the view. <br />
*a '''view_position''' - relative to the origin of the ship model. <br />
*a '''view_orientation''' - this is a [[Quaternions|quaternion]] expressing a rotation from directly forwards. <br />
*a '''weapon_facing''' - FORWARD, AFT, PORT or STARBOARD. The weapon that will fire when that view is selected.<br />
<br />
The view_position is best chosen by selecting a facet, line or point in Wings and copying down the coordinates. <br />
<br />
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: <br />
<br />
W = the cosine of half the angle rotated about the axis xyz<br /><br />
X = the sine of half the angle rotated about xyz, multiplied by x<br /><br />
Y = the sine of half the angle rotated about xyz, multiplied by y <br /><br />
Z = the sine of half the angle rotated about xyz, multiplied by z <br /><br />
<br />
Four decimal places are probably enough accuracy for these values.<br />
<br />
Example:<br />
custom_views =<br />
(<br />
{<br />
view_description = "Front View";<br />
view_orientation = "0.0 0.0 1.0 0.0";<br />
view_position = "0.0 30.0 200.0";<br />
weapon_facing = "FORWARD";<br />
}<br />
);<br />
<br />
== death_actions ==<br />
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.<br />
<br />
Example:<br />
"death_actions" = ("spawn: explosive_shrapnel 1");<br />
<br />
== debris_role ==<br />
Specifies the kind of debris an asteroid or boulder generates. When not defined they default to generating 'ships' with role "boulder" or "splinter". (Key added with Oolite 1.74)<br />
<br />
Example:<br />
"debris_role" = "my_boulder_foo";<br />
<br />
== density ==<br />
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.<br />
<br />
Ship's mass does not affect its flight under the non-inertial engines - see [[#thrust|thrust]]. It does affect:<br />
* changes in momentum, and damage done, in a collision<br />
* 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)<br />
* the length of time a witchspace wormhole opened by this ship will remain open, and the radius of that wormhole.<br />
<br />
Example:<br />
"density" = 1.5;<br />
<br />
== display_name ==<br />
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.<br />
<br />
Example:<br />
"display_name" = "ExampleShip Mark IX";<br />
<br />
== energy_recharge_rate ==<br />
The rate at which energy is replenished. Stations are at 100, Adders at 2. (Default value: 1)<br />
<br />
Example:<br />
"energy_recharge_rate" = "3.5";<br />
<br />
== escape_pod_model ==<br />
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).<br />
<br />
Example:<br />
"escape_pod_model" = "custom_pod";<br />
<br />
== escorts ==<br />
Determines how many escorts an NPC shall have. Maximum is 16.<br />
<br />
Example:<br />
"escorts" = 4;<br />
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.<br><br />
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. <br />
<br />
== escort_role ==<br />
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.)<br />
<br />
Example:<br />
"escort_role" = "my_custom_escort_role";<br />
Escort ships will use the escortAI.plist unless "auto_ai" is set to false.<br />
<br />
<br />
==escort_roles==<br />
''Available from Oolite 1.79 onwards''<br />
<br />
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.<br />
<br />
escort_roles = (<br />
{ role = "escort"; min = -2; max = 2; },<br />
{ role = "escort-medium"; min = 0; max = 4; },<br />
{ role = "escort-heavy"; min = -4; max = 2; },<br />
{ role = ""; min = 0; max = 2; } // spare slots for wandering escorts<br />
);<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
== escort_ship ==<br />
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.)<br />
<br />
Example:<br />
"escort_ship" = "cobramk1";<br />
Escort ships will use the escortAI.plist unless "auto_ai" is set to false.<br />
<br />
In Oolite 1.77 and later it is also possible to use <code>"escort_role" = "[cobramk1]"</code><br />
<br />
== exhaust ==<br />
The XYZ position(s) of exhaust plume(s), and the XYZ of the plume shape, ergo<br />
<br />
x y z width height length<br />
<br />
'''x y z''' is the position relative to the origin of the main model. <br />
<br />
'''width''' in meters, how far a plume extends on x axis, on each side of plume position. (x radius)<br />
<br />
'''height''' in meters, how far a plume extends on y axis, above and below of plume position. (y radius)<br />
<br />
'''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)<br />
<br />
<br />
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)<br />
<br />
Example:<br />
"exhaust" = (<br />
"5 0.0 -25 3.0 2.0 10.0",<br />
"-5 0.0 -25 3.0 2.0 10.0"<br />
);<br />
<br />
== explosion_type ==<br />
In Oolite 1.81 or later, a list of [[explosions.plist]] entries describing how the ship explodes if destroyed.<br />
<br />
Example:<br />
"explosion_type" = ("oolite-default-asteroid-explosion");<br />
<br />
== extra_cargo ==<br />
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.<br />
<br />
Example:<br />
"extra_cargo" = 25;<br />
<br />
== forward_weapon_type ==<br />
Assigns the ship's forward laser. <br />
Any weapon type from the [[equipment.plist]] can be used.<br> e.g.: WEAPON_PULSE_LASER, WEAPON_BEAM_LASER, WEAPON_MILITARY_LASER, WEAPON_MINING_LASER, WEAPON_PLASMA_CANNON, WEAPON_THARGOID_LASER and WEAPON_NONE. <br />
<br />
Example:<br />
"forward_weapon_type" = "WEAPON_BEAM_LASER";<br />
<br />
== frangible ==<br />
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. <br />
If set to false, the object plus subentities will be regarded as a single object.<br />
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.<br />
<br />
Example:<br />
"frangible" = no;<br />
<br />
== fragment_chance ==<br />
Determines if a ship breaks apart into fragments and generates parts with role "wreckage". By chance factor, or true/false. Default is 90% chance.<br />
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)<br />
<br />
Example:<br />
"fragment_chance" = no;<br />
<br />
== fuel ==<br />
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)<br />
<br />
Example:<br />
"fuel" = 70;<br />
<br />
== has_cloaking_device ==<br />
Determines if a ship has a cloacking device installed. By chance factor, or true/false.<br />
<br />
Example:<br />
"has_cloaking_device" = 0.5;<br />
<br />
== has_ecm ==<br />
Determines if a ship has the E.C.M system installed. By chance factor, or true/false.<br />
<br />
Example:<br />
"has_ecm" = 0.5;<br />
or<br />
"has_ecm" = no;<br />
<br />
== has_energy_bomb ==<br />
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.<br>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.<br />
<br />
Example: <br />
"has_energy_bomb" = yes;<br />
<br />
== has_escape_pod ==<br />
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.<br />
<br />
Examples:<br />
has_escape_pod = no;<br />
has_escape_pod = 0.75;<br />
has_escape_pod = 3;<br />
<br />
== has_fuel_injection ==<br />
Determines if a ship has the witchdrive fuel injector.<br />
<br />
Example:<br />
"has_fuel_injection" = 0.99;<br />
<br />
==has_military_jammer==<br />
Determines if a ship has a military jammer. Ships equipped with this item become invisible on the radar. <br />
Example:<br />
"has_military_jammer" = 0.75;<br />
<br />
==has_military_scanner_filter==<br />
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. <br />
Example:<br />
"has_military_scanner_filter" = 0.50;<br />
<br />
== has_scoop ==<br />
Determines if a ship has a fuel/cargo scoop.<br />
<br />
Example:<br />
"has_scoop" = no;<br />
<br />
== has_scoop_message ==<br />
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)<br />
<br />
Example:<br />
"has_scoop_message" = no;<br />
<br />
== has_shield_booster==<br />
Determines if a ship has the shield booster. (enlarges max energy with 256)<br />
<br />
Example:<br />
"has_shield_booster" = 0.80;<br />
<br />
== has_shield_enhancer ==<br />
Determines if a ship has the coveted shield enhancer. (enlarges max energy with 256 and raises energy recharge rate with 50%)<br />
<br />
Example:<br />
"has_shield_enhancer" = 0.45;<br />
<br />
== heat_insulation ==<br />
This real number gives the amount of heat insulation of a ship. Default is 1.0 Only for NPC ships. Playes ships can have the equipment EQ_HEAT_SHIELDING with gives the player than a heat_insulation of 2.0<br />
<br />
Example:<br />
"heat_insulation" = "2.0";<br />
<br />
== hud ==<br />
Used for a playership, to assign another HUD than the default one.<br />
<br />
Example:<br />
"hud" = "specialhud.plist";<br />
<br />
== hyperspace_motor ==<br />
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)<br />
<br />
Examples:<br />
"hyperspace_motor" = no;<br />
<br />
hyperspace_motor=NO;<br />
<br />
== hyperspace_motor_spin_time ==<br />
Used to modify jump countdown time. Default = 15.<br />
<br />
Examples:<br />
"hyperspace_motor_spin_time" = "15";<br />
<br />
==injector_burn_rate==<br />
The default fuel burn rate of injectors on this ship, in deci-LY per second. The default is 0.25.<br />
<br />
"injector_burn_rate" = 0.25;<br />
<br />
Added in Oolite 1.81<br />
<br />
==injector_speed_factor==<br />
The multiplier applied to the ship's maximum speed when it is using injectors. The default is 7.<br />
<br />
"injector_speed_factor" = 7;<br />
<br />
Added in Oolite 1.81<br />
<br />
==is_external_dependency==<br />
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.<br>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.<br />
<br />
Example:<br />
"is_external_dependency" = yes;<br />
<br />
==is_submunition==<br />
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.<br />
<br />
Example:<br />
"is_submunition" = yes;<br />
<br />
==is_template==<br />
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.<br />
<br />
Example:<br />
"is_template" = yes;<br />
<br />
== laser_color ==<br />
Determines a ship's laser colour.<br />
<br />
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.<br />
<br />
Example:<br />
"laser_color" = "cyanColor"<br />
<br />
<br />
== launch_actions ==<br />
Triggers a script on the entity just after setup, also when called by spawn and addShip methods.<br />
Can be used to change to a custom AI, when a ship is generated by standard role. <br />
[[Shipdata.plist#script_actions|script_actions]]<br />
<br />
Example:<br />
"role = trader";<br />
"launch_actions" = (<br />
"setAITo: pirateAI.plist"<br />
);<br />
<br />
<br />
== like_ship ==<br />
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.<br />
<br />
Works well together with the [[#is_template|is_template]]-key.<br />
<br />
Example:<br />
"my_ship" = {<br />
"like_ship" = "adder";<br />
"max_flight_speed" = "700";<br />
"name" = "Freak Turbo Adder";<br />
},<br />
<br />
== likely_cargo ==<br />
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.<br />
<br />
Example:<br />
"likely_cargo" = "2";<br />
<br />
== materials ==<br />
See [[Materials in Oolite]].<br />
<br />
<br />
== max_cargo ==<br />
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.<br />
<br />
Example:<br />
"max_cargo" = "5";<br />
<br />
== max_energy ==<br />
Sets the ship's energy value. (Default value: 200)<br />
<br />
Example:<br />
"max_energy" = "300";<br />
<br />
<br />
== max_flight_pitch ==<br />
Sets pitch factor. Will usually range from a sluggish 0.6 to a very sensitive 3.0<br />
<br />
Example:<br />
"max_flight_pitch" = "2.2";<br />
<br />
<br />
== max_flight_roll ==<br />
Sets roll factor. Will usually range from 0.8 to 4.6.<br />
<br />
Example:<br />
"max_flight_roll" = "4.2";<br />
<br />
<br />
== max_flight_speed ==<br />
Sets the model's top speed. Interceptors fly at 520 (0.52 LM), Shuttles at 80.<br />
<br />
Example:<br />
"max_flight_speed" = "320";<br />
<br />
== max_flight_yaw ==<br />
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<br />
<br />
Example:<br />
"max_flight_yaw" = "2.2";<br />
<br />
== max_missiles ==<br />
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.<br />
<br />
Example:<br />
"max_missiles" = "1";<br />
<br />
== missile_launch_position ==<br />
Determines the XYZ point on the model from which a missile is launched.<br />
<br />
Example:<br />
"missile_launch_position" = "0.0 -2.25 10.0";<br />
<br />
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)<br><br />
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.<br />
<br />
== missile_load_time ==<br />
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.<br />
<br />
Example:<br />
"missile_load_time" = "2.1";<br />
<br />
<br />
== missiles ==<br />
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.<br />
<br />
Example:<br />
"missiles" = "0";<br />
<br />
== missile_role ==<br />
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.<br />
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. <br />
<br />
To assign a specific missile type to a newly bought player ship, its dependancies must be defined inside [[shipyard.plist]].<br />
<br />
Example: <br />
"missile_role" = "EQ_THARGON";<br />
<br />
== model ==<br />
Assigns the entity's corresponding '''.dat''' file that will be found with the exact same name in the ''Models'' folder.<br />
<br />
Example:<br />
"model" = "example_ship.dat";<br />
<br />
== model_scale_factor ==<br />
1.81 or later only.<br />
<br />
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.<br />
<br />
Player ships will also have their internal and external view positions multiplied by the scale factor.<br />
<br />
model_scale_factors on subentities will be ignored - the value for the main entity will be used instead.<br />
<br />
Example:<br />
"model_scale_factor" = 2.0;<br />
<br />
== name ==<br />
States the model's name as it will be known to the ID computer.<br />
<br />
Example:<br />
"name" = "ExampleShip Mark IX";<br />
<br />
== no_boulders ==<br />
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.<br />
<br />
Example:<br />
"no_boulders" = yes;<br />
<br />
== pilot ==<br />
Gives the ship a predefined pilot, defined in [[characters.plist]]. Can eject in pod, if available, and be captured.<BR><br />
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.<br />
<br />
Example:<br />
"pilot" = "constrictor-mission-thief";<br />
<br />
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)<br />
<br />
== port_weapon_type ==<br />
(Oolite 1.77 or later)<br />
Assigns the ship's port laser. <br />
Any weapon type from the [[equipment.plist]] can be used (and WEAPON_NONE). <br />
<br />
While not essential, you should generally assign the same weapon to [[#starboard_weapon_type|starboard_weapon_type]].<br />
<br />
Example:<br />
"port_weapon_type" = "WEAPON_BEAM_LASER";<br />
<br />
== roles ==<br />
Assigns which [[role]](s) the entity should have, that can correspond to one specific, exclusive use, or several.<br />
<br />
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]].<br />
<br />
'''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.<br />
<br />
Example:<br />
"roles" = "hunter(0.25) trader(2.0) pirate";<br />
<br />
or an exclusive role, simply:<br />
<br />
"roles" = "uniquely_named_role";<br />
<br />
This has the benefit of being the only ship to be selected when a [[Script.plist|script]] calls for the ''uniquely_named_role'' ship.<br />
<br />
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.<br />
<br />
Example:<br />
"roles" = "Gold";<br />
<br />
Some roles are used by the game engine to populate systems, detect and define properties. (see also the [[System Populator]])<br />
Such roles include 'thargoid', 'missile' and 'energybomb'.<br />
Externally used equipment also needs specific mention of role, for example EQ_*_MINE and EQ_*_MISSILE.<br />
<br />
== rotational_velocity ==<br />
May be applied to a sub-entity, like the following entry to the [[Shipdata.plist#subentities|subentity]] spines of the [[Weeviloid Hunter]].<br />
Takes the form of [[Quaternions|quaternions]]. The following example enables rotation around the Z-axis.<br />
<br />
Example:<br />
"rotational_velocity" = "0.707 0.0 0.0 0.707";<br />
<br />
<br />
An explaining example taken from the Oolite Bulletin board.<br />
<br />
The rotational velocity key is rotation per second. <br />
<br />
For instance, if you want to rotate once per 20 seconds around the Z axis:<br />
<br />
a = 360 ° / 20 = 18 °<br />
<br />
[x, y, z] = [0, 0, 1]<br />
<br />
sin a ˜ 0.30902<br />
<br />
cos a ˜ 0.95106<br />
<br />
Q = (0.95106, 0, 0, 0.30902)<br />
<br />
'''shipdata.plist entry:'''<br />
"rotational_velocity"="0.95106 0.0 0.0 0.30902";<br />
<br />
== scan_class ==<br />
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.<br />
* CLASS_BUOY - green/yellow on scanner, will rotate in idle state, does not masslock<br />
* CLASS_CARGO - white on scanner, can be scooped, does not masslock<br />
* CLASS_MILITARY - purple on scanner, better pilots, will not attack other military ships, flashes purple/magenta if hostile to player<br />
* CLASS_MISSILE - cyan on scanner, will not avoid collisions<br />
* 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<br />
* CLASS_ROCK - white on scanner, launched defense ships do not inherit scan class, does not masslock<br />
* CLASS_STATION - green on scanner, launched defense ships do not inherit scan class<br />
* CLASS_THARGOID - green/red on scanner, considered hostile to any non-thargoid ship<br />
* CLASS_NO_DRAW - invisible on scanner, cannot be targeted by missiles, does not masslock<br />
* CLASS_MINE - red/yellow on scanner, automatically set on mines launched by player to override existing scan class, does not masslock<br />
(This property was called "scanClass" before Oolite 1.74.)<br />
Scan classes marked as "does not masslock" will masslock the player anyway if they are hostile to the player (as condition will be Red)<br />
<br />
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.<br />
<br />
Example:<br />
"scan_class" = "CLASS_ROCK";<br />
<br />
==== Developer Note ====<br />
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!<br />
<br />
== scan_description ==<br />
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.<br />
<br />
"scan_description" = "Unclaimed rock";<br />
<br />
Added in Oolite 1.81<br />
<br />
== scanner_display_color1 ==<br />
Overrides the color that would normally be set by scanClass.<br />
<br />
Example:<br />
"scanner_display_color1" = "greenColor";<br />
<br />
== scanner_display_color2 ==<br />
Overrides the color that would normally be set by scanClass. If this is set, the ship will flash between the two colours.<br />
<br />
Example:<br />
"scanner_display_color2" = "redColor";<br />
<br />
== scanner_hostile_display_color1 ==<br />
(1.81 or later)<br />
<br />
Overrides the color that would normally be set by scanClass when the ship is hostile and targeting the player.<br />
<br />
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.<br />
<br />
Example:<br />
"scanner_hostile_display_color1" = "greenColor";<br />
<br />
== scanner_hostile_display_color2 ==<br />
(1.81 or later)<br />
<br />
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.<br />
<br />
Example:<br />
"scanner_hostile_display_color2" = "redColor";<br />
<br />
== scanner_range ==<br />
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.<br />
<br />
Example:<br />
"scanner_range" = "25600";<br />
<br />
== scoop_position ==<br />
Determines the XYZ point on the model from which cargo is scooped. (default is 0,0,0)<br />
<br />
Example:<br />
"scoop_position" = "0.0 -4.5 -23.0"<br />
<br />
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.<br />
<br />
== script ==<br />
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.<br />
<br />
== script_info ==<br />
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.<br><br />
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.<br />
<br />
A short overview about used [[OXP_scriptInfo|script_info keys in OXPs]].<br />
<br />
== script_actions ==<br />
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.<br />
<br />
Example:<br />
"script_actions" =<br />
(<br />
"testForEquipment: EQ_CLOAKING_DEVICE",<br />
{<br />
"conditions"<br />
(<br />
"foundEquipment_bool equal NO"<br />
)<br />
"do"<br />
(<br />
"awardEquipment: EQ_CLOAKING_DEVICE"<br />
)<br />
"else"<br />
(<br />
"awardCargo: 100 Gold"<br />
)<br />
}<br />
);<br />
<br />
== setup_actions ==<br />
Arranges a process that may be necessary for some objects, like ball turrets.<br />
<br />
Example:<br />
"setup_actions" =<br />
(<br />
"initialiseTurret"<br />
);<br />
<br />
<br />
== shaders ==<br />
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.<br />
<br />
== ship_name ==<br />
Added in 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.<br />
<br />
== ship_class_name ==<br />
Added in 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.<br />
<br />
== show_damage ==<br />
Added in 1.81. Whether to show sparks and other damage effects when this ship is hit.<br />
<br />
Defaults to on if energy recharge rate is greater than zero, off otherwise, for compatibility with previous hard-coded behaviour.<br />
<br />
== smooth ==<br />
Determines if the model will use glLightModel(GL_FLAT) or glLightModel(GL_SMOOTH).<br />
<br />
If true, then lighting effects will be interpolated across the polygons of the model, giving a more 'rounded' effect.<br />
<br />
Asteroids, Boulders and Splinters use this effect as do some other models.<br />
<br />
Example:<br />
"smooth" = yes;<br />
<br />
== spawn ==<br />
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.<br />
<br />
Example<br />
"spawn"<br />
{<br />
"facing_position" = "spu 0 0 0";<br />
"position" = "wpu 0 0 0.2";<br />
}<br />
<br />
<br />
== starboard_weapon_type ==<br />
(Oolite 1.77 or later)<br />
Assigns the ship's starboard laser. <br />
Any weapon type from the [[equipment.plist]] can be used (and WEAPON_NONE). <br />
<br />
While not essential, you should generally assign the same weapon to [[#port_weapon_type|port_weapon_type]].<br />
<br />
Example:<br />
"starboard_weapon_type" = "WEAPON_BEAM_LASER";<br />
<br />
== subentities ==<br />
An array of ''subentity definitions''. A ''subentity'' is an object attached to your ship. There are several types of subentity:<br />
* ''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.<br />
* ''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.<br />
* ''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'''.<br />
* ''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.<br />
<br />
=== New-style subentity definition ===<br />
Oolite 1.73 introduced a more flexible, dictionary-based way of specifying subentities. A new-style subentity is a dictionary using the following keys:<br />
{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"<br />
|+ Subentity definition properties<br />
! Name !! Type !! Description<br />
|-<br />
| '''type''' || string || One of: “'''standard'''”, “'''ball_turret'''”, “'''flasher'''”. If not specified, “standard” is assumed.<br />
|-<br />
| '''subentity_key''' || string || The key of a ''shipdata.plist'' entry. Required for '''standard''' and '''ball_turret''' subentities, ignored for flashers.<br />
|-<br />
| '''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).<br />
|-<br />
| '''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.<br />
|-<br />
| '''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.<br />
|}<br />
<br />
{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"<br />
|+ Subentity definition properties for dock subentities (1.77 or later)<br />
! Name !! Type !! Description<br />
|-<br />
| '''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.<br />
|-<br />
| '''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.<br />
|-<br />
| '''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.<br />
|-<br />
| '''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.<br />
|}<br />
See [[Multiple Docks]] for more information on dock subentities and stations with more than one dock in Oolite 1.77 or later.<br />
<br />
{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"<br />
|+ Subentity definition properties for ball turrets<br />
! Name !! Type !! Description<br />
|-<br />
| '''fire_rate''' || number || Interval between shots in seconds, for '''ball_turret''' subentities. Default: 0.5; minimum: 0.25.<br />
|-<br />
| '''weapon_range''' || number || Range for '''ball_turret''' subentities. Default: 6000; maximum 7500.<br />
|-<br />
| '''weapon_energy''' || number || Weapon energy for '''ball_turret''' subentities. Default: 25; maximum 100.<br />
|}<br />
<br />
{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"<br />
|+ Subentity definition properties for flashers<br />
! Name !! Type !! Description<br />
|-<br />
| '''color''' || [[Materials in Oolite#Colour specifiers|colour specifier]] || Single colour for a flasher. Ignored for non-flashers. Default value: '''redColor'''.<br />
|-<br />
| '''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”.<br />
|-<br />
| '''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.<br />
|-<br />
| '''initially_on''' || boolean || Specifiers whether a flasher is turned on when created. Ignored for non-flashers. Default: yes.<br />
|-<br />
| '''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.<br />
|-<br />
| '''size''' || positive number || Diameter of a flasher in metres. Ignored for non-flashers. Default: 8. (Why 8? I don’t remember.)<br />
|-<br />
| '''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.<br />
|-<br />
|}<br />
<br />
=== Old-style subentity definition ===<br />
Prior to Oolite 1.73, this was the the only way to specify a subentity.<br />
<br />
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:<br />
<br />
==== Flashers ====<br />
For a flasher, the entry takes the form:<br />
*FLASHER* x y z hue frequency phase size<br />
''*FLASHER*'' must be precisely the string “*FLASHER*”, in capitals.<br />
<br />
''x'', ''y'' and ''z'' form the '''position'''.<br />
<br />
''hue'' specifies the [http://en.wikipedia.org/wiki/HSL_and_HSV HSV] hue component (in degrees) of '''color'''. Saturation and value are always 1.<br />
<br />
'''frequency''', '''phase''' and '''size''' are the same as in the new-style format.<br />
<br />
'''initially_on''' is false.<br />
<br />
==== Other subentities ====<br />
For a non-flasher, the entry takes the form:<br />
key x y z qw qx qy qz<br />
''key'' corresponds to '''subentity_key'''.<br />
<br />
''x'', ''y'' and ''z'' form the '''position'''.<br />
<br />
''qw'', ''qx'', ''qy'' and ''qz'' form the '''orientation'''.<br />
<br />
'''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.<br />
<br />
'''is_dock''' is implied by having the string “dock” (in lowercase) in the ''key''.<br />
<br />
== sun_glare_filter ==<br />
<br />
Added in Oolite 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)<br />
<br />
"sun_glare_filter" = 0.3;<br />
<br />
== track_contacts ==<br />
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.<br />
<br />
Example:<br />
"track_contacts" = yes;<br />
<br />
== throw_sparks ==<br />
Each new ship should start in seemingly good operating condition, unless specifically told not to. (Added with oolite 1.73, false by default)<br />
<br />
Example:<br />
"throw_sparks" = yes;<br />
<br />
== thrust ==<br />
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). <br />
<br />
Example:<br />
"thrust" = "25"<br />
<br />
== unpiloted ==<br />
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.<br><br />
It will not add a pilot when set to false, but will remove any existing pilot when set to true.<br />
commsMessages can only be broadcasted by piloted ships. Ships are by default piloted. cargo , rocks, missiles etc. are not piloted by default.<br />
<br />
Example:<br />
"unpiloted" = yes;<br />
<br />
== view_position_.. ==<br />
Sets the ship's 4 point-of-view positions in XYZ relative to the model.<br />
<br />
Example:<br />
"view_position_aft" = "0.0 5.0 -20.0";<br />
"view_position_forward" = "0.0 1.9375 5.0";<br />
"view_position_port" = "-11.85 2.825 -3.5";<br />
"view_position_starboard" = "11.85 2.825 -3.5";<br />
<br />
<br />
== weapon_energy ==<br />
This setting works differently depending on the type of entity it's used for:<br><br />
<br />
<b>Missiles.</b> Changes the damage inflicted by the missile. Any value accepted.<br />
<br />
<b>NPC ships.</b> 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.<br><br />
<i><b>N.B.</b> It does not have any effect on player ships.</i><br />
<br />
<b>turrets.</b> Unused for turrets. Set the turret weapon_energy in its [[Shipdata.plist#New-style_subentity_definition|subEntity directory]].<br />
<br />
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<br />
<br />
Example:<br />
"weapon_energy" = "17";<br />
<br />
== weapon_facings ==<br />
(1.77 or later only)<br />
What weapon mounts are available on the ship. This is a bit-mask, so pick the mounts and add the numbers:<br />
<br />
1 - Forward<br /><br />
2 - Aft<br /><br />
4 - Port<br /><br />
8 - Starboard<br /><br />
<br />
Example: <br /><br />
Fore and aft weapon mounts only.<br />
<key>weapon_facings</key><br />
<integer>3</integer><br />
<br />
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.<br />
<br />
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.<br />
<br />
== weapon_mount_mode ==<br />
(1.83 or later only)<br />
<br />
This controls how multiple weapon mount points work. It has three possible values:<br />
* '''"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.<br />
* '''"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)<br />
* '''"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)<br />
<br />
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.<br />
<br />
== weapon_offset ==<br />
Removed after version 1.65 (it was used to change the offsetpoint of a plasma cannon.)<br />
<br />
== weapon_position_.. ==<br />
Plots the 'gunmouth' points of the model's 4 potential lasers.<br />
<br />
In 1.82 and earlier, and in 1.83 and later in the "single" <code>weapon_mount_mode</code>, these are vector expressions.<br />
<br />
Example:<br />
"weapon_position_aft" = "0.0 -5.0 -20.0";<br />
"weapon_position_forward" = "0.0 0.0417 16.6667";<br />
"weapon_position_port" = "-13.75 -2.0625 -1.875";<br />
"weapon_position_starboard" = "13.75 -2.0625 -1.875";<br />
<br />
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:<br />
"weapon_position_forward" = ( "0.0 3.0 32.0" , "-15.0 0.0 32.0" , "15.0 0.0 32.0" )<br />
<br />
= Station keys=<br />
The following keys are only used by stations or carriers.<br />
<br />
== allegiance ==<br />
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.<br />
<br />
Example:<br />
allegiance = "neutral";<br />
<br />
== allows_auto_docking ==<br />
When set false for a station, this station will not allow the use of a docking computer. Default value in "yes". (Planned for Oolite 1.75)<br />
<br />
Example:<br />
allows_auto_docking = "no";<br />
<br />
== allows_fast_docking ==<br />
When set true for a station, this station will allow fast docking with the docking computer. Default value in "no". (Planned for Oolite 1.75)<br />
<br />
Example:<br />
allows_fast_docking = "yes";<br />
<br />
== defense_ship ==<br />
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]]<br />
<br />
Example:<br />
defense_ship" = "my_defender";<br />
<br />
== defense_ship_role ==<br />
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"<br />
<br />
Example:<br />
"defense_ship_role" = " carrier_defenders";<br />
<br />
== equipment_price_factor ==<br />
Equipment price mask for dockables.<br />
<br />
Example:<br />
"equipment_price_factor" = "4.5";<br />
<br />
== equivalent_tech_level ==<br />
Sets shipyard tech level for dockables, different to the local system tech_level. Default value is the system tech_level.<br />
<br />
Example:<br />
"equivalent_tech_level" = 1;<br />
<br />
== has_npc_traffic ==<br />
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).<br />
<br />
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).<br />
<br />
Example:<br />
"has_npc_traffic" = yes;<br />
<br />
== has_patrol_ships ==<br />
Determines if a station launches periodic patrol ships. Default is "no". Main stations always have patrol ships. (Planned for Oolite 1.75)<br />
<br />
Example:<br />
"has_patrol_ships" = yes;<br />
<br />
== has_shipyard ==<br />
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".)<br />
<br />
Example:<br />
"has_shipyard" = "0.75";<br />
<br />
or<br />
<br />
"has_shipyard" = (<br />
"systemGovernment_number morethan 3",<br />
"systemEconomy_number lessthan 4"<br />
)<br />
<br />
== interstellar_undocking ==<br />
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". (Planned for Oolite 1.75)<br />
<br />
Example:<br />
interstellar_undocking = "yes";<br />
<br />
==is_carrier==<br />
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".)<br />
<br />
Example:<br />
"is_carrier" = yes;<br />
<br />
== market ==<br />
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.<br />
<br />
Example:<br />
"market" = "none";<br />
<br />
== market_broadcast ==<br />
In 1.81 or later, 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.<br />
<br />
"market_broadcast" = no;<br />
<br />
== market_capacity ==<br />
In 1.81 or later, 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.<br />
<br />
"market_capacity" = 31;<br />
<br />
== market_definition ==<br />
In 1.81 or later, 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.<br />
<br />
"market_definition" = (<br />
{<br />
// export cheap clothes<br />
"type" = "class";<br />
"name" = "oolite-wearable";<br />
"price_multiplier" = 0.8;<br />
"price_randomiser" = 0.1;<br />
"quantity_multiplier" = 3.5;<br />
"quantity_randomiser" = 3.0;<br />
}, <br />
{<br />
// not really interested in other goods<br />
"type" = "default";<br />
"price_multiplier" = 0.55;<br />
"price_randomiser" = 0.25;<br />
"quantity_multiplier" = 0.0;<br />
"capacity" = 3;<br />
}<br />
);<br />
<br />
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.<br />
<br />
A blank array<br />
"market_definition" = ();<br />
will give a market identical to the primary system market.<br />
<br />
If this key is omitted, the station will have no market. This is roughly equivalent to<br />
"market_definition = (<br />
{<br />
"type" = "default";<br />
"price_multiplier" = 0;<br />
"quantity_multiplier" = 0;<br />
"capacity" = 0;<br />
}<br />
);<br />
<br />
== market_monitored ==<br />
In Oolite 1.81 and later, 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.<br />
<br />
market_monitored = yes;<br />
<br />
== market_script ==<br />
In Oolite 1.81 and later, allows a [[Oolite_Market_Scripts|market script]] to be used to modify trade prices. This overrides market_definition, if it is present.<br />
<br />
market_script = "myoxp_marketchanges.js";<br />
<br />
== max_defense_ships ==<br />
Designates how many ships a dockable entity (station, carrier) can launch in defense. Default value is 3. See also [[Station Ships]]<br />
<br />
Example:<br />
"max_defense_ships" = "10";<br />
<br />
== max_police ==<br />
Designates how many police or patrol ships a dockable entity (station, carrier) can launch. Default value is 8. See also [[Station Ships]]<br />
<br />
Example:<br />
"max_police " = "10";<br />
<br />
== max_scavengers ==<br />
Designates how many scavengers or miners a dockable entity (station, carrier) can launch. Default value is 3. See also [[Station Ships]]<br />
<br />
Example:<br />
"max_scavengers" = "10";<br />
<br />
== port_dimensions ==<br />
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.<br />
<br />
Example:<br />
"port_dimensions" = "65x30x500";<br />
<br />
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)<br><br />
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.<br />
<br />
== port_radius ==<br />
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.<br />
<br />
Example:<br />
"port_radius" = "500";<br />
<br />
== requires_docking_clearance ==<br />
Sets the requirement for docking clearance. Default is "no". See also [[Oolite_Docking_Clearance_Protocol_%28v1.72_or_later%29|DockingClearance]]<br />
<br />
Example:<br />
"requires_docking_clearance" = yes;<br />
<br />
==rotating==<br />
Given to a station when rotation is desired. Default is "no".<br />
<br />
Example:<br />
"rotating" = yes;<br />
<br />
== station_roll ==<br />
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. (Key is added in Oolite 1.74.2)<br />
<br />
'''Note''': unlike the other turn rate properties, for historical reasons <code>station_roll</code> is measured in right-angles/second, ''not'' radians/second.<br />
<br />
Example:<br />
"station_roll" = "-1.5"<br />
<br />
==tunnel_corners==<br />
Defines the number of corners in the docking tunnel. Ranges from 4 to 128. Default is "4". (Key is added in Oolite 1.75)<br />
<br />
Example:<br />
"tunnel_corners" = 6;<br />
<br />
==tunnel_start_angle==<br />
Defines the position of the first corner of the docking tunnel in degrees. 0 means the first corner is straight up. Default is "45". (Key is added in Oolite 1.75)<br />
<br />
Example:<br />
"tunnel_start_angle" = 0;<br />
<br />
==tunnel_aspect_ratio==<br />
Defines the proportion of the tunnel’s width to its height. Default is "2.67".<br />
<br />
Example:<br />
"tunnel_aspect_ratio" = 1;<br />
<br />
--------------------------------------------------------------------------------<br />
[[Category:Oolite]]<br />
[[Category:Oolite scripting]]</div>Cimhttps://wiki.alioth.net/index.php?title=Shipdata.plist&diff=48480Shipdata.plist2015-08-23T20:06:47Z<p>Cim: /* weapon_mount_mode */ 1.83 property</p>
<hr />
<div>'''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:<br />
<br />
<br />
= Ship keys=<br />
The following keys are used by all ships<br />
==accuracy==<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Example:<br />
"accuracy" = 8.3;<br />
<br />
== aft_eject_position ==<br />
Determines the XYZ point on the model from which cargo is ejected.<br />
<br />
Example:<br />
"aft_eject_position" = "0.0 -4.5 -23.0";<br />
<br />
== aft_weapon_type ==<br />
Assigns the ship's aft laser. <br />
Any weapon type from the [[equipment.plist]] can be used (and WEAPON_NONE). <br />
<br />
Example:<br />
"aft_weapon_type" = "WEAPON_BEAM_LASER";<br />
<br />
== ai_type ==<br />
Assigns an AI to the entity. This may be a previously existing AI, or one custom made for the occasion.<br />
<br />
Example:<br />
"ai_type" = "pirateAI.plist";<br />
<br />
== auto_ai ==<br />
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.<br />
Example:<br />
"auto_ai" = yes;<br />
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.<br />
<br />
== auto_weapons ==<br />
Added in 1.79<br />
<br />
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.<br />
<br />
Example:<br />
"auto_weapons" = yes;<br />
<br />
== beacon ==<br />
A special feature for beacons and navigation aids.<br />
The string can be anything - the first letter is what's displayed in the advanced space compass.<br />
<br />
Example: <br />
"beacon" = "X";<br />
<br />
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.<br />
<br />
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].<br><br />
Example in shipdata:<br />
"beacon" = "fuelStation_location";<br />
Example in descriptions.plist<br />
"fuelStation_location" = (1, 2, -3, 2, -3, -4, 3, -4, 3, 4, -3, 4, -3, 3, 2, 3, 2, -3, 1, -3 );<br />
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.<br />
<br />
== beacon_label ==<br />
(1.79 or later)<br />
<br />
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<br />
"beacon_label" = "%H Station"; // Lave Station, Diso Station, etc.<br />
<br />
== bounty ==<br />
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.<br />
<br />
Example:<br />
"bounty" = 50;<br />
<br />
== cargo_carried ==<br />
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.<br />
<br />
Example:<br />
"cargo_carried" = "Gold";<br />
<br />
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.<br><br />
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.)<br><br />
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)<br />
<br />
'''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.<br />
<br />
== [[cargo_type]] ==<br />
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.)<br><br />
<br />
Example:<br />
"cargo_type" = "CARGO_RANDOM";<br />
<br />
Will create random cargo, often based on availability in the system. When you want fixed cargo you can use:<br />
<br />
Example:<br />
"cargo_type" = "CARGO_CARRIED";<br />
"cargo_carried" = "4 Gold";<br />
<br />
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]].<br />
<br />
Example:<br />
"cargo_type" = "CARGO_NOT_CARGO";<br />
"cargo_carried" = "Computers";<br />
<br />
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.<br><br />
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.<br />
<br />
== cloak_automatic ==<br />
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) Key added with Oolite 1.75<br />
<br />
Example:<br />
"cloak_automatic" = no;<br />
<br />
== cloak_passive ==<br />
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) <br />
<br />
Example:<br />
"cloak_passive" = yes;<br />
<br />
==conditions==<br />
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.<br />
<br />
Example:<br />
"conditions" = (<br />
"systemGovernment_number equal 3",<br />
"systemEconomy_number lessthan 4"<br />
);<br />
<br />
==condition_script==<br />
''Available from Oolite 1.77 onwards''<br />
<br />
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.<br />
<br />
Example:<br />
"condition_script" = "myoxp_conditions.js";<br />
<br />
== counts_as_kill ==<br />
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. Key is added with Oolite 1.75<br />
<br />
Example:<br />
"counts_as_kill" = no;<br />
<br />
== custom_views==<br />
Will add the ability to display custom POVs of the player ship, in game toggled by pressing '''v'''. <br />
<br />
This is an array with any number of entries, one for each view, each with:<br />
*a '''view_description''' - giving a textual description of the view. <br />
*a '''view_position''' - relative to the origin of the ship model. <br />
*a '''view_orientation''' - this is a [[Quaternions|quaternion]] expressing a rotation from directly forwards. <br />
*a '''weapon_facing''' - FORWARD, AFT, PORT or STARBOARD. The weapon that will fire when that view is selected.<br />
<br />
The view_position is best chosen by selecting a facet, line or point in Wings and copying down the coordinates. <br />
<br />
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: <br />
<br />
W = the cosine of half the angle rotated about the axis xyz<br /><br />
X = the sine of half the angle rotated about xyz, multiplied by x<br /><br />
Y = the sine of half the angle rotated about xyz, multiplied by y <br /><br />
Z = the sine of half the angle rotated about xyz, multiplied by z <br /><br />
<br />
Four decimal places are probably enough accuracy for these values.<br />
<br />
Example:<br />
custom_views =<br />
(<br />
{<br />
view_description = "Front View";<br />
view_orientation = "0.0 0.0 1.0 0.0";<br />
view_position = "0.0 30.0 200.0";<br />
weapon_facing = "FORWARD";<br />
}<br />
);<br />
<br />
== death_actions ==<br />
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.<br />
<br />
Example:<br />
"death_actions" = ("spawn: explosive_shrapnel 1");<br />
<br />
== debris_role ==<br />
Specifies the kind of debris an asteroid or boulder generates. When not defined they default to generating 'ships' with role "boulder" or "splinter". (Key added with Oolite 1.74)<br />
<br />
Example:<br />
"debris_role" = "my_boulder_foo";<br />
<br />
== density ==<br />
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.<br />
<br />
Ship's mass does not affect its flight under the non-inertial engines - see [[#thrust|thrust]]. It does affect:<br />
* changes in momentum, and damage done, in a collision<br />
* 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)<br />
* the length of time a witchspace wormhole opened by this ship will remain open, and the radius of that wormhole.<br />
<br />
Example:<br />
"density" = 1.5;<br />
<br />
== display_name ==<br />
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.<br />
<br />
Example:<br />
"display_name" = "ExampleShip Mark IX";<br />
<br />
== energy_recharge_rate ==<br />
The rate at which energy is replenished. Stations are at 100, Adders at 2. (Default value: 1)<br />
<br />
Example:<br />
"energy_recharge_rate" = "3.5";<br />
<br />
== escape_pod_model ==<br />
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).<br />
<br />
Example:<br />
"escape_pod_model" = "custom_pod";<br />
<br />
== escorts ==<br />
Determines how many escorts an NPC shall have. Maximum is 16.<br />
<br />
Example:<br />
"escorts" = 4;<br />
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.<br><br />
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. <br />
<br />
== escort_role ==<br />
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.)<br />
<br />
Example:<br />
"escort_role" = "my_custom_escort_role";<br />
Escort ships will use the escortAI.plist unless "auto_ai" is set to false.<br />
<br />
<br />
==escort_roles==<br />
''Available from Oolite 1.79 onwards''<br />
<br />
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.<br />
<br />
escort_roles = (<br />
{ role = "escort"; min = -2; max = 2; },<br />
{ role = "escort-medium"; min = 0; max = 4; },<br />
{ role = "escort-heavy"; min = -4; max = 2; },<br />
{ role = ""; min = 0; max = 2; } // spare slots for wandering escorts<br />
);<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
== escort_ship ==<br />
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.)<br />
<br />
Example:<br />
"escort_ship" = "cobramk1";<br />
Escort ships will use the escortAI.plist unless "auto_ai" is set to false.<br />
<br />
In Oolite 1.77 and later it is also possible to use <code>"escort_role" = "[cobramk1]"</code><br />
<br />
== exhaust ==<br />
The XYZ position(s) of exhaust plume(s), and the XYZ of the plume shape, ergo<br />
<br />
x y z width height length<br />
<br />
'''x y z''' is the position relative to the origin of the main model. <br />
<br />
'''width''' in meters, how far a plume extends on x axis, on each side of plume position. (x radius)<br />
<br />
'''height''' in meters, how far a plume extends on y axis, above and below of plume position. (y radius)<br />
<br />
'''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)<br />
<br />
<br />
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)<br />
<br />
Example:<br />
"exhaust" = (<br />
"5 0.0 -25 3.0 2.0 10.0",<br />
"-5 0.0 -25 3.0 2.0 10.0"<br />
);<br />
<br />
== explosion_type ==<br />
In Oolite 1.81 or later, a list of [[explosions.plist]] entries describing how the ship explodes if destroyed.<br />
<br />
Example:<br />
"explosion_type" = ("oolite-default-asteroid-explosion");<br />
<br />
== extra_cargo ==<br />
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.<br />
<br />
Example:<br />
"extra_cargo" = 25;<br />
<br />
== forward_weapon_type ==<br />
Assigns the ship's forward laser. <br />
Any weapon type from the [[equipment.plist]] can be used.<br> e.g.: WEAPON_PULSE_LASER, WEAPON_BEAM_LASER, WEAPON_MILITARY_LASER, WEAPON_MINING_LASER, WEAPON_PLASMA_CANNON, WEAPON_THARGOID_LASER and WEAPON_NONE. <br />
<br />
Example:<br />
"forward_weapon_type" = "WEAPON_BEAM_LASER";<br />
<br />
== frangible ==<br />
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. <br />
If set to false, the object plus subentities will be regarded as a single object.<br />
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.<br />
<br />
Example:<br />
"frangible" = no;<br />
<br />
== fragment_chance ==<br />
Determines if a ship breaks apart into fragments and generates parts with role "wreckage". By chance factor, or true/false. Default is 90% chance.<br />
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)<br />
<br />
Example:<br />
"fragment_chance" = no;<br />
<br />
== fuel ==<br />
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)<br />
<br />
Example:<br />
"fuel" = 70;<br />
<br />
== has_cloaking_device ==<br />
Determines if a ship has a cloacking device installed. By chance factor, or true/false.<br />
<br />
Example:<br />
"has_cloaking_device" = 0.5;<br />
<br />
== has_ecm ==<br />
Determines if a ship has the E.C.M system installed. By chance factor, or true/false.<br />
<br />
Example:<br />
"has_ecm" = 0.5;<br />
or<br />
"has_ecm" = no;<br />
<br />
== has_energy_bomb ==<br />
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.<br>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.<br />
<br />
Example: <br />
"has_energy_bomb" = yes;<br />
<br />
== has_escape_pod ==<br />
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.<br />
<br />
Examples:<br />
has_escape_pod = no;<br />
has_escape_pod = 0.75;<br />
has_escape_pod = 3;<br />
<br />
== has_fuel_injection ==<br />
Determines if a ship has the witchdrive fuel injector.<br />
<br />
Example:<br />
"has_fuel_injection" = 0.99;<br />
<br />
==has_military_jammer==<br />
Determines if a ship has a military jammer. Ships equipped with this item become invisible on the radar. <br />
Example:<br />
"has_military_jammer" = 0.75;<br />
<br />
==has_military_scanner_filter==<br />
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. <br />
Example:<br />
"has_military_scanner_filter" = 0.50;<br />
<br />
== has_scoop ==<br />
Determines if a ship has a fuel/cargo scoop.<br />
<br />
Example:<br />
"has_scoop" = no;<br />
<br />
== has_scoop_message ==<br />
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)<br />
<br />
Example:<br />
"has_scoop_message" = no;<br />
<br />
== has_shield_booster==<br />
Determines if a ship has the shield booster. (enlarges max energy with 256)<br />
<br />
Example:<br />
"has_shield_booster" = 0.80;<br />
<br />
== has_shield_enhancer ==<br />
Determines if a ship has the coveted shield enhancer. (enlarges max energy with 256 and raises energy recharge rate with 50%)<br />
<br />
Example:<br />
"has_shield_enhancer" = 0.45;<br />
<br />
== heat_insulation ==<br />
This real number gives the amount of heat insulation of a ship. Default is 1.0 Only for NPC ships. Playes ships can have the equipment EQ_HEAT_SHIELDING with gives the player than a heat_insulation of 2.0<br />
<br />
Example:<br />
"heat_insulation" = "2.0";<br />
<br />
== hud ==<br />
Used for a playership, to assign another HUD than the default one.<br />
<br />
Example:<br />
"hud" = "specialhud.plist";<br />
<br />
== hyperspace_motor ==<br />
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)<br />
<br />
Examples:<br />
"hyperspace_motor" = no;<br />
<br />
hyperspace_motor=NO;<br />
<br />
== hyperspace_motor_spin_time ==<br />
Used to modify jump countdown time. Default = 15.<br />
<br />
Examples:<br />
"hyperspace_motor_spin_time" = "15";<br />
<br />
==injector_burn_rate==<br />
The default fuel burn rate of injectors on this ship, in deci-LY per second. The default is 0.25.<br />
<br />
"injector_burn_rate" = 0.25;<br />
<br />
Added in Oolite 1.81<br />
<br />
==injector_speed_factor==<br />
The multiplier applied to the ship's maximum speed when it is using injectors. The default is 7.<br />
<br />
"injector_speed_factor" = 7;<br />
<br />
Added in Oolite 1.81<br />
<br />
==is_external_dependency==<br />
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.<br>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.<br />
<br />
Example:<br />
"is_external_dependency" = yes;<br />
<br />
==is_submunition==<br />
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.<br />
<br />
Example:<br />
"is_submunition" = yes;<br />
<br />
==is_template==<br />
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.<br />
<br />
Example:<br />
"is_template" = yes;<br />
<br />
== laser_color ==<br />
Determines a ship's laser colour.<br />
<br />
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.<br />
<br />
Example:<br />
"laser_color" = "cyanColor"<br />
<br />
<br />
== launch_actions ==<br />
Triggers a script on the entity just after setup, also when called by spawn and addShip methods.<br />
Can be used to change to a custom AI, when a ship is generated by standard role. <br />
[[Shipdata.plist#script_actions|script_actions]]<br />
<br />
Example:<br />
"role = trader";<br />
"launch_actions" = (<br />
"setAITo: pirateAI.plist"<br />
);<br />
<br />
<br />
== like_ship ==<br />
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.<br />
<br />
Works well together with the [[#is_template|is_template]]-key.<br />
<br />
Example:<br />
"my_ship" = {<br />
"like_ship" = "adder";<br />
"max_flight_speed" = "700";<br />
"name" = "Freak Turbo Adder";<br />
},<br />
<br />
== likely_cargo ==<br />
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.<br />
<br />
Example:<br />
"likely_cargo" = "2";<br />
<br />
== materials ==<br />
See [[Materials in Oolite]].<br />
<br />
<br />
== max_cargo ==<br />
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.<br />
<br />
Example:<br />
"max_cargo" = "5";<br />
<br />
== max_energy ==<br />
Sets the ship's energy value. (Default value: 200)<br />
<br />
Example:<br />
"max_energy" = "300";<br />
<br />
<br />
== max_flight_pitch ==<br />
Sets pitch factor. Will usually range from a sluggish 0.6 to a very sensitive 3.0<br />
<br />
Example:<br />
"max_flight_pitch" = "2.2";<br />
<br />
<br />
== max_flight_roll ==<br />
Sets roll factor. Will usually range from 0.8 to 4.6.<br />
<br />
Example:<br />
"max_flight_roll" = "4.2";<br />
<br />
<br />
== max_flight_speed ==<br />
Sets the model's top speed. Interceptors fly at 520 (0.52 LM), Shuttles at 80.<br />
<br />
Example:<br />
"max_flight_speed" = "320";<br />
<br />
== max_flight_yaw ==<br />
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<br />
<br />
Example:<br />
"max_flight_yaw" = "2.2";<br />
<br />
== max_missiles ==<br />
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.<br />
<br />
Example:<br />
"max_missiles" = "1";<br />
<br />
== missile_launch_position ==<br />
Determines the XYZ point on the model from which a missile is launched.<br />
<br />
Example:<br />
"missile_launch_position" = "0.0 -2.25 10.0";<br />
<br />
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)<br><br />
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.<br />
<br />
== missile_load_time ==<br />
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.<br />
<br />
Example:<br />
"missile_load_time" = "2.1";<br />
<br />
<br />
== missiles ==<br />
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.<br />
<br />
Example:<br />
"missiles" = "0";<br />
<br />
== missile_role ==<br />
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.<br />
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. <br />
<br />
To assign a specific missile type to a newly bought player ship, its dependancies must be defined inside [[shipyard.plist]].<br />
<br />
Example: <br />
"missile_role" = "EQ_THARGON";<br />
<br />
== model ==<br />
Assigns the entity's corresponding '''.dat''' file that will be found with the exact same name in the ''Models'' folder.<br />
<br />
Example:<br />
"model" = "example_ship.dat";<br />
<br />
== model_scale_factor ==<br />
1.81 or later only.<br />
<br />
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.<br />
<br />
Player ships will also have their internal and external view positions multiplied by the scale factor.<br />
<br />
model_scale_factors on subentities will be ignored - the value for the main entity will be used instead.<br />
<br />
Example:<br />
"model_scale_factor" = 2.0;<br />
<br />
== name ==<br />
States the model's name as it will be known to the ID computer.<br />
<br />
Example:<br />
"name" = "ExampleShip Mark IX";<br />
<br />
== no_boulders ==<br />
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.<br />
<br />
Example:<br />
"no_boulders" = yes;<br />
<br />
== pilot ==<br />
Gives the ship a predefined pilot, defined in [[characters.plist]]. Can eject in pod, if available, and be captured.<BR><br />
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.<br />
<br />
Example:<br />
"pilot" = "constrictor-mission-thief";<br />
<br />
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)<br />
<br />
== port_weapon_type ==<br />
(Oolite 1.77 or later)<br />
Assigns the ship's port laser. <br />
Any weapon type from the [[equipment.plist]] can be used (and WEAPON_NONE). <br />
<br />
While not essential, you should generally assign the same weapon to [[#starboard_weapon_type|starboard_weapon_type]].<br />
<br />
Example:<br />
"port_weapon_type" = "WEAPON_BEAM_LASER";<br />
<br />
== roles ==<br />
Assigns which [[role]](s) the entity should have, that can correspond to one specific, exclusive use, or several.<br />
<br />
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]].<br />
<br />
'''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.<br />
<br />
Example:<br />
"roles" = "hunter(0.25) trader(2.0) pirate";<br />
<br />
or an exclusive role, simply:<br />
<br />
"roles" = "uniquely_named_role";<br />
<br />
This has the benefit of being the only ship to be selected when a [[Script.plist|script]] calls for the ''uniquely_named_role'' ship.<br />
<br />
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.<br />
<br />
Example:<br />
"roles" = "Gold";<br />
<br />
Some roles are used by the game engine to populate systems, detect and define properties. (see also the [[System Populator]])<br />
Such roles include 'thargoid', 'missile' and 'energybomb'.<br />
Externally used equipment also needs specific mention of role, for example EQ_*_MINE and EQ_*_MISSILE.<br />
<br />
== rotational_velocity ==<br />
May be applied to a sub-entity, like the following entry to the [[Shipdata.plist#subentities|subentity]] spines of the [[Weeviloid Hunter]].<br />
Takes the form of [[Quaternions|quaternions]]. The following example enables rotation around the Z-axis.<br />
<br />
Example:<br />
"rotational_velocity" = "0.707 0.0 0.0 0.707";<br />
<br />
<br />
An explaining example taken from the Oolite Bulletin board.<br />
<br />
The rotational velocity key is rotation per second. <br />
<br />
For instance, if you want to rotate once per 20 seconds around the Z axis:<br />
<br />
a = 360 ° / 20 = 18 °<br />
<br />
[x, y, z] = [0, 0, 1]<br />
<br />
sin a ˜ 0.30902<br />
<br />
cos a ˜ 0.95106<br />
<br />
Q = (0.95106, 0, 0, 0.30902)<br />
<br />
'''shipdata.plist entry:'''<br />
"rotational_velocity"="0.95106 0.0 0.0 0.30902";<br />
<br />
== scan_class ==<br />
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.<br />
* CLASS_BUOY - green/yellow on scanner, will rotate in idle state, does not masslock<br />
* CLASS_CARGO - white on scanner, can be scooped, does not masslock<br />
* CLASS_MILITARY - purple on scanner, better pilots, will not attack other military ships, flashes purple/magenta if hostile to player<br />
* CLASS_MISSILE - cyan on scanner, will not avoid collisions<br />
* 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<br />
* CLASS_ROCK - white on scanner, launched defense ships do not inherit scan class, does not masslock<br />
* CLASS_STATION - green on scanner, launched defense ships do not inherit scan class<br />
* CLASS_THARGOID - green/red on scanner, considered hostile to any non-thargoid ship<br />
* CLASS_NO_DRAW - invisible on scanner, cannot be targeted by missiles, does not masslock<br />
* CLASS_MINE - red/yellow on scanner, automatically set on mines launched by player to override existing scan class, does not masslock<br />
(This property was called "scanClass" before Oolite 1.74.)<br />
Scan classes marked as "does not masslock" will masslock the player anyway if they are hostile to the player (as condition will be Red)<br />
<br />
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.<br />
<br />
Example:<br />
"scan_class" = "CLASS_ROCK";<br />
<br />
==== Developer Note ====<br />
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!<br />
<br />
== scan_description ==<br />
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.<br />
<br />
"scan_description" = "Unclaimed rock";<br />
<br />
Added in Oolite 1.81<br />
<br />
== scanner_display_color1 ==<br />
Overrides the color that would normally be set by scanClass.<br />
<br />
Example:<br />
"scanner_display_color1" = "greenColor";<br />
<br />
== scanner_display_color2 ==<br />
Overrides the color that would normally be set by scanClass. If this is set, the ship will flash between the two colours.<br />
<br />
Example:<br />
"scanner_display_color2" = "redColor";<br />
<br />
== scanner_hostile_display_color1 ==<br />
(1.81 or later)<br />
<br />
Overrides the color that would normally be set by scanClass when the ship is hostile and targeting the player.<br />
<br />
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.<br />
<br />
Example:<br />
"scanner_hostile_display_color1" = "greenColor";<br />
<br />
== scanner_hostile_display_color2 ==<br />
(1.81 or later)<br />
<br />
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.<br />
<br />
Example:<br />
"scanner_hostile_display_color2" = "redColor";<br />
<br />
== scanner_range ==<br />
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.<br />
<br />
Example:<br />
"scanner_range" = "25600";<br />
<br />
== scoop_position ==<br />
Determines the XYZ point on the model from which cargo is scooped. (default is 0,0,0)<br />
<br />
Example:<br />
"scoop_position" = "0.0 -4.5 -23.0"<br />
<br />
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.<br />
<br />
== script ==<br />
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.<br />
<br />
== script_info ==<br />
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.<br><br />
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.<br />
<br />
A short overview about used [[OXP_scriptInfo|script_info keys in OXPs]].<br />
<br />
== script_actions ==<br />
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.<br />
<br />
Example:<br />
"script_actions" =<br />
(<br />
"testForEquipment: EQ_CLOAKING_DEVICE",<br />
{<br />
"conditions"<br />
(<br />
"foundEquipment_bool equal NO"<br />
)<br />
"do"<br />
(<br />
"awardEquipment: EQ_CLOAKING_DEVICE"<br />
)<br />
"else"<br />
(<br />
"awardCargo: 100 Gold"<br />
)<br />
}<br />
);<br />
<br />
== setup_actions ==<br />
Arranges a process that may be necessary for some objects, like ball turrets.<br />
<br />
Example:<br />
"setup_actions" =<br />
(<br />
"initialiseTurret"<br />
);<br />
<br />
<br />
== shaders ==<br />
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.<br />
<br />
== ship_name ==<br />
Added in 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.<br />
<br />
== ship_class_name ==<br />
Added in 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.<br />
<br />
== show_damage ==<br />
Added in 1.81. Whether to show sparks and other damage effects when this ship is hit.<br />
<br />
Defaults to on if energy recharge rate is greater than zero, off otherwise, for compatibility with previous hard-coded behaviour.<br />
<br />
== smooth ==<br />
Determines if the model will use glLightModel(GL_FLAT) or glLightModel(GL_SMOOTH).<br />
<br />
If true, then lighting effects will be interpolated across the polygons of the model, giving a more 'rounded' effect.<br />
<br />
Asteroids, Boulders and Splinters use this effect as do some other models.<br />
<br />
Example:<br />
"smooth" = yes;<br />
<br />
== spawn ==<br />
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.<br />
<br />
Example<br />
"spawn"<br />
{<br />
"facing_position" = "spu 0 0 0";<br />
"position" = "wpu 0 0 0.2";<br />
}<br />
<br />
<br />
== starboard_weapon_type ==<br />
(Oolite 1.77 or later)<br />
Assigns the ship's starboard laser. <br />
Any weapon type from the [[equipment.plist]] can be used (and WEAPON_NONE). <br />
<br />
While not essential, you should generally assign the same weapon to [[#port_weapon_type|port_weapon_type]].<br />
<br />
Example:<br />
"starboard_weapon_type" = "WEAPON_BEAM_LASER";<br />
<br />
== subentities ==<br />
An array of ''subentity definitions''. A ''subentity'' is an object attached to your ship. There are several types of subentity:<br />
* ''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.<br />
* ''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.<br />
* ''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'''.<br />
* ''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.<br />
<br />
=== New-style subentity definition ===<br />
Oolite 1.73 introduced a more flexible, dictionary-based way of specifying subentities. A new-style subentity is a dictionary using the following keys:<br />
{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"<br />
|+ Subentity definition properties<br />
! Name !! Type !! Description<br />
|-<br />
| '''type''' || string || One of: “'''standard'''”, “'''ball_turret'''”, “'''flasher'''”. If not specified, “standard” is assumed.<br />
|-<br />
| '''subentity_key''' || string || The key of a ''shipdata.plist'' entry. Required for '''standard''' and '''ball_turret''' subentities, ignored for flashers.<br />
|-<br />
| '''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).<br />
|-<br />
| '''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.<br />
|-<br />
| '''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.<br />
|}<br />
<br />
{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"<br />
|+ Subentity definition properties for dock subentities (1.77 or later)<br />
! Name !! Type !! Description<br />
|-<br />
| '''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.<br />
|-<br />
| '''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.<br />
|-<br />
| '''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.<br />
|-<br />
| '''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.<br />
|}<br />
See [[Multiple Docks]] for more information on dock subentities and stations with more than one dock in Oolite 1.77 or later.<br />
<br />
{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"<br />
|+ Subentity definition properties for ball turrets<br />
! Name !! Type !! Description<br />
|-<br />
| '''fire_rate''' || number || Interval between shots in seconds, for '''ball_turret''' subentities. Default: 0.5; minimum: 0.25.<br />
|-<br />
| '''weapon_range''' || number || Range for '''ball_turret''' subentities. Default: 6000; maximum 7500.<br />
|-<br />
| '''weapon_energy''' || number || Weapon energy for '''ball_turret''' subentities. Default: 25; maximum 100.<br />
|}<br />
<br />
{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"<br />
|+ Subentity definition properties for flashers<br />
! Name !! Type !! Description<br />
|-<br />
| '''color''' || [[Materials in Oolite#Colour specifiers|colour specifier]] || Single colour for a flasher. Ignored for non-flashers. Default value: '''redColor'''.<br />
|-<br />
| '''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”.<br />
|-<br />
| '''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.<br />
|-<br />
| '''initially_on''' || boolean || Specifiers whether a flasher is turned on when created. Ignored for non-flashers. Default: yes.<br />
|-<br />
| '''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.<br />
|-<br />
| '''size''' || positive number || Diameter of a flasher in metres. Ignored for non-flashers. Default: 8. (Why 8? I don’t remember.)<br />
|-<br />
| '''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.<br />
|-<br />
|}<br />
<br />
=== Old-style subentity definition ===<br />
Prior to Oolite 1.73, this was the the only way to specify a subentity.<br />
<br />
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:<br />
<br />
==== Flashers ====<br />
For a flasher, the entry takes the form:<br />
*FLASHER* x y z hue frequency phase size<br />
''*FLASHER*'' must be precisely the string “*FLASHER*”, in capitals.<br />
<br />
''x'', ''y'' and ''z'' form the '''position'''.<br />
<br />
''hue'' specifies the [http://en.wikipedia.org/wiki/HSL_and_HSV HSV] hue component (in degrees) of '''color'''. Saturation and value are always 1.<br />
<br />
'''frequency''', '''phase''' and '''size''' are the same as in the new-style format.<br />
<br />
'''initially_on''' is false.<br />
<br />
==== Other subentities ====<br />
For a non-flasher, the entry takes the form:<br />
key x y z qw qx qy qz<br />
''key'' corresponds to '''subentity_key'''.<br />
<br />
''x'', ''y'' and ''z'' form the '''position'''.<br />
<br />
''qw'', ''qx'', ''qy'' and ''qz'' form the '''orientation'''.<br />
<br />
'''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.<br />
<br />
'''is_dock''' is implied by having the string “dock” (in lowercase) in the ''key''.<br />
<br />
== sun_glare_filter ==<br />
<br />
Added in Oolite 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)<br />
<br />
"sun_glare_filter" = 0.3;<br />
<br />
== track_contacts ==<br />
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.<br />
<br />
Example:<br />
"track_contacts" = yes;<br />
<br />
== throw_sparks ==<br />
Each new ship should start in seemingly good operating condition, unless specifically told not to. (Added with oolite 1.73, false by default)<br />
<br />
Example:<br />
"throw_sparks" = yes;<br />
<br />
== thrust ==<br />
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). <br />
<br />
Example:<br />
"thrust" = "25"<br />
<br />
== unpiloted ==<br />
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.<br><br />
It will not add a pilot when set to false, but will remove any existing pilot when set to true.<br />
commsMessages can only be broadcasted by piloted ships. Ships are by default piloted. cargo , rocks, missiles etc. are not piloted by default.<br />
<br />
Example:<br />
"unpiloted" = yes;<br />
<br />
== view_position_.. ==<br />
Sets the ship's 4 point-of-view positions in XYZ relative to the model.<br />
<br />
Example:<br />
"view_position_aft" = "0.0 5.0 -20.0";<br />
"view_position_forward" = "0.0 1.9375 5.0";<br />
"view_position_port" = "-11.85 2.825 -3.5";<br />
"view_position_starboard" = "11.85 2.825 -3.5";<br />
<br />
<br />
== weapon_energy ==<br />
This setting works differently depending on the type of entity it's used for:<br><br />
<br />
<b>Missiles.</b> Changes the damage inflicted by the missile. Any value accepted.<br />
<br />
<b>NPC ships.</b> 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.<br><br />
<i><b>N.B.</b> It does not have any effect on player ships.</i><br />
<br />
<b>turrets.</b> Unused for turrets. Set the turret weapon_energy in its [[Shipdata.plist#New-style_subentity_definition|subEntity directory]].<br />
<br />
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<br />
<br />
Example:<br />
"weapon_energy" = "17";<br />
<br />
== weapon_facings ==<br />
(1.77 or later only)<br />
What weapon mounts are available on the ship. This is a bit-mask, so pick the mounts and add the numbers:<br />
<br />
1 - Forward<br /><br />
2 - Aft<br /><br />
4 - Port<br /><br />
8 - Starboard<br /><br />
<br />
Example: <br /><br />
Fore and aft weapon mounts only.<br />
<key>weapon_facings</key><br />
<integer>3</integer><br />
<br />
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.<br />
<br />
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.<br />
<br />
== weapon_mount_mode ==<br />
(1.83 or later only)<br />
<br />
This controls how multiple weapon mount points work. It has three possible values:<br />
* '''"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.<br />
* '''"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)<br />
* '''"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)<br />
<br />
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.<br />
<br />
== weapon_offset ==<br />
Removed after version 1.65 (it was used to change the offsetpoint of a plasma cannon.)<br />
<br />
== weapon_position_.. ==<br />
Plots the 'gunmouth' points of the model's 4 potential lasers.<br />
<br />
Example:<br />
"weapon_position_aft" = "0.0 -5.0 -20.0";<br />
"weapon_position_forward" = "0.0 0.0417 16.6667";<br />
"weapon_position_port" = "-13.75 -2.0625 -1.875";<br />
"weapon_position_starboard" = "13.75 -2.0625 -1.875";<br />
<br />
= Station keys=<br />
The following keys are only used by stations or carriers.<br />
<br />
== allegiance ==<br />
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.<br />
<br />
Example:<br />
allegiance = "neutral";<br />
<br />
== allows_auto_docking ==<br />
When set false for a station, this station will not allow the use of a docking computer. Default value in "yes". (Planned for Oolite 1.75)<br />
<br />
Example:<br />
allows_auto_docking = "no";<br />
<br />
== allows_fast_docking ==<br />
When set true for a station, this station will allow fast docking with the docking computer. Default value in "no". (Planned for Oolite 1.75)<br />
<br />
Example:<br />
allows_fast_docking = "yes";<br />
<br />
== defense_ship ==<br />
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]]<br />
<br />
Example:<br />
defense_ship" = "my_defender";<br />
<br />
== defense_ship_role ==<br />
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"<br />
<br />
Example:<br />
"defense_ship_role" = " carrier_defenders";<br />
<br />
== equipment_price_factor ==<br />
Equipment price mask for dockables.<br />
<br />
Example:<br />
"equipment_price_factor" = "4.5";<br />
<br />
== equivalent_tech_level ==<br />
Sets shipyard tech level for dockables, different to the local system tech_level. Default value is the system tech_level.<br />
<br />
Example:<br />
"equivalent_tech_level" = 1;<br />
<br />
== has_npc_traffic ==<br />
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).<br />
<br />
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).<br />
<br />
Example:<br />
"has_npc_traffic" = yes;<br />
<br />
== has_patrol_ships ==<br />
Determines if a station launches periodic patrol ships. Default is "no". Main stations always have patrol ships. (Planned for Oolite 1.75)<br />
<br />
Example:<br />
"has_patrol_ships" = yes;<br />
<br />
== has_shipyard ==<br />
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".)<br />
<br />
Example:<br />
"has_shipyard" = "0.75";<br />
<br />
or<br />
<br />
"has_shipyard" = (<br />
"systemGovernment_number morethan 3",<br />
"systemEconomy_number lessthan 4"<br />
)<br />
<br />
== interstellar_undocking ==<br />
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". (Planned for Oolite 1.75)<br />
<br />
Example:<br />
interstellar_undocking = "yes";<br />
<br />
==is_carrier==<br />
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".)<br />
<br />
Example:<br />
"is_carrier" = yes;<br />
<br />
== market ==<br />
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.<br />
<br />
Example:<br />
"market" = "none";<br />
<br />
== market_broadcast ==<br />
In 1.81 or later, 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.<br />
<br />
"market_broadcast" = no;<br />
<br />
== market_capacity ==<br />
In 1.81 or later, 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.<br />
<br />
"market_capacity" = 31;<br />
<br />
== market_definition ==<br />
In 1.81 or later, 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.<br />
<br />
"market_definition" = (<br />
{<br />
// export cheap clothes<br />
"type" = "class";<br />
"name" = "oolite-wearable";<br />
"price_multiplier" = 0.8;<br />
"price_randomiser" = 0.1;<br />
"quantity_multiplier" = 3.5;<br />
"quantity_randomiser" = 3.0;<br />
}, <br />
{<br />
// not really interested in other goods<br />
"type" = "default";<br />
"price_multiplier" = 0.55;<br />
"price_randomiser" = 0.25;<br />
"quantity_multiplier" = 0.0;<br />
"capacity" = 3;<br />
}<br />
);<br />
<br />
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.<br />
<br />
A blank array<br />
"market_definition" = ();<br />
will give a market identical to the primary system market.<br />
<br />
If this key is omitted, the station will have no market. This is roughly equivalent to<br />
"market_definition = (<br />
{<br />
"type" = "default";<br />
"price_multiplier" = 0;<br />
"quantity_multiplier" = 0;<br />
"capacity" = 0;<br />
}<br />
);<br />
<br />
== market_monitored ==<br />
In Oolite 1.81 and later, 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.<br />
<br />
market_monitored = yes;<br />
<br />
== market_script ==<br />
In Oolite 1.81 and later, allows a [[Oolite_Market_Scripts|market script]] to be used to modify trade prices. This overrides market_definition, if it is present.<br />
<br />
market_script = "myoxp_marketchanges.js";<br />
<br />
== max_defense_ships ==<br />
Designates how many ships a dockable entity (station, carrier) can launch in defense. Default value is 3. See also [[Station Ships]]<br />
<br />
Example:<br />
"max_defense_ships" = "10";<br />
<br />
== max_police ==<br />
Designates how many police or patrol ships a dockable entity (station, carrier) can launch. Default value is 8. See also [[Station Ships]]<br />
<br />
Example:<br />
"max_police " = "10";<br />
<br />
== max_scavengers ==<br />
Designates how many scavengers or miners a dockable entity (station, carrier) can launch. Default value is 3. See also [[Station Ships]]<br />
<br />
Example:<br />
"max_scavengers" = "10";<br />
<br />
== port_dimensions ==<br />
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.<br />
<br />
Example:<br />
"port_dimensions" = "65x30x500";<br />
<br />
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)<br><br />
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.<br />
<br />
== port_radius ==<br />
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.<br />
<br />
Example:<br />
"port_radius" = "500";<br />
<br />
== requires_docking_clearance ==<br />
Sets the requirement for docking clearance. Default is "no". See also [[Oolite_Docking_Clearance_Protocol_%28v1.72_or_later%29|DockingClearance]]<br />
<br />
Example:<br />
"requires_docking_clearance" = yes;<br />
<br />
==rotating==<br />
Given to a station when rotation is desired. Default is "no".<br />
<br />
Example:<br />
"rotating" = yes;<br />
<br />
== station_roll ==<br />
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. (Key is added in Oolite 1.74.2)<br />
<br />
'''Note''': unlike the other turn rate properties, for historical reasons <code>station_roll</code> is measured in right-angles/second, ''not'' radians/second.<br />
<br />
Example:<br />
"station_roll" = "-1.5"<br />
<br />
==tunnel_corners==<br />
Defines the number of corners in the docking tunnel. Ranges from 4 to 128. Default is "4". (Key is added in Oolite 1.75)<br />
<br />
Example:<br />
"tunnel_corners" = 6;<br />
<br />
==tunnel_start_angle==<br />
Defines the position of the first corner of the docking tunnel in degrees. 0 means the first corner is straight up. Default is "45". (Key is added in Oolite 1.75)<br />
<br />
Example:<br />
"tunnel_start_angle" = 0;<br />
<br />
==tunnel_aspect_ratio==<br />
Defines the proportion of the tunnel’s width to its height. Default is "2.67".<br />
<br />
Example:<br />
"tunnel_aspect_ratio" = 1;<br />
<br />
--------------------------------------------------------------------------------<br />
[[Category:Oolite]]<br />
[[Category:Oolite scripting]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Ship&diff=48479Oolite JavaScript Reference: Ship2015-08-23T19:59:11Z<p>Cim: /* weaponPosition* */ 1.83 format change</p>
<hr />
<div><small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Entity|Entity]]</code></small><br /><br />
<small>'''Subtypes:''' <code>[[Oolite JavaScript Reference: Station|Station]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code></small><br />
<br />
The '''<code>Ship</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing a ship, station, missile, cargo pod or other flying item – anything that can be specified in [[shipdata.plist]]. A <code>Ship</code> has all the properties and methods of a <code>Entity</code>, and several others.<br />
<br />
<code>[[Oolite JavaScript Reference: Station|Station]]</code>s and the <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code> are types of ship. Note that these more specific types have additional properties and methods.<br />
<br />
== Properties ==<br />
=== <code>accuracy</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''accuracy''' : Number (read/write, read-only and irrelevant for player ship)<br />
The accuracy of the ship's AI. Varies between -5 and +10 for ships, or 0 and +10 for missiles. Setting a value outside the allowed range will set the closest value within the allowed range.<br />
<br />
For missiles, this affects the missile tracking, with 0 being the default value.<br />
<br />
For NPC ships, this affects their combat AI in many ways. Values of +5 or higher enable various [[OXP_NPC_Combat_AI|special combat AIs]] for a tough fight.<br />
<br />
=== <code>aftWeapon</code> ===<br />
'''aftWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped aft weapon, or <code>null</code>.<br />
<br />
'''See also:''' <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>AI</code> ===<br />
'''AI''' : String (read-only)<br />
The name of the ship’s current plist-based state machine AI. If the ship is using Javascript-based AI, this will always be "<code>nullAI.plist</code>"<br />
<br />
'''See also:''' <code>[[#AIState|AIState]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AIScript|AIScript]]</code><br />
<br />
=== <code>AIFoundTarget</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''AIFoundTarget''' : Entity (read/write, read-only for player)<br />
The "found target" of the ship's AI. This is set by various AI state commands, and is often copied to the primary target with the <code>setTargetToFoundTarget</code> AI command.<br />
<br />
=== <code>AIPrimaryAggressor</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''AIPrimaryAggressor''' : Entity (read/write, read-only for player)<br />
The "primary aggressor" of the ship's AI. Often the last ship to attack this ship.<br />
<br />
=== <code>AIScript</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''AIScript''' : String (read-only)<br />
The name of the ship’s current Javascript-based AI. If the ship is using plist-based AI, this will always be "<code>oolite-nullAI.js</code>"<br />
<br />
'''See also:''' <code>[[#AIScriptWakeTime|AIScriptWakeTime]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AI|AI]]</code><br />
<br />
=== <code>AIScriptWakeTime</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''AIScriptWaketime''' : Number (read-write)<br />
The next game time at which the ship's Javascript-based AI script will receive an <code>aiAwoken</code> event.<br />
<br />
=== <code>AIState</code> ===<br />
'''AIState''' : String (read/write, read-only for player)<br />
The ship’s plist AI’s current state.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#reactToAIMessage|reactToAIMessage()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code><br />
<br />
=== <code>alertCondition</code> ===<br />
'''alertCondition''' : Number (read-only integer)<br />
The ship's current alert condition (Docked = 0, Green = 1, Yellow = 2, Red = 3). Non-Station non-Player ships are generally only found at condition Yellow or Red.<br />
<br />
'''See also:''' [[Oolite_JavaScript_Reference:_Station#alertCondition|station.alertCondition]]<br />
<br />
=== <code>autoAI</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''autoAI''' : Boolean (read-only)<br />
The value of the "<code>auto_ai</code>" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the AI of this ship to better fit into scenarios or roles. If this is false, the ship's provider would prefer you not to alter the AI of this ship but to use it as-is.<br />
<br />
=== <code>autoWeapons</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''autoWeapons''' : Boolean (read-only)<br />
The value of the "<code>auto_weapons</code>" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the properties of this ship to better fit into scenarios or roles. If this is false, the ship's provider would prefer you not to alter the properties of this ship but to use it as-is.<br />
<br />
=== <code>beaconCode</code> ===<br />
'''beaconCode''' : String (read-only in 1.76, read-write from 1.77)<br />
If the ship is a beacon, an identifying string. The first character is used for identification on the [[Advanced Space Compass]]. For non-beacons, this property is <code>null</code>. This can not be changed by script for either the player's ship or the main station.<br />
<br />
'''See also:''' <code>[[#isBeacon|isBeacon]]</code><br />
<br />
=== <code>beaconLabel</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''beaconLabel''' : String (read/write)<br />
A full label for the beacon. This is useful where the beacon code and the full beacon label do not begin with the same letter.<br />
<br />
=== <code>boundingBox</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''boundingBox''' : Vector (read-only)<br />
For ships, a vector describing the dimensions of the cuboid box containing the ship aligned to the ship axes, including all non-flasher sub-entities. For sub-entities, the dimensions of the box for the sub-entity alone.<br />
<br />
Vector components match the standard model order - <code>x</code> is width, <code>y</code> is height, <code>z</code> is length.<br />
<br />
=== <code>bounty</code> ===<br />
'''bounty''' : Number (read/write integer)<br />
The bounty on the ship.<br />
<br />
In 1.77, changes to the bounty are given a reason. If you change this directly, the reason sent to [[Oolite_JavaScript_Reference:_ship_script_event_handlers#shipBountyChanged|shipBountyChanged]] will be "scripted". To set a different reason, use [[#setBounty|setBounty]] instead.<br />
<br />
=== <code>cargoList</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''cargoList''' : Array (read-only)<br />
A list of the ship's current cargo, grouped by cargo type. For the player ship, this is equivalent to <code>player.ship.manifest.list</code><br />
<br />
=== <code>cargoSpaceCapacity</code> ===<br />
'''cargoSpaceCapacity''' : Number (read-only in 1.80, read/write in 1.81, integer)<br />
The ship’s cargo capacity, in tons.<br />
<br />
=== <code>collisionExceptions</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''collisionExceptions''' : Array (read-only)<br />
A list of ships this ship is currently prevented from colliding with. See [[#addCollisionException|addCollisionException]] and [[#removeCollisionException|removeCollisionException]].<br />
<br />
=== <code>commodity</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''commodity''' : String (read-only)<br />
The commodity for cargo containers as a lowercase string. Returns <code>null</code> for non-cargo ships. For scripted cargo that has no specific cargo defined, it returns the general description "goods".<br />
<br />
=== <code>commodityAmount</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''commodityAmount''' : Number (read-only)<br />
The amount of commodity in a cargo container. (not the number of containers in a ship)<br />
<br />
=== <code>contracts</code> ===<br />
'''contracts''' : Array (read-only NSDictionary)<br />
The ship’s contracts. (For now only available for the player). Each contract contains the entries: <code>commodity: string, quantity: integer, description: string, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
<br />
For example, the information of the first contract can be obtained by:<br />
player.ship.contracts[0].commodity<br />
player.ship.contracts[0].quantity<br />
player.ship.contracts[0].description<br />
player.ship.contracts[0].start<br />
player.ship.contracts[0].destination<br />
player.ship.contracts[0].startName<br />
player.ship.contracts[0].destinationName<br />
player.ship.contracts[0].eta // Estimated Time of Arrival.<br />
player.ship.contracts[0].etaDescription<br />
player.ship.contracts[0].fee // The profit of the contract, paid out on successful delivery.<br />
player.ship.contracts[0].premium // The sum paid to obtain the goods and paid back on successful delivery.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this contract, and premium was the amount the player had to pay to secure this contract.<br />
<br />
=== <code>cloakAutomatic</code> ===<br />
'''cloakAutomatic''' : Boolean (read/write)<br />
If <code>true</code> (the default), the ship will automatically engage its cloak while attacking. Otherwise, it must be managed by a script. The corresponding ''[[shipdata.plist]]'' key is <code>cloak_automatic</code>.<br />
<br />
=== <code>crew</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''crew''' : Array (read-only)<br />
An array containing the ship's crew. Each crew member is represented as a dictionary. Note that in current Oolite versions ships only have a single crew member defined.<br />
<br />
=== <code>cruiseSpeed</code> ===<br />
'''cruiseSpeed''' : Number (read-only nonnegative)<br />
The ship’s “normal” <code>[[#desiredSpeed|desiredSpeed]]</code>, used in normal flight. Normally this is 80 % of <code>[[#maxSpeed|maxSpeed]]</code>, but it may be lowered when accepting a slow escort.<br />
<br />
=== <code>currentWeapon</code> ===<br />
{{oolite-prop-added|1.77}} <br />
'''currentWeapon''' : EquipmentType (read/write)<br />
A shortcut property to whichever of <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code> or <code>[[#starboardWeapon|starboardWeapon]]</code> represents the ship's currently active laser mount.<br />
<br />
=== <code>dataKey</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''dataKey''' : String (read-only)<br />
The ship data key used to define this ship (e.g. <code>adder-player</code> or <code>coriolis-station</code>)<br />
<br />
=== <code>defenseTargets</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''defenseTargets''' : Array (read-only)<br />
The array of defense targets that the ship has. If the ship has point defense weapons (turrets, thargoid lasers) it may fire them at these targets if it cannot hit its primary target.<br />
<br />
'''See also:''' <code>[[#addDefenseTarget|addDefenseTarget]]</code>, <code>[[#clearDefenseTargets|clearDefenseTargets]]</code><br />
<br />
=== <code>desiredRange</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''desiredRange''' : Number (read/write nonnegative, read-only for player)<br />
The range the AI uses in various AI routines to set a distance between the ship and another object - for example, the radius of a sphere around a destination point, or the distance to flee from a hostile ship.<br />
<br />
=== <code>desiredSpeed</code> ===<br />
'''desiredSpeed''' : Number (read/write nonnegative, read-only for player)<br />
The speed the AI will attempt to maintain. The AI core and AI script may change this from time to time. The corresponding AI method is <code>setSpeedFactorTo:</code>; a speed factor of 1.0 corresponds to a <code>desiredSpeed</code> equal to <code>[[#maxSpeed|maxSpeed]]</code>.<br />
<br />
'''See also:''' <code>[[#cruiseSpeed|cruiseSpeed]]</code><br />
<br />
=== <code>destination</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''destination''' : Vector (read/write, read-only for player)<br />
The destination coordinates for the AI, used in behaviours such as <code>performFlyToRangeFromDestination</code>.<br />
<br />
=== <code>destinationSystem</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''destinationSystem''' : Number (read/write)<br />
The destination system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.<br />
<br />
=== <code>displayName</code> ===<br />
'''displayName''' : String (read/write, read-only for player)<br />
The name of the ship as seen by the player. By default in 1.78 or earlier it is the same as <code>[[#name|name]]</code>. In 1.79 or later it is a combination of [[#shipClassName|shipClassName]] and [[#shipUniqueName|shipUniqueName]]<br />
<br />
=== <code>dockingInstructions</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''dockingInstructions''' : Object (read-only)<br />
If the ship is currently attempting to dock with a station, this describes the next step on its docking procedure<br />
<br />
{<br />
station: [Station "Coriolis Station" "Coriolis Station" position: (-31043.6, -94232.3, 619036) scanClass: CLASS_STATION status: STATUS_ACTIVE],<br />
match_rotation: 0,<br />
ai_message: "APPROACH_COORDINATES",<br />
speed: 512,<br />
destination: {<br />
x: -28033.37401563089,<br />
y: -92813.76688970842,<br />
z: 622226.0625336492<br />
},<br />
range: 96<br />
}<br />
<br />
'''See also:''' <code>[[#requestDockingInstructions|requestDockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code><br />
<br />
=== <code>energyRechargeRate</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''energyRechargeRate''' : Number (read-only, read/write from 1.81)<br />
The rate at which energy is replenished in every second. The corresponding ''[[shipdata.plist]]'' key is <code>energy_recharge_rate</code>.<br />
<br />
Note for the player ship that this includes the boost from an extra or naval energy unit, and NPC (but not player) ships with military shield boosters also have an increase to this in lieu of actual shields.<br />
<br />
=== <code>entityPersonality</code> ===<br />
'''entityPersonality''' : Number (read-only integer, read/write in 1.81 onwards)<br />
A random number in the range 0..32767 which is generated when the ship is created. Equivalent to the <code>entityPersonalityInt</code> [[Shaders in Oolite: uniforms#Ship|uniform binding]].<br />
<br />
Altering this value is possible in 1.81 onwards, but requires a re-bind of the materials and shaders, and so is a relatively slow process.<br />
<br />
=== <code>equipment</code> ===<br />
'''equipment''' : Array of [[Oolite_JavaScript_Reference:_EquipmentInfo|EquipmentInfo ]] (read-only)<br />
The equipment a ship is carrying.<br />
<br />
=== <code>escortGroup</code> ===<br />
'''escortGroup''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]<br />
The ship’s deployed escorts.<br />
<br />
'''See also:''' <code>[[#maxEscorts|maxEscorts]]</code><br />
<br />
=== <code>escorts</code> ===<br />
'''escorts''' : Array (read-only array of [[Oolite JavaScript Reference: Entity|Entity]]s)<br />
The ship’s deployed escorts.<br />
<br />
=== <code>exhaustEmissiveColor</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''exhaustEmissiveColor''' : Color (read/write)<br />
The baseline colour of the ship's exhaust. Damage to the ship, and use of injectors and torus drive, apply a fixed transformation to this colour, so not all colours are effective as exhaust colours.<br />
<br />
=== <code>exhausts</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''exhausts''' : Array (read-only)<br />
An array of the ship's [[Oolite_JavaScript_Reference:_ExhaustPlume|ExhaustPlume]] subentities.<br />
<br />
=== <code>extraCargo</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''extraCargo''' : Number (read-only integer)<br />
The amount the cargo capacity increases when an extra cargobay is installed. The corresponding ''[[shipdata.plist]]'' key is <code>extra_cargo</code>.<br />
<br />
=== <code>flashers</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''flashers''' : Array (read-only)<br />
An array of the ship's [[Oolite_JavaScript_Reference:_Flasher|Flasher]] subentities.<br />
<br />
=== <code>forwardWeapon</code> ===<br />
'''forwardWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped forward weapon, or <code>null</code>.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>fuel</code> ===<br />
'''fuel''' : Number (read/write)<br />
The ship’s current fuel capacity, in LY. The game will limit this to the range 0..7, and round it off to the nearest tenth.<br />
<br />
'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#fuelLeakRate|PlayerShip.fuelLeakRate]]</code><br />
<br />
=== <code>fuelChargeRate</code> ===<br />
'''fuelChargeRate''' : Number (read-only)<br />
The cost, relative to the cost for a new Cobra III, of a unit of fuel. When buying fuel for a ship, the price in [[equipment.plist]] will be multiplied by this number.<br />
<br />
=== <code>group</code> ===<br />
'''group''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]<br />
Contains ship’s belonging to each other. Added pirate groups are an example or a station with its launched defenders.<br><br />
A group is an individual object that can be linked to several ships belonging to the same group. When a ship dies and the group object has still owners, the group stays active as object. The group is only removed from memory after the last ship that had this group as property is removed.<br><br />
Adding a group to a ship does not automatic puts that ship in the group. For that to happen you need also use the addShip() command. <br />
e.g. <br />
this.ship.group = new ShipGroup();<br />
this.ship.group.addShip(this.ship);<br />
<br />
=== <code>hasHostileTarget</code> ===<br />
'''hasHostileTarget''' : Boolean (read-only)<br />
<code>true</code> if the ship’s AI is trying to kill something, <code>false</code> otherwise. Always <code>false</code> for the player.<br />
<br />
=== <code>hasHyperspaceMotor</code> ===<br />
'''hasHyperspaceMotor''' : Boolean (read-only)<br />
True if the ship can make witchspace jumps. The corresponding ''[[shipdata.plist]]'' entry is <code>hyperspace_motor</code>.<br />
<br />
=== <code>hasSuspendedAI</code> ===<br />
'''hasSuspendedAI''' : Boolean (read-only)<br />
<code>true</code> if the ship has suspended AIs, <code>false</code> otherwise.<br />
<br />
=== <code>heatInsulation</code> ===<br />
'''heatInsulation''' : Number (read/write)<br />
The ship’s heat insulation factor. 1.0 is normal, higher values mean more resistance to heat.<br />
<br />
Note that in 1.80 and earlier writes to this property had no effect on the player ship.<br />
<br />
=== <code>homeSystem</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''homeSystem''' : Number (read/write)<br />
The home system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.<br />
<br />
=== <code>hyperspaceSpinTime</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''hyperspaceSpinTime''' : Number (read/write)<br />
The length of the ship's hyperspace countdown.<br />
<br />
Setting this to a negative value disables the drive entirely.<br />
<br />
Note that most NPC ship jumps use <code>ship.exitSystem()</code> to make the jump, which does not have a delay. Provided this value is zero or positive, the ship will jump instantly if <code>ship.exitSystem()</code> is called. The AI must use this property elsewhere if a delay before jumping is required.<br />
<br />
=== <code>injectorBurnRate</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorBurnRate''' : Number (read/write)<br />
The rate at which the ship's injectors burn fuel in deci-LY per second. The default is 0.25.<br />
<br />
=== <code>injectorSpeedFactor</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorSpeedFactor''' : Number (read/write)<br />
The multiplier to maximum speed granted to this ship when it is using injectors. The default is 7, and values must be between 1.0 and 32.0 (the torus drive's speed)<br />
<br />
=== <code>isBeacon</code> ===<br />
'''isBeacon''' : Boolean (read-only)<br />
<code>true</code> if the ship is a beacon (i.e., can show up on the [[Advanced Space Compass]] with a character indicating its identity), <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#beaconCode|beaconCode]]</code><br />
<br />
=== <code>isBoulder</code> ===<br />
'''isBoulder''' : Boolean (read/write)<br />
<code>true</code> if the ship is a boulder (i.e., has the role "boulder in its roleset)<br />
<br />
=== <code>isCargo</code> ===<br />
'''isCargo''' : Boolean (read-only)<br />
<code>true</code> if the ship is cargo (i.e., has scan_class CLASS_CARGO and contains at least one unit)<br />
<br />
=== <code>isCloaked</code> ===<br />
'''isCloaked''' : Boolean (read/write)<br />
<code>true</code> if the ship has a cloaking device which is currently active <code>false</code> otherwise. If the ship has a cloaking device and sufficient energy to use it (<code>energy > 0.75 * [[Oolite JavaScript Reference: Entity#maxEnergy|maxEnergy]]</code>), you can activate it by setting <code>isCloaked</code> to <code>true</code>.<br />
<br />
=== <code>isDerelict</code> ===<br />
'''isDerelict''' : Boolean (read-only)<br />
<code>true</code> if the ship is a derelict (i.e., the pilot has ejected from the ship, or the ship was created with the ship-key: "is_hulk")<br />
<br />
=== <code>isFleeing</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isFleeing''' : Boolean (read-only)<br />
<code>true</code> if the ship is currently fleeing combat. This may be queried for the player ship too, though the value is somewhat of a guess in that case as it's impossible to say for certain what the player is intending by their actions.<br />
<br />
=== <code>isFrangible</code> ===<br />
'''isFrangible''' : Boolean (read-only)<br />
<code>true</code> if the ship is frangible (i.e., its subentities can be destroyed separately from the main ship), <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>isJamming</code> ===<br />
'''isJamming''' : Boolean (read-only)<br />
<code>true</code> if the ship has a military scanner jammer which is currently active <code>false</code> otherwise.<br />
<br />
=== <code>isMinable</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isMinable''' : Boolean (read-only)<br />
<code>true</code> if the ship will break up usefully when hit by a mining laser, <code>false</code> otherwise. By default this is true for anything with "asteroid" or "boulder" in its role list - if you need to add anything which miners shouldn't be shooting at to those roles, give it <code>"no_boulders" = yes;</code> in its [[shipdata.plist]].<br />
<br />
=== <code>isMine</code> ===<br />
'''isMine''' : Boolean (read-only)<br />
<code>true</code> if the ship is a mine, <code>false</code> otherwise.<br />
<br />
=== <code>isMissile</code> ===<br />
'''isMissile''' : Boolean (read-only)<br />
<code>true</code> if the ship is a missile, <code>false</code> otherwise.<br />
<br />
=== <code>isPiloted</code> ===<br />
'''isPiloted''' : Boolean (read-only)<br />
<code>true</code> if the ship has a pilot on board, <code>false</code> otherwise. Generally have ships, station and escape pods pilots and have cargo, rocks, missiles or buoys no pilots.<br />
<br />
=== <code>isPirate</code> ===<br />
'''isPirate''' : Boolean (read-only)<br />
<code>true</code> if the ship is a pirate vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "pirate"</code>.<br />
<br />
=== <code>isPirateVictim</code> ===<br />
'''isPirateVictim''' : Boolean (read-only)<br />
<code>true</code> if the ship’s [[#primaryRole|primary role]] is listed in ''pirate-victim-roles.plist'', <code>false</code> otherwise. This is the same test used by the pirate AI to select victims.<br />
<br />
=== <code>isPolice</code> ===<br />
'''isPolice''' : Boolean (read-only)<br />
<code>true</code> if the ship is a police vessel, <code>false</code> otherwise. Currently equivalent to <code>[[Oolite JavaScript Reference: Entity#scanClass|scanClass]] == "CLASS_POLICE"</code>.<br />
<br />
=== <code>isRock</code> ===<br />
'''isRock''' : Boolean (read-only)<br />
<code>true</code> if the ship is a rock (i.e., has scan_class: CLASS_ROCK)<br />
<br />
=== <code>isThargoid</code> ===<br />
'''isThargoid''' : Boolean (read-only)<br />
<code>true</code> if the ship is a Thargoid vessel, <code>false</code> otherwise. Currently equivalent to <code>[[Oolite JavaScript Reference: Entity#scanClass|scanClass]] == "CLASS_THARGOID"</code>.<br />
<br />
=== <code>isTrader</code> ===<br />
'''isTrader''' : Boolean (read-only)<br />
<code>true</code> if the ship is a merchant vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "trader" || isPlayer</code>. '''Note:''' <code>[[#isPirateVictim|isPirateVictim]]</code> may be a better choice in many cases.<br />
<br />
=== <code>isTurret</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isTurret''' : Boolean (read-only)<br />
<code>true</code> if the ship is a plasma turret sub-entity, <code>false</code> otherwise.<br />
<br />
=== <code>isWeapon</code> ===<br />
'''isWeapon''' : Boolean (read-only)<br />
<code>true</code> if the ship is a weapon, <code>false</code> otherwise. Currently equivalent to <code>[[#isMissile|isMissile]] || [[#isMine|isMine]] </code>, but new categories of weapon could be added in future.<br />
<br />
=== <code>laserHeatLevel</code>* ===<br />
{{Oolite-prop-added|1.77}}<br />
'''laserHeatLevel''' : Number (read-only, 0 to 1)<br />
The temperature of the ship's currently active weapon. Thermal cut-out is active above 0.85. For non-player ships, if their forward weapon is empty, then the temperature of the forward weapon may be the temperature of a subentity forward weapon.<br />
'''laserHeatLevelAft''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelForward''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelPort''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelStarboard''' : Number (read-only, 0 to 1)<br />
The temperature of specific laser mounts can also be queried.<br />
<br />
=== <code>lightsActive</code> ===<br />
'''lightsActive''' : Boolean (read-write)<br />
Setting this property to <code>true</code> turns on all the entity’s flashers, and setting it to <code>false</code> turns them off. Setting it sets the <code>lightsActive</code> property for all subentities, but subentities’ setting can also be manipulated separately. In addition to affecting flashers, the value can be used by shaders.<br />
<br />
Note: <code>lightsActive</code> is always <code>true</code> when a ship is spawned, although individual flashers may be off because they have <code>initially_on</code> set to false in their ''shipdata.plist'' declarations.<br />
<br />
=== <code>markedForFines</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''markedForFines''' : Boolean (read-only)<br />
<code>True</code> if the ship has been marked for fines the next time it docks at this system's main station.<br />
<br />
'''See also''' : [[#markTargetForFines|markTargetForFines()]]<br />
<br />
=== <code>maxEscorts</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxEscorts''' : Number (read/write)<br />
The maximum number of escorts this ship can have. This cannot be set lower than the number of escorts it currently has, or higher than the value of the MAX_ESCORTS constant (currently 16). There may be other reasons why a ship can have fewer escorts than the value of <code>maxEscorts</code> (for instance, ships which are escorts cannot have their own escorts)<br />
<br />
'''See also:''' <code>[[#escortGroup|escortGroup]]</code><br />
<br />
=== <code>maxPitch</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxPitch''' : Number (read-only, read/write from 1.81)<br />
The maximum pitch rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#pitch|pitch]]</code><br />
<br />
=== <code>maxRoll</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxRoll''' : Number (read-only, read/write from 1.81)<br />
The maximum roll rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#roll|roll]]</code><br />
<br />
=== <code>maxSpeed</code> ===<br />
'''maxSpeed''' : Number (read-only, read/write from 1.81)<br />
The ship’s maximum speed under normal power. Note that <code>[[#speed|speed]]</code> may exceed this when [[witch fuel injectors]] or [[hyperspeed]] are in use.<br />
<br />
'''See also:''' <code>[[#speed|speed]]</code><br />
<br />
=== <code>maxThrust</code> ===<br />
'''maxThrust''' : Number (read-only, read/write from 1.81)<br />
The ship’s maximum <code>[[#thrust|thrust]]</code>. This value is the one defined as <code>thrust</code> in ''[[Shipdata.plist#thrust|shipdata.plist]]''.<br />
<br />
=== <code>maxYaw</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxYaw''' : Number (read-only, read/write from 1.81)<br />
The maximum yaw rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#yaw|yaw]]</code><br />
<br />
=== <code>missileCapacity</code> ===<br />
'''missileCapacity''' : Number (read-only integer)<br />
The maximum number of missiles the ship can carry.<br />
<br />
=== <code>missileLoadTime</code> ===<br />
'''missileLoadTime''' : Number (read-write nonnegative)<br />
The minimum amount of time between two missiles. The corresponding ''[[shipdata.plist]]'' key is <code>missile_load_time</code>.<br />
<br />
=== <code>missiles</code> ===<br />
'''missiles''' : Array (read-only array of [[Oolite JavaScript Reference: EquipmentInfo|EquipmentInfo]])<br />
The ship’s loaded missiles.<br />
<br />
=== <code>name</code> ===<br />
'''name''' : String (read/write, read-only for player)<br />
The name of the ship type (<code>name</code> key in [[shipdata.plist]]).<br />
<br />
''Note'': while <code>name</code> can be changed, this is discouraged (and will probably not be supported in Oolite 2.0). Use <code>[[#displayName|displayName]]</code> instead.<br />
<br />
=== <code>parcelCount</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''parcelCount''' : Number (read-only integer)<br />
The ship’s current number of parcels.<br />
<br />
=== <code>parcels</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''parcels''' : Array (read-only NSDictionary)<br />
The ship’s parcels. (For now only available for the player). Each parcel list contains the entries: <code>name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
For example, the information of the first contract can be obtained by:<br />
player.ship.parcels[0].name<br />
player.ship.parcels[0].start<br />
player.ship.parcels[0].destination<br />
player.ship.parcels[0].startName<br />
player.ship.parcels[0].destinationName<br />
player.ship.parcels[0].eta<br />
player.ship.parcels[0].etaDescription<br />
player.ship.parcels[0].fee // The final fee, paid out on successful delivery.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this parcel.<br />
<br />
=== <code>passengerCapacity</code> ===<br />
'''passengerCapacity''' : Number (read-only integer)<br />
The ship’s maximum passenger capacity.<br />
<br />
=== <code>passengerCount</code> ===<br />
'''passengerCount''' : Number (read-only integer)<br />
The ship’s current number of passengers.<br />
<br />
=== <code>passengers</code> ===<br />
'''passengers''' : Array (read-only NSDictionary)<br />
The ship’s passengers. (For now only available for the player). Each passengers list contains the entries: <code>name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
For example, the information of the first contract can be obtained by:<br />
player.ship.passengers[0].name<br />
player.ship.passengers[0].start<br />
player.ship.passengers[0].destination<br />
player.ship.passengers[0].startName<br />
player.ship.passengers[0].destinationName<br />
player.ship.passengers[0].eta<br />
player.ship.passengers[0].etaDescription<br />
player.ship.passengers[0].fee // The final fee, paid out on successful delivery.<br />
player.ship.passengers[0].premium // The advance fee, already paid on acceptance of the contract.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this passenger, and premium shows the amount the player received when the passenger boarded the ship.<br />
<br />
=== <code>pitch</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''pitch''' : Number (read-only)<br />
The rate of pitch of the ship in radians/second (positive for dive, negative for climb)<br />
<br />
=== <code>portWeapon</code> ===<br />
'''portWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped port weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>potentialCollider</code> ===<br />
'''potentialCollider''' : [[Oolite JavaScript Reference: Entity|Entity]] (read-only)<br />
The entity the ship is currently trying not to crash into, if any.<br />
<br />
=== <code>primaryRole</code> ===<br />
'''primaryRole''' : String (read/write, read-only for player)<br />
The main role of the ship; the role for which it was created. For instance, if a ship’s ''shipdata.plist'' entry specifies the roles “pirate trader(0.5) escort”, and a ship of that type is spawned to be a trader, its <code>primaryRole</code> is <code>"trader"</code>, its <code>roles</code> is <code>["escort", "pirate", "trader"]</code> and its <code>roleWeights</code> is <code> { "escort":1, "pirate":1, "trader":0.5}</code>.<br />
<br />
'''See also:''' <code>[[#roles|roles]]</code>, <code>[[#roleWeights|roleWeights]]</code><br />
<br />
=== <code>reportAIMessages</code> ===<br />
'''reportAIMessages''' : Boolean (read/write)<br />
Debugging facility: set to <code>true</code> to dump information about AI activity to the log. <br />
<br />
=== <code>roleWeights</code> ===<br />
'''roleWeights''' : Object (read-only)<br />
The probabilities for each role in <code>[[#roles|roles]]</code>.<br />
<br />
Example:<br />
this.pirateProb = ship.roleWeights["pirate"]<br />
<br />
'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roles|roles]]</code><br />
<br />
=== <code>roles</code> ===<br />
'''roles''' : Array (read-only array of Strings)<br />
The roles of the ship. This consists of the roles specified in the ship’s ''shipdata.plist'' entry, as well as the <code>[[#primaryRole|primaryRole]]</code> if it is not among those.<br />
<br />
'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roleWeights|roleWeights]]</code>, <code>[[#hasRole|hasRole()]]</code><br />
<br />
=== <code>roll</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''roll''' : Number (read-only, read/write for stations)<br />
The rate of roll of the ship in radians/second (positive for anti-clockwise, negative for clockwise)<br />
<br />
For stations, this can be set to any value between -2 and +2 to adjust their roll rate. The default is 0.4, or the value specified by the <code>station_roll</code> key in shipdata.plist.<br />
<br />
=== <code>savedCoordinates</code> ===<br />
'''savedCoordinates''' : [[Oolite JavaScript Reference: Vector|Vector]] (read-write)<br />
The savedCoordinates of the ship in system co-ordinates. The savedCoordinates vector is only used by AI scripting to store a coordinate that can be used by other AI commands like <code>setDestinationFromCoordinates</code>. It are the same coordinates that are set by the AI command: <code>"setCoordinates: X Y Z"</code><br />
<br />
=== <code>scanDescription</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''scanDescription''' : String (read/write)<br />
The description of the ship in the "legal status" text shown by the [[Scanner Targeting Enhancement]]. If this is null then the default text for the ship's scan class and bounty level will be shown.<br />
<br />
=== <code>scannerDisplayColor1</code> ===<br />
'''scannerDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The first of two colours used by the ship’s scanner “lollipop”. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning <code>null</code> will restore the value from [[shipdata.plist]], or the default value for the ship’s scan class.<br />
<br />
'''See also:''' <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code>, <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code><br />
<br />
=== <code>scannerDisplayColor2</code> ===<br />
'''scannerDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The second scanner colour. If both <code>scannerDisplayColor1</code> and <code>scannerDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.<br />
<br />
'''See also:''' <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code>, <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code><br />
<br />
=== <code>scannerHostileDisplayColor1</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''scannerHostileDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The first of two colours used by the ship’s scanner “lollipop” when the ship is specifically targeting the player with hostile intent. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning <code>null</code> will restore the value from [[shipdata.plist]], or the default value for the ship’s scan class.<br />
<br />
If hostile colours are set but normal colours aren't, then the normal colours will default to those for the ship's scan class. If normal colours are set but hostile colours aren't, the scanner blip will not change colour when the ship is hostile.<br />
<br />
'''See also:''' <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code>, <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code><br />
<br />
=== <code>scannerHostileDisplayColor2</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''scannerHostileDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The second scanner colour when the ship is specifically targeting the player with hostile intent.. If both <code>scannerHostileDisplayColor1</code> and <code>scannerHostileDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.<br />
<br />
'''See also:''' <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code>, <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code><br />
<br />
=== <code>scannerRange</code> ===<br />
'''scannerRange''' : Number (read-only)<br />
The range of the ship’s scanner.<br />
<br />
=== <code>script</code> ===<br />
'''script''' : [[Oolite JavaScript Reference: Script|Script]] (read-only)<br />
The ship’s script.<br />
<br />
=== <code>scriptedMisjump</code> ===<br />
'''scriptedMisjump''' : Boolean (read/write)<br />
When <code>true</code>, the next hyperspace jump will be a misjump. The <code>scriptedMisjump</code> flag will remain <code>true</code> during the <code>shipWillExitWitchspace()</code> event handler, and will be set to <code>false</code> after the <code>shipExitedWitchspace()</code> event.<br />
<br />
=== <code>scriptedMisjumpRange</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''scriptedMisjumpRange''' : Number (read/write)<br />
If this ship misjumps, this number will be consulted to determine the length of the resulting misjump relative to the normal jump range. Setting this does not in itself force a misjump - this must occur through the usual mechanisms. Values must be greater than 0.0 and less than 1.0, and the default is 0.5 for a traditional half-way misjump. This will be reset to 0.5 at the same time as <code>[[#scriptedMisjump|scriptedMisjump]]</code> is reset to <code>false</code>.<br />
<br />
=== <code>scriptInfo</code> ===<br />
'''scriptInfo''' : Object (read-only)<br />
The contents of the <code>script_info</code> key in the ship’s ''[[shipdata.plist]]'' entry, if any. This may be any [[property list]] object, but the recommended approach is to use a dictionary whose keys have a unique prefix (such as you should be using for file names, ship names etc.). A property list dictionary is converted to a JavaScript object with properties corresponding to the dictionary’s keys. All other property list types used with Oolite have directly corresponding JavaScript types.<br><br />
When using numeric values in the scriptInfo, the JS engine is not able to detect the type reliably on all systems, so you always must explicitly convert its content to a number by using parseInt(scriptInfo.myKey) or parseFloat(scriptInfo.myKey).<br />
<br />
=== <code>shipClassName</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''shipClassName''' : String (read/write)<br />
The name of the ship class (e.g. "Python")<br />
<br />
=== <code>shipUniqueName</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''shipUniqueName''' : String (read/write)<br />
The name of this specific ship (e.g. "Sunrise of Lave")<br />
<br />
=== <code>speed</code> ===<br />
'''speed''' : Number (read-only)<br />
The ship’s current speed.<br />
<br />
'''See also:''' <code>[[#maxSpeed|maxSpeed]]</code><br />
<br />
=== <code>starboardWeapon</code> ===<br />
'''starboardWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped forward weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code><br />
<br />
=== <code>subEntities</code> ===<br />
'''subEntities''' : Array (read-only array of Ships)<br />
The ships subentities, or <code>null</code> if it has none. Special subentities such as flashers and exhaust plumes are not included.<br />
<br />
'''See also:''' <code>[[#isFrangible|isFrangible]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>subEntityCapacity</code> ===<br />
'''subEntityCapacity''' : Number (read-only integer)<br />
The original number of subentities on the ship. <br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>subEntityRotation</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''subEntityRotation''' : Quaternion (read/write)<br />
The subentity rotational velocity, expressed as a quaternion. This much rotation will be applied per second. Exact 180 degree rotations should not be specified, as it is not possible to determine what route to use to make that rotation. This property is ignored when set on non-subentities.<br />
<br />
=== <code>sunGlareFilter</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''sunGlareFilter''' : Number (read/write)<br />
The strength of the sun glare filter on this ship. It must be in the range 0 to 1 (0 is no filter).<br />
<br />
=== <code>target</code> ===<br />
'''target''' : Ship (read-write)<br />
The ship’s primary target, i.e. the entity it will attempt to shoot at. This value is automatically co-ordinated between a ship and its subentities.<br />
<br />
=== <code>temperature</code> ===<br />
'''temperature''' : Number (read/write)<br />
The ship’s temperature, normalized such that a temperature of 1.0 is the level at which a ship starts taking heat damage.<br />
<br />
=== <code>thrust</code> ===<br />
'''thrust''' : Number (read/write for NPCs, read-only for player before 1.81)<br />
The ship’s thrust, ranging from 0 to <code>maxThrust</code>. This value determines how fast the ship accelerates or decelerates, specified in m/s².<br />
<br />
'''See also:''' <code>[[#thrustVector|thrustVector]]</code><br />
<br />
=== <code>thrustVector</code> ===<br />
'''thrustVector''' : Vector3D (read-only)<br />
The inertialess velocity generated by the engines.<br />
<br />
'''See also:''' <code>[[#thrust|thrust]]</code>, <code>[[#velocity|velocity]]</code><br />
<br />
=== <code>trackCloseContacts</code> ===<br />
'''trackCloseContacts''' : Boolean (read/write)<br />
If true, AI events are generated for near collisions.<br />
<br />
=== <code>vectorForward</code> ===<br />
'''vectorForward''' : Vector3D (read-only)<br />
The vector pointing forwards from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorForward|vectorForward]]</code>.<br />
<br />
=== <code>vectorRight</code> ===<br />
'''vectorRight''' : Vector3D (read-only)<br />
The vector pointing right from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorRight|vectorRight]]</code>.<br />
<br />
=== <code>vectorUp</code> ===<br />
'''vectorUp''' : Vector3D (read-only)<br />
The vector pointing up from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorUp|vectorUp]]</code>.<br />
<br />
=== <code>velocity</code> ===<br />
'''velocity''' : Vector3D (read/write)<br />
The ship’s velocity.<br />
<br />
'''Note:''' A ship’s velocity consists of two components, inertial velocity and inertialess thrust. Generally, inertial velocity is zero (so <code>velocity</code> is equal to <code>[[#thrustVector|thrustVector]]</code>), but inertial impulses may be applied if a ship collides or is caught in an explosion. If inertial velocity is non-zero, the ship’s engines will work to counteract it. Changing the ship’s velocity will always apply inertial velocity, so for ships with non-zero <code>[[#maxThrust|maxThrust]]</code> the effect will be temporary.<br />
<br />
'''See also:''' <code>[[#thrustVector|thrustVector]]</code><br />
<br />
=== <code>weaponFacings</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''weaponFacings''' : Number (read-only, integer in range 0-15)<br />
The weapon facings available for the ship. The format is the same as the equivalent property in [[shipyard.plist]] or [[shipdata.plist]] - a bitmask with the following bits:<br><br />
1 - fore<br><br />
2 - aft<br><br />
4 - port<br><br />
8 - starboard<br />
<br />
=== <code>weaponPosition*</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''weaponPositionAft''' : Vector (read-only)<br />
'''weaponPositionForward''' : Vector (read-only)<br />
'''weaponPositionPort''' : Vector (read-only)<br />
'''weaponPositionStarboard''' : Vector (read-only)<br />
<br />
{{Oolite-prop-added|1.83}}<br />
'''weaponPositionAft''' : Array of Vectors (read-only)<br />
'''weaponPositionForward''' : Array of Vectors (read-only)<br />
'''weaponPositionPort''' : Array of Vectors (read-only)<br />
'''weaponPositionStarboard''' : Array of Vectors (read-only)<br />
<br />
The position relative to the ship at which the appropriate laser beam will start. These properties do not imply that the ship has or can have any such weapon.<br />
<br />
In 1.83 this property changed syntax to become an array of vectors, as ships can now have multiple mounts per facing.<br />
<br />
=== <code>weaponRange</code> ===<br />
'''weaponRange''' : Number (read-only)<br />
The maximum range of the ship’s primary weapon. For the player it is the range of the weapon that fired as last, even when the view direction changed.<br><br />
Range values are: WEAPON_PLASMA_CANNON: 5000, WEAPON_PULSE_LASER: 12500, WEAPON_BEAM_LASER: 15000, WEAPON_MINING_LASER: 12500, WEAPON_THARGOID_LASER: 17500, WEAPON_MILITARY_LASER: 30000, WEAPON_NONE: 32000.<br><br />
(Turrets are secondary weapons with a maximum range of 6000)<br />
<br />
=== <code>withinStationAegis</code> ===<br />
'''withinStationAegis''' : Boolean (read-only)<br />
<code>true</code> if the ship is within the aegis of the system’s main station (i.e., no more than 51 200 game metres from the station, or twice scanner range).<br />
<br />
=== <code>yaw</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''yaw''' : Number (read-only)<br />
The rate of yaw of the ship in radians/second (positive for right, negative for left)<br />
<br />
== Methods ==<br />
=== <code>abandonShip</code> ===<br />
function '''abandonShip'''() : Boolean<br />
Returns <code>true</code> when the ship has an escapepod. It will launch all escapeposd on board leaving the ship behind as a empty hulk. (scanClass = CLASS_CARGO). This command does nothing when no escape-pod is present.<br><br />
Pressence of an escapepod can be tested with: <code>equipmentStatus("EQ_ESCAPE_POD") == "EQUIPMENT_OK"</code><br />
<br />
=== <code>addCollisionException</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''addCollisionException'''(exception : Ship)<br />
Prevented this ship and the selected ship from colliding. See [[#collisionExceptions|collisionExceptions]] and [[#removeCollisionException|removeCollisionException]].<br />
<br />
Prevention from collision will specifically prevent the following:<br />
<br />
* the ships colliding with each other and suffering collision damage and/or momentum change<br />
* the ships receiving collision warning events if they come close to each other<br />
* if one of the ships is a station, the other ship will not be able to dock with it even if it enters a dock<br />
<br />
This has no useful effect when applied to a subentity.<br />
<br />
Adding a collision exception which already exists has no effect but will not cause an error.<br />
<br />
=== <code>addDefenseTarget</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''addDefenseTarget'''(target : Ship)<br />
Adds the target ship to this ship's list of point [[#defenseTargets|defense targets]], if it isn't already.<br />
<br />
=== <code>adjustCargo</code>===<br />
{{oolite-method-added|1.81}}<br />
function '''adjustCargo'''(commodity : String, amount : Number) : Boolean<br />
Adjust the quantity of the specified commodity carried by the ship. Amount may be negative to remove cargo. The method will return false if the operation would fail due to insufficient free space or carried cargo, and will not make a partial adjustment in this case.<br />
<br />
=== <code>awardEquipment</code> ===<br />
function '''awardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Adds the given piece of equipment to the ship, if possible, returning <code>true</code> if successful and <code>false</code> otherwise.<br />
<br />
Example:<br />
ship.awardEquipment("EQ_ECM");<br />
<br />
'''See also:''' <code>[[#canAwardEquipment|canAwardEquipment()]]</code>, <code>[[#removeEquipment|removeEquipment()]]</code><br />
<br />
=== <code>canAwardEquipment</code> ===<br />
function '''canAwardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Tests whether it is possible to add a given equipment type. This command takes the conditions for offering inside equipment.plist into account. Returns <code>true</code> if <code>[[#awardEquipment|awardEquipment()]]</code> is expected to succeed, <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#awardEquipment|awardEquipment()]]</code><br />
<br />
=== <code>becomeCascadeExplosion</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''becomeCascadeExplosion'''()<br />
This method causes the ship to explode as if it were hit by a quirium cascade.<br />
<br />
=== <code>broadcastCascadeImminent</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''broadcastCascadeImminent'''()<br />
This method causes the ship to broadcast a message to the AIs of all nearby ships warning them of an imminent cascade explosion. It is polite to call this a few seconds before calling <code>becomeCascadeExplosion</code><br />
<br />
=== <code>broadcastDistressMessage</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''broadcastDistressMessage'''()<br />
This method causes the ship to broadcast a distress message to the AIs of all nearby ships (received also by the player as a comms message). Ships receiving a distress message will often intervene in the fight, depending on their own AI and the roles of the ships already involved.<br />
<br />
=== <code>checkCourseToDestination</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''checkCourseToDestination'''()<br />
Checks the line between the ship's current position and its destination, and returns either null or an Entity (usually a planet, sun or other ship) that this ship would risk collision with if it travelled along that course.<br />
<br />
'''See also''': [[#getSafeCourseToDestination|getSafeCourseToDestination()]]<br />
<br />
=== <code>checkScanner</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''checkScanner'''([poweredOnly : Boolean]) : Array<br />
Runs a fast scanner check and returns the results. At most 32 objects within scanner range will be returned. If the <code>poweredOnly</code> parameter is present and set to true, then only powered objects will be returned (i.e. ships with a scan class other than CLASS_CARGO or CLASS_ROCK).<br />
<br />
This method is usually considerably quicker than [[Oolite_JavaScript_Reference:_System#filteredEntities|system.filteredEntities()]] and similar methods, with little loss of accuracy, though it is still advisable to cache the result for a while before re-scanning.<br />
<br />
=== <code>clearDefenseTargets</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''clearDefenseTargets'''()<br />
Clears the ship's list of point [[#defenseTargets|defense targets]].<br />
<br />
=== <code>commsMessage</code> ===<br />
function '''commsMessage'''(message : String [,target : Ship])<br />
Make the ship broadcast the specified message. Works on buoys and subentities as well as normal ships and stations. Messages are send to a maximum of 16 ships in range and always to the player when in range. When the optional target is used, the message goes only to that ship.<br />
<br />
=== <code>damageAssessment</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''damageAssessment'''() : Number<br />
Returns a number indicating the amount of damage or supply usage by this ship. Zero means that the ship is in excellent fighting condition, while higher numbers indicate increasing amounts of damage or supply shortages.<br />
<br />
=== <code>dealEnergyDamage</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''dealEnergyDamage'''(damage : Number, idealRange : Number [, velocityBias : Number])<br />
Deals damage to all ships within a sphere centred on this ship. If this ship has an owner (e.g. it is a missile or a subentity) the damage will be credited to its owner. Damage is dealt according to the following formula:<br />
* Further away than MAX_SCANNER_RANGE (25.6km): deal no damage<br />
* At or closer than <code>idealRange</code>: deal <code>damage</code> plus (or minus, for receding objects) <code>velocityBias</code> damage for every 0.001LM of relative closing speed, up to a maximum of 1.0LM<br />
* Between <code>idealRange</code> and a derived maximum range: calculate the damage that would have been done at <code>idealRange</code>, and then divide it by the square of the ratio of <code>idealRange</code> and the real range (i.e inverse-square). The derived maximum range is the distance where a target with no relative closing speed would take 1 point of damage.<br />
<br />
As an example, the standard Oolite missile uses <code>dealEnergyDamage(170, 32.5, 0.25)</code>, has a maximum speed of 0.75LM, and its AI tries to detonate it 25m from its target. Some worked examples (for comparision, one energy bank can absorb 64 points of damage, and a standard shield generator can absorb 128 points of damage):<br />
* The missile is fired at a stationary asteroid. It detonates at 25m, within the ideal range, and the relative closing speed is 0.75LM. The asteroid takes 170 + (0.25 * 750) = 357.5 points of damage<br />
* The missile is fired at a Cobra Mk III, which tries to flee from and evade the missile at its top speed of 0.35LM. The missile detonates at 25m, and the evasive manoeuvres mean that it is not heading directly at the Cobra when it detonates. The relative closing speed is 0.38LM. The Cobra takes 170 + (0.25 * 380) = 265 points of damage.<br />
* An Anaconda freighter travelling at 0.2LM fires a missile at a distant Fer-de-lance. After the missile has travelled 150m away from the Anaconda, it is hit by an ECM pulse from the FDL, and detonates. The relative velocity is -0.55LM (the missile is travelling away from the Anaconda), so the damage at the ideal range would be 170 - (0.25 * 550) = 32.5. The damage is then divided by (150 / 32.5)<sup>2</sup>, so the Anaconda takes about 1.5 points of damage.<br />
* A missile fired at something else detonates 500m away from a Sidewinder. The inverse-square rule divides the damage by (500 / 32.5)<sup>2</sup>, so the base damage at this range (ignoring velocityBias) is only 0.7. The Sidewinder is therefore safely outside the blast radius, and is not considered for damage. <br />
<br />
=== <code>deployEscorts</code> ===<br />
function '''deployEscorts'''()<br />
Cause a random number (at least 1 if possible) of the ship's escorts which are not already attacking a target to attack this ship's primary target, unless this function has already been called for the current target without meanwhile being called for a different target.<br />
<br />
=== <code>dockEscorts</code> ===<br />
function '''dockEscorts'''()<br />
Dock the ship’s deployed escorts, if any.<br />
<br />
=== <code>dumpCargo</code> ===<br />
function '''dumpCargo'''([amount : Number, commodity: String]) : Ship<br />
Ejects one item of cargo from the ship, and returns the cargo item. Returns <code>null</code> if the ship has no cargo, anything has been ejected in the last 0.5 seconds, or if sent to the player while docked.<br />
<br />
In 1.79 or later, multiple items may be scheduled for dumping by passing the number as a parameter.<br />
<br />
In 1.81 or later, a preferred commodity may be specified (if this is not present, a random item will be dumped as usual). This preference only applies to the first item dropped, not subsequent ones.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code><br />
<br />
=== <code>ejectItem</code> ===<br />
function '''ejectItem'''(role : String) : Ship<br />
Spawns a ship of role <code>role</code> immediately behind the ship, with a slight backwards velocity. (Note: an equal and opposite reaction is applied to the parent ship, so doing this with large ships is rarely useful. <code>player.ejectItem("station")</code> may seem funny, but don’t come running to me if you have someone’s eye out.) Returns the generated ship, or <code>null</code> if no ship is generated. The scanClass of the ejected item will always be CLASS_CARGO.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code><br />
<br />
=== <code>ejectSpecificItem</code> ===<br />
function '''ejectSpecificItem'''(itemKey : String) : Ship<br />
Spawns a ship with the ''shipdata.plist'' key <code>itemKey</code> immediately behind the ship, with a slight backwards velocity. The scanClass of the ejected item will always be CLASS_CARGO.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectItem|ejectItem]]</code><br />
<br />
=== <code>enterWormhole</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''enterWormhole'''([wormhole : Wormhole])<br />
If the player has entered witchspace, but before the old system is removed from memory, this method may be used to add this ship to the contents of the specified outbound wormhole. If no parameter is given, add them to the player's wormhole.<br />
<br />
If the player is not entering witchspace, this method does nothing: the ship must fly to the wormhole in the normal way to enter it.<br />
<br />
=== <code>equipmentStatus</code> ===<br />
function '''equipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]] [, multiple : Boolean]) : String or Object<br />
Tests whether the specified type of equipment is installed, and whether it is functioning. Returns one of the following strings: <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>, <code>"EQUIPMENT_UNAVAILABLE"</code> or <code>"EQUIPMENT_UNKNOWN"</code>.<br />
<br />
In 1.81 and later, if the optional <code>multiple</code> parameter is set to true, it will instead return an object in this format:<br />
{<br />
"EQUIPMENT_OK": 3.<br />
"EQUIPMENT_DAMAGED": 2<br />
}<br />
to allow equipments which allow fitting multiple to be queried. If multiple equipments can be fitted, not setting the 'multiple' parameter will return the 'best' state of all items of that type.<br />
<br />
'''See also:''' <code>[[#setEquipmentStatus|setEquipmentStatus()]]</code><br />
<br />
=== <code>exitAI</code> ===<br />
function '''exitAI'''()<br />
Exit the current AI, restoring the previous one. Equivalent to the <code>[[AI_methods|exitAI]]:</code> AI method. May not be used on player. Will generate a warning if there are no suspended AI states.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code><br />
<br />
=== <code>exitSystem</code> ===<br />
function '''exitSystem'''([targetSystem : Number]) : Boolean<br />
Cause the ship to jump out of the system, if possible. If <code>targetSystem</code> is specified, it will attempt to jump to the specified system, otherwise a random system within range is chosen.<br />
<br />
This method can fail for various reasons, in which case it returns <code>false</code>. It always fails for the player ship.<br />
<br />
=== <code>explode</code> ===<br />
function '''explode'''()<br />
Causes the ship to explode. Works on all ships, including the main station and the player except when docked.<br />
<br />
'''See also:''' <code>[[#remove|remove()]]</code><br />
<br />
=== <code>fireECM</code> ===<br />
function '''fireECM'''()<br />
activates an ecm burst, identical as the AI command.<br />
<br />
=== <code>findNearestStation</code> ===<br />
function '''findNearestStation'''()<br />
Returns the nearest Station entity to this ship. This is quicker than manually searching <code>system.stations</code> and much quicker than using <code>system.filteredEntities()</code>.<br />
<br />
=== <code>fireMissile</code> ===<br />
function '''fireMissile'''([missile]) : Ship<br />
fireMissile() will try to fire the first available missile and will return the missile fired, or <code>null</code> if no missiles can be fired at this time. It can take the optional missile identifier parameter, to allow for a specific missile to be fired. Missiles cannot be fired if the ship hasn’t got a valid target, or if the previous missile was launched less than <code>missile_load_time</code> seconds before. If a missile type was specified, and not found on the ship, no missile will be fired.<br />
<br />
=== <code>getSafeCourseToDestination</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''getSafeCourseToDestination'''()<br />
Returns some coordinates which can be flown to as an intermediate destination to allow travel between the ship's current position and its destination without colliding with any objects on the way. Use this if <code>checkCourseToDestination</code> returns an object you are unable or unwilling to destroy to calculate a new route.<br />
<br />
'''See also''': [[#checkCourseToDestination|checkCourseToDestination()]]<br />
<br />
=== <code>getMaterials</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''getMaterials'''() : Object<br />
getMaterials() returns the ship's current materials dictionary, or if none present an empty dictionary.<br />
<br />
'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code><br />
<br />
=== <code>getShaders</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''getShaders'''() : Object<br />
getShaders() returns the ship's current shaders dictionary, or if none present an empty dictionary.<br />
<br />
'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code><br />
<br />
=== <code>hasEquipmentProviding</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''hasEquipmentProviding'''(key : String)<br />
This method returns <code>true</code> if the ship has any equipment providing the <code>key</code> equipment type, and <code>false</code> otherwise.<br />
<br />
=== <code>hasRole</code> ===<br />
function '''hasRole'''(role : String)<br />
Returns <code>true</code> if the ship has <code>role</code> among its roles, <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#roles|roles]]</code><br />
<br />
=== <code>markTargetForFines</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''markTargetForFines()'''<br />
If this ship is eligible to give out fines and the primary target has a bounty, mark the current primary target for fines, which will need to be paid when the ship docks. If used on a ship other than the player, of course, the fines are not particularly meaningful.<br />
<br />
=== <code>notifyGroupOfWormhole</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''notifyGroupOfWormhole()'''<br />
Tells the ship's group about a wormhole (usually the one this ship has just entered). Causes a <code>wormholeSuggested</code> event to occur in the scripts of other group members.<br />
<br />
=== <code>offerToEscort</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''offerToEscort(mother : Ship)'''<br />
Offer to escort the specified ship. The ship making the offer must have the same scan class as the mothership and must have one of the designated escort roles. After the mothership has made a decision this ship will receive either an <code>escortAccepted</code> or <code>escortRejected</code> ship script event.<br />
<br />
=== <code>perform*</code> ===<br />
Each of these functions switches the frame-by-frame behaviour of the ship to a different mode. It may not necessarily remain in that mode, however - for example, those modes which require a target will usually fall back to idle mode if the target is lost.<br />
<br />
==== <code>performAttack</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performAttack()'''<br />
Attack the current target with available weapons.<br />
<br />
==== <code>performCollect</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performCollect()'''<br />
Attempt to scoop up the current target. If the current target is not scoopable, it will be lost.<br />
<br />
==== <code>performEscort</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performEscort()'''<br />
Escort the group leader. If this ship is not an escort of the group leader, it will not receive escort position updates from that ship.<br />
<br />
==== <code>performFaceDestination</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFaceDestination()'''<br />
Come to a stop, and turn to face the current destination coordinates.<br />
<br />
==== <code>performFlee</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFlee()'''<br />
Flee from the current target, using injectors if possible, until it is out of scanner range.<br />
<br />
==== <code>performFlyToRangeFromDestination</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFlyToRangeFromDestination()'''<br />
Fly to the current [[#destination|destination]] coordinates, stopping when the distance between the ship and those coordinates is the [[#desiredRange|desiredRange]]. If the ship is already closer to the destination coordinates than the desired range, it will move away from the coordinates.<br />
<br />
==== <code>performHold</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performHold()'''<br />
Come to a stop, and continually turn to face the current target<br />
<br />
==== <code>performIdle</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performIdle()'''<br />
Cancel any current turns to return to level flight, then move forward at current speed.<br />
<br />
==== <code>performIntercept</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performIntercept()'''<br />
Fly to intercept (i.e. ram) the current target.<br />
<br />
==== <code>performLandOnPlanet</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performLandOnPlanet()'''<br />
Land on rather than crash into the planet. This is a slow flight, so it is recommended to get close to the planet surface before activating this behaviour.<br />
<br />
==== <code>performMining</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performMining()'''<br />
Attack the current target with a mining laser. This does not count as hostile behaviour, so cannot be used except on rocks.<br />
<br />
==== <code>performScriptedAI</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performScriptedAI()'''<br />
Request flight instructions from a [[OXP_Scripted_AI|scripted AI]] callback each frame.<br />
<br />
==== <code>performScriptedAttackAI</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performScriptedAttackAI()'''<br />
Request flight instructions, including weapons fire, from a [[OXP_Scripted_AI|scripted AI]] callback each frame.<br />
<br />
==== <code>performStop</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performStop()'''<br />
Come to a complete halt<br />
<br />
==== <code>performTumble</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performTumble()'''<br />
Come to a complete halt and rotate randomly.<br />
<br />
=== <code>reactToAIMessage</code> ===<br />
function '''reactToAIMessage'''(message : String)<br />
Immediately perform the specified handler in the ship’s current AI state.<br />
<br />
'''See also:''' <code>[[#sendAIMessage|sendAIMessage()]]</code><br />
<br />
=== <code>recallDockingInstructions</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''recallDockingInstructions'''() : Object<br />
Returns the current docking instructions as an object, and sets the destination, desired range and desired speed to match the instructions. Use this if the ship may have been interrupted while docking to ensure its flight parameters are set correctly.<br />
<br />
'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#requestDockingInstructions|requestDockingInstructions]]</code><br />
<br />
=== <code>remove</code> ===<br />
function '''remove'''([suppressDeathEvent : Boolean])<br />
Immediately removes the ship from the universe. Works on all ships except the player, including the main station.<br>It generates a [[Oolite JavaScript Reference: ship script event handlers#shipRemoved|this.shipRemoved(suppressDeathEvent)]] event. By default it will also trigger a [[Oolite JavaScript Reference: ship script event handlers#shipDied|this.shipDied()]] event, unless <code>suppressDeathEvent</code> is true.<br />
<br />
'''See also:''' <code>[[#explode|explode()]]</code><br />
<br />
=== <code>removeCollisionException</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''removeCollisionException'''(exception : Ship)<br />
Allow this ship and the selected ship to collide again. See [[#collisionExceptions|collisionExceptions]] and [[#addCollisionException|addCollisionException]].<br />
<br />
Removing a collision exception which does not exist has no effect but will not cause an error.<br />
<br />
=== <code>removeDefenseTarget</code>===<br />
{{oolite-method-added|1.79}}<br />
function '''removeDefenseTarget'''(target : Ship)<br />
Ensures that the target ship is not on this ship's list of point [[#defenseTargets|defense targets]].<br />
<br />
=== <code>removeEquipment</code> ===<br />
function '''removeEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]])<br />
Removes the given piece of equipment from the ship.<br />
This function can also be used to remove missiles (and mines). If more than one missile of the same type is found on board, only one of them will be removed.<br />
<br />
Note that in Oolite prior to 1.76.1 there was a bug which could sometimes cause the game to crash if this function was used on pylon-mounted equipment. Therefore, if you do this in your OXP, you should set (at least) 1.76.1 as the version in requires.plist<br />
<br />
Example:<br />
ship.removeEquipment("EQ_ECM");<br />
<br />
=== <code>requestDockingInstructions</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''requestDockingInstructions'''() : Object<br />
Requests the next docking instructions from the station, and returns them as an object, setting the destination, desired range and desired speed to match the instructions. Use this to get the next step in the docking sequence after completing the previous one.<br />
<br />
'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code><br />
<br />
<br />
=== <code>requestHelpFromGroup</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''requestHelpFromGroup'''()<br />
This function sends the <code>helpRequestReceived</code> event to the other ships in this ship's group and escort group, sending the name of this ship's current target as the aggressor.<br />
<br />
=== <code>restoreSubEntities</code> ===<br />
function '''restoreSubEntities'''() : Boolean<br />
Recreate all destroyed or removed subentities of the ship. Returns <code>true</code> if any subentities were added. Whether or not any subentities were added, this will also reset all subentities to their original configuration of position, orientation and other properties.<br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#isFrangible|isFrangible]]</code><br />
<br />
=== <code>selectNewMissile</code> ===<br />
function '''selectNewMissile'''() : equipmentKey<br />
selectNewMissile() will automatically select a missile for a specific ship. It uses the missile_role shipdata.plist key to find out which missiles to select. As with the system populator, there's a small chance that missiles other than the missile_role specified in shipdata will be selected.<br />
e.g.<br />
this.ship.awardEquipment(this.ship.selectNewMissile())<br />
will automatically add the 'right type' of missile to a ship, i.e. one that its captain would normally choose.<br />
<br />
=== <code>sendAIMessage</code> ===<br />
function '''sendAIMessage'''(message : String)<br />
Add a message to the ship’s AI deferred message queue. Messages in the queue are handled immediately after the next periodic <code>UPDATE</code> message. Identical messages are coalesced.<br />
<br />
'''See also:''' <code>[[#reactToAIMessage|reactToAIMessage()]]</code><br />
<br />
=== <code>setAI</code> ===<br />
function '''setAI'''(AIName : String)<br />
Set the current AI, leaving the old one suspended. Equivalent to the <code>[[AI_methods|setAITo]]:</code> AI method. May not be used on player. From 1.79 onwards AI files may either be plist-based (with a .plist extension) or Javascript-based (with a .js extension).<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code><br />
<br />
=== <code>setBounty</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''setBounty'''(bounty : Number, reason : String)<br />
Sets the ship's bounty to the new value. <code>reason</code> will be sent to [[Oolite_JavaScript_Reference:_ship_script_event_handlers#shipBountyChanged|shipBountyChanged()]].<br />
<br />
'''See also:''' <code>[[#bounty|bounty]]</code><br />
<br />
=== <code>setCargo</code> ===<br />
function '''setCargo'''(commodity : String [, count : Number]) : Boolean<br />
Attempts to create <code>count</code> weight units of the commodity <code>commodity</code> for a cargo barrel. (Can not be used to set cargo for ships) When more units are defined than 1 ton, the count is reduced to one ton. It returns false when the selected commodity is unknown. If <code>count</code> is not specified, one will be assumed.<br />
<br />
=== <code>setCargoType</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setCargoType'''(commodityType : String) : Boolean<br />
Attempts to set the ship's cargo hold to contain cargo of the specified type, discarding any cargo already present. This should generally only be used immediately after a ship is spawned. Valid cargo types are:<br />
* '''SCARCE_GOODS''': goods which are likely to be rare in the current system, usually legal.<br />
* '''PLENTIFUL_GOODS''': goods which are likely to be plentiful in the current system, usually legal.<br />
* '''MEDICAL_GOODS''': narcotics (used for the Moray Medical Boat)<br />
* '''ILLEGAL_GOODS''': various goods likely to be rare in the current system, with a strong bias towards contraband<br />
* '''PIRATE_GOODS''': as ILLEGAL_GOODS, but the total amount carried will be lower<br />
This will return false if an unrecognised commodity type is used, and will throw an exception if used on a cargo pod rather than a cargo carrier. Using it on a ship like an Asp without a cargo hold is valid but pointless.<br />
<br />
=== <code>setCrew</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setCrew'''(Object) : Boolean<br />
Sets the ship's crew to one represented by the given object (or sets the ship to uncrewed if null is given as a parameter). Returns true if this succeeds, false otherwise (if the ship is ''always'' unpiloted). The object has the same keys as [[characters.plist]], all of which are optional and will be replaced with default values if unset. They are applied in the following order:<br />
* origin system<br />
* random seed<br />
* role<br />
* the rest<br />
You can therefore set a random seed or role to get particular behaviour, and use the other keys to override it.<br />
<br />
At the moment this function only sets the first crew member (the pilot of the ship)<br />
<br />
=== <code>setEquipmentStatus</code> ===<br />
function '''setEquipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]], statusKey : String)<br />
Changes the status of the given piece of equipment from the ship. The two only valid status keys are <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>.<br />
<br />
'''Note:''' by design, this method will throw an exception if called with an equipment type that does not exist. To test whether an equipment type exists, use <code>[[Oolite JavaScript Reference: EquipmentInfo#infoForKey|EquipmentInfo.infoForKey()]]</code>, which will return <code>null</code> for undefined equipment.<br />
<br />
'''See also:''' <code>[[#equipmentStatus|equipmentStatus()]]</code><br />
<br />
=== <code>setMaterials</code> ===<br />
function '''setMaterials'''(materialDictionary : Object [, shaderDictionary : Object]) : Boolean<br />
Set the materials of the ship’s model. This works exactly like the <code>materials</code> dictionary in [[shipdata.plist]]. The optional <code>shaderDictionary</code> argument overrides <code>materialDictionary</code> if shaders are active.<br />
<br />
'''Example:'''<br />
this.ship.setMaterials({"my_ship_diffuse.png": { diffuse_map: "my_ship_damaged_diffuse.png" }});<br />
<br />
'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code><br />
<br />
=== <code>setScript</code> ===<br />
function '''setScript'''(scriptName : String)<br />
Set, or completely replace, the javascript code associated to a ship entity.<br />
<br />
=== <code>setShaders</code> ===<br />
function '''setShaders'''(shaderDictionary : Object) : Boolean<br />
Set the shader materials of the ship’s model. Equivalent to <code>[[#setMaterials|setMaterials()]]</code> with the <code>materialDictionary</code> value set to the ship’s current material dictionary.<br />
<br />
'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code><br />
<br />
=== <code>spawn</code> ===<br />
function '''spawn'''(role : String [, count : Number]) : Array<br />
Attempts to create <code>count</code> (maximum: 64) ships of role <code>role</code> close to the ship – specifically, inside the ship’s collision radius. (Since creating ships may fail, the number created may be less than <code>count</code>). The created ships are returned in an array. If <code>count</code> is not specified, one will be assumed.<br />
<br />
<code>spawn()</code> is intended for cases when a ship splits into multiple parts or drops parts. In particular, it has the following special behaviour:<br />
* The spawned ships inherit most of the temperature of the parent.<br />
* If the parent is a missile and a child has the <code>[[shipdata.plist#is_submunition|is_submunition]]</code> property, the child will be considered a missile, its target will be set to that of the parent and the child’s owner will be set to the parent.<br />
* <code>spawn()</code> does not set up escorts for the new ships, or generate witchspace effects, or do any special AI handling.<br />
<br />
=== <code>spawnOne</code> ===<br />
function '''spawnOne'''(role : String) : Ship<br />
Convenience method which calls <code>[[#spawn|spawn]](role)</code> and returns the first element of the resulting array, or <code>null</code> if <code>spawn()</code> fails.<br />
<br />
=== <code>switchAI</code> ===<br />
function '''switchAI'''(AIName : String)<br />
Set the current AI, exiting the old one. Equivalent to the <code>[[AI_methods|switchAITo]]:</code> AI method. May not be used on player.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#exitAI|exitAI()]]</code><br />
<br />
=== <code>threatAssessment</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''threatAssessment'''(full : Boolean) : Number<br />
Returns a number indicating the relative strength of the ship. If the 'full' parameter is true, additional information will be considered as part of the assessment which would generally only be known by ships which know this ship or have seen it in combat. Otherwise, only data which could reasonably be expected to be common knowledge based on the class of the ship will be included.<br />
<br />
For example, which weapon facings are available is part of the basic assessment, but what forward laser the ship has is part of the full assessment.<br />
<br />
=== <code>throwSpark</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''throwSpark'''()<br />
Sets the ship to throw a spark as if it was seriously damaged. If this ship is already scheduled to throw a spark, this does nothing.<br />
<br />
=== <code>updateEscortFormation</code> ===<br />
function '''updateEscortFormation'''()<br />
Request that the game updates the target positions for the ship’s escorts by calling the ship’s script’s <code>coordinatesForEscortPosition()</code> method.<br />
<br />
== Static Methods ==<br />
=== <code>keys</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''keys'''() : Array<br />
Returns all dataKeys of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.<br />
var dataKeysArray = Ship.keys();<br />
<br />
=== <code>keysForRole</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''keysForRole'''(role : String) : Array<br />
Returns all dataKeys of ships defined in all [[shipdata.plist]] which contains the given role.<br />
<br />
var role = "trader";<br />
var roleKeys = Ship.keysForRole( role );<br />
log("keysForRole", role + ": " + roleKeys );<br />
<br />
=== <code>roleIsInCategory</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''roles'''(role : String, category : String) : Boolean<br />
Returns whether the role given is in a particular category as defined in [[role-categories.plist]]<br />
<br />
Ship.roleIsInCategory("trader","oolite-pirate-victims"); // true<br />
<br />
=== <code>roles</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''roles'''() : Array<br />
Returns all roles of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.<br />
<br />
var roles = Ship.roles();<br />
for( var i = 0; i < roles.length; i++ ) {<br />
var roleKeys = Ship.keysForRole( roles[i] );<br />
log("roles", i + ". "+roles[i] + ": " + roleKeys );<br />
}<br />
<br />
=== <code>shipDataForKey</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''shipDataForKey'''(datakey : String) : Object<br />
Returns an object containing a representation of the raw [[shipdata.plist]] entry for a given data key, or null if the data key does not exist. Keys not defined in the shipdata.plist entry will not be defined in the object - they won't get their default values.<br />
<br />
Using the ship object properties is generally a better way to get this information, but this is useful if you want to find out what a ship might be like if you did add it.<br />
<br />
var shipdata = Ship.shipDataForKey("cobra3-trader");<br />
log("test",shipdata["name"]); // "Cobra Mark III"<br />
log("test",shipdata["ship_class_name"]); // undefined<br />
log("test",shipdata["ship_unique_name"]); // undefined<br />
log("test",shipdata["display_name"]); // undefined<br />
<br />
==See also==<br />
*[[Shipdata.plist]]<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Ship_script_event_handlers&diff=48449Oolite JavaScript Reference: Ship script event handlers2015-08-15T09:11:10Z<p>Cim: /* shipDumpedCargo */</p>
<hr />
<div>This page provides a list of event handlers which can be implemented by [[Scripting Oolite with JavaScript|JavaScript scripts for Oolite]].<br />
<br />
Ship scripts are linked to Oolite either using the appropriate [[shipdata.plist#script|shipdata.plist]] setting or via javascript using [[Oolite JavaScript Reference: Ship#setScript|ship.setScript]] and are only active when the ship is present. More than one ship can be assigned the same ship script. Each ship will create its own separate copy of the script, each one independent from the others.<br />
<br />
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.<br />
<br />
Note that a ship script event which affects the player ship (therefore not those marked NPC only, station only, etc.) will also appear as a [[Oolite JavaScript Reference: world_script_event_handlers|world script event]].<br />
<br />
In Oolite 1.79 onwards, each ship has two scripts: the "ship script" as in previous versions (<code>ship.script</code>) and an AI script (<code>ship.AIScript</code>) which manages [[Oolite_Javascript_AI|Javascript-based AI]]. The former is intended for constant events related to the ship itself, and the latter is intended for event handling which varies based on what the ship is currently doing. Both scripts receive all events which do not expect a return value. Events expecting a return value are sent to the ship script ''only''.<br />
<br />
=== Docking ===<br />
<br />
==== <code>shipWillDockWithStation</code> ====<br />
<br />
The <code>shipWillDockWithStation</code> handler is called at the beginning of the docking tunnel effect.<br />
<br />
this.shipWillDockWithStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
At this moment "ship.dockedStation == nil", "ship.status == STATUS_DOCKING"<br />
<br />
<br />
==== <code>shipDockedWithStation</code> ====<br />
<br />
The <code>shipDockedWithStation</code> handler is called at the end of the docking tunnel effect.<br />
<br />
this.shipDockedWithStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
At this moment "ship.dockedStation == the station", "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.<br />
<br />
<br />
==== <code>shipWillLaunchFromStation</code> ====<br />
This handler was added for npc ships with test release 1.75, before it was a worldScript only handler.<br />
<br />
The <code>shipWillLaunchFromStation</code> handler is called for ship scripts on ship creation, before the shipSpawned event. <br />
<br />
this.shipWillLaunchFromStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLaunchedFromStation</code> ====<br />
<br />
The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tract, when the ship has clearly left the station and AI updating begins.<br />
<br />
this.shipLaunchedFromStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationWithdrewDockingClearance</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>stationWithdrewDockingClearance</code> handler is received when the station the ship is trying to dock with unexpectedly withdraws clearance (e.g. if <code>station.abortAllDockings</code> is called).<br />
<br />
this.stationWithdrewDockingClearance = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
=== Witchspace Jumps ===<br />
<br />
==== <code>playerWillEnterWitchspace</code> ====<br />
<br />
The <code>playerWillEnterWitchspace</code> handler is called just before a witchspace jump starts and after the <code>shipWillEnterWitchspace</code> handler fires. It is send to all ships in the system to signal that the player is about to leave the system. (By jump or by wormhole)<br />
<br />
this.playerWillEnterWitchspace = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedWormhole</code> ====<br />
<br />
The <code>shipExitedWormhole</code> handler is called when a ship exits a wormhole.<br />
<br />
this.shipExitedWormhole = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipWillEnterWormhole</code> ====<br />
<br />
The <code>shipWillEnterWormhole</code> handler is called when a ship enters a wormhole. only<br />
<br />
this.shipWillEnterWormhole = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>shipWitchspaceBlocked</code> ====<br />
{{oolite-method-added|1.79}}<br />
<br />
The <code>shipWitchspaceBlocked</code> handler is called when a ship is prevented from entering witchspace by the presence of a nearby large mass. The blocking object is passed as a parameter<br />
<br />
this.shipWitchspaceBlocked = function(blocker)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>wormholeSuggested</code> ====<br />
{{oolite-method-added|1.79}}<br />
<br />
The <code>wormholeSuggested</code> handler is called when another ship enters witchspace and suggests that this ship follows. The wormhole used is passed as a parameter. This is most commonly called when a group leader enters witchspace and wishes to take its escorts with it.<br />
<br />
this.wormholeSuggested = function(wormhole)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Enter/Exit Aegis ===<br />
<br />
==== <code>shipEnteredStationAegis</code> ====<br />
<br />
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.<br />
<br />
this.shipEnteredStationAegis = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedStationAegis</code> ====<br />
<br />
The <code>shipExitedStationAegis</code> handler is called when the player leaves the aegis of the main-station (2x scanner range from main-station).<br />
<br />
this.shipExitedStationAegis = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipEnteredPlanetaryVicinity</code> ====<br />
<br />
The <code>shipEnteredPlanetaryVicinity</code> handler is called when the player enters the planet aegis (3x planet radius).<br />
<br />
this.shipEnteredPlanetaryVicinity = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedPlanetaryVicinity</code> ====<br />
<br />
The <code>shipExitedPlanetaryVicinity</code> handler is called when the player leaves the planet aegis (3x planet radius).<br />
<br />
this.shipExitedPlanetaryVicinity = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipApproachingPlanetSurface</code> ====<br />
<br />
The <code>shipApproachingPlanetSurface</code> handler is called when the player is very close to the planet (crosses a border ± 500 meter above the surface).<br />
<br />
this.shipApproachingPlanetSurface = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLeavingPlanetSurface</code> ====<br />
<br />
The <code>shipLeavingPlanetSurface</code> handler is called when the player leaves the planet (crosses a border ± 500 meter above the surface).<br />
<br />
this.shipLeavingPlanetSurface = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Combat ===<br />
<br />
==== <code>cascadeWeaponDetected</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>cascadeWeaponDetected</code> handler fires when a Q-bomb (or equivalent device) detonates within scanner range of the player. The stock Q-mine (and potentially OXP equivalents) will also send this handler at the start of the countdown, giving ships more time to react. The weapon entity will be passed as a parameter.<br />
<br />
this.cascadeWeaponDetected = function(weapon)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>defenseTargetDestroyed</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>defenseTargetDestroyed</code> handler is sent when a defense (i.e. secondary) target is destroyed. A reference to the destroyed ship (which will become invalid shortly) is passed as a parameter.<br />
<br />
this.defenseTargetDestroyed = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>escortAttack</code> ====<br />
<br />
The <code>escortAttack</code> handler is sent to all escorts of a mothership that are deployed. The mother first changes the escorts AI to interceptAI.plist and also sets the escort target to his own target before sending this handler to the escorts.<br />
<br />
this.escortAttack = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>helpRequestReceived</code> ====<br />
{{oolite-method-added|1.79}}<br />
<br />
The <code>helpRequestReceived</code> handler is sent when an ally of this ship is being attacked and requires help. There are two parameters, the ally and the enemy.<br />
<br />
this.helpRequestReceived = function(ally, enemy)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAttackedOther</code> ====<br />
The <code>shipAttackedOther</code> handler is called when this ship hits another with a laser shot. <code>other</code> is the identity of the ship being hit (added in test version 1.74.2).<br />
<br />
this.shipAttackedOther = function(other)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAttackedWithMissile</code> ====<br />
<br />
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.<br />
<br />
this.shipAttackedWithMissile = function(missile, whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAttackerDistracted</code> ====<br />
<br />
The <code>shipAttackerDistracted</code> handler is called when the ship's current attacker is distracted by another ship. <code>whom</code> contains the ship which is doing the distracting.<br />
<br />
this.shipAttackerDistracted = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBeingAttacked</code> ====<br />
<br />
The <code>shipBeingAttacked</code> handler is called when a laser shot hits. <code>whom</code> the identity of the ship that attacked.<br />
<br />
this.shipBeingAttacked = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBeingAttackedByCloaked</code> ====<br />
<br />
The <code>shipBeingAttackedByCloaked</code> handler is called when a laser shot from a cloaked ship hits. There is no parameter provided to identify the cloaked ship.<br />
<br />
this.shipBeingAttackedByCloaked = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBeingAttackedUnsuccessfully</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>shipBeingAttackedUnsuccessfully</code> handler is called when a laser shot narrowly misses the ship, when fired by an uncloaked ship intending to hit. <code>whom</code> the identity of the ship that attacked.<br />
<br />
this.shipBeingAttackedUnsuccessfully = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCloakActivated</code> ====<br />
<br />
The <code>shipCloakActivated</code> handler is called whenever the script's target ship activates its cloaking device. No parameters are required for this handler (added in test version 1.74).<br />
<br />
this.shipCloakActivated = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCloakDeactivated</code> ====<br />
<br />
The <code>shipCloakDeactivated</code> handler is called whenever the script's target ship deactivates its cloaking device. No parameters are required for this handler (added in test version 1.74).<br />
<br />
this.shipCloakDectivated = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetDestroyed</code> ====<br />
<br />
The <code>shipTargetDestroyed</code> handler is called when the target gets destroyed by this ship. <code>target</code> contains the destroyed target entity. This command is always preceded by the <code>shipTargetLost</code> handler.<br />
<br />
this.shipTargetDestroyed = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipDied</code> ====<br />
<br />
The <code>shipDied</code> handler is called when the ship or player dies.<br />
<br />
this.shipDied = function(whom, why)<br />
{<br />
// Your code here<br />
}<br />
'''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".<br><br />
("cascade weapon" is new in 1.74 and "removed" / "energy damage" were accidentally switched in 1.73)<br />
<br />
==== <code>shipEnergyBecameFull </code> ====<br />
<br />
The <code>shipEnergyBecameFull </code> handler is called when the energy level reaches its maximum value again. <br />
<br />
this.shipEnergyBecameFull = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipEnergyIsLow</code> ====<br />
<br />
The <code>shipEnergyIsLow</code> handler is called every time when a ship gets energy damage while the energy level lies below 25% of its maximum value.<br />
<br />
this.shipEnergyIsLow = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipHitByECM</code> ====<br />
<br />
The <code>shipHitByECM</code> handler is called when a ship receives a ECM pulse. <code>pulsesRemaining</code> contains the number of pulses that still have to be send by the sending ship. When a ship activates his ecm, he will send 4 pulses with 0.5 seconds interval and increasing range.: 6400 --> 12800 --> 19200 --> 25600. (Handler added in test version 1.71)<br />
<br />
this.shipHitByECM = function(pulsesRemaining)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipFiredMissile</code> ====<br />
<br />
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. (Handler added in test version 1.74)<br />
<br />
this.shipFiredMissile = function(missile, target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipKilledOther</code> ====<br />
<br />
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. (Handler added in test version 1.75) <br />
<br />
this.shipKilledOther = function(whom,damageType)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetAcquired</code> ====<br />
<br />
The <code>shipTargetAcquired</code> handler is called whenever a new target is selected. (Handler added in test version 1.74) <br />
<br />
this.shipTargetAcquired = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetCloaked</code> ====<br />
<br />
The <code>shipTargetCloaked</code> handler is called when the target cloakes.<br />
<br />
this.shipTargetCloaked = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetLost</code> ====<br />
<br />
The <code>shipTargetLost</code> handler is called when the target gets lost. <code>target</code> contains the lost target entity.<br>(Handler introduced in 1.74 as replacement with consistent name for the old handler: 'shipLostTarget'.)<br />
<br />
this.shipTargetLost = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTakingDamage</code> ====<br />
<br />
The <code>shipTakingDamage</code> handler is called when a ship sustains damage. Handler is added in Oolite 1.75<br><br />
It transfers the <code>amount</code> of damage, <code>who</code> caused the damage and the <code>type</code> of damage.<br />
<br />
For the player ship, only damage not absorbed by the shields will appear in <code>amount</code>, but the handler will be called anyway with zero as the amount if the shields absorb all the damage.<br />
<br />
this.shipTakingDamage = function(amount, whom, type)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Miscellaneous ===<br />
<br />
==== <code>cargoDumpedNearby</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>cargoDumpedNearby</code> handler is sent when a nearby ship - not this ship - dumps a cargo pod.<br />
<br />
this.cargoDumpedNearby = function(cargo: ship, releasedBy: ship)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>commsMessageReceived</code> ====<br />
<br />
The <code>commsMessageReceived</code> handler is sent when receiving a message from other ships. Handler is added in Oolite 1.75<br />
<br />
this.commsMessageReceived = function(message: string, sender: ship)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>distressMessageReceived</code> ====<br />
<br />
The <code>distressMessageReceived</code> handler is sent when receiving a distress message from other ships. Handler is added in Oolite 1.75<br />
<br />
this.distressMessageReceived = function(aggressor: ship, sender: ship)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>equipmentAdded</code> ====<br />
{{Oolite-method-added|1.81}}<br />
The <code>equipmentAdded</code> handler is called whenever a 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.<br />
<br />
this.equipmentAdded = function(equipmentKey)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>equipmentRemoved</code> ====<br />
{{Oolite-method-added|1.81}}<br />
The <code>equipmentRemoved</code> handler is called whenever a 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.<br />
<br />
this.equipmentAdded = function(equipmentKey)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAchievedDesiredRange</code> ====<br />
{{Oolite-method-added|1.79}}<br />
The <code>shipAchievedDesiredRange</code> handler is called when the ship reaches the desired range from its destination during certain flight behaviours.<br />
<br />
this.shipAchievedDesiredRange = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAIFrustrated</code> ====<br />
{{Oolite-method-added|1.79}}<br />
The <code>shipAIFrustrated</code> handler is called when the ship's low-level behaviour is unable to achieve the desired result (e.g. a <code>performFlee</code> request is not getting further from the target). A short string describing the context of the frustration is passed as a parameter.<br />
<br />
this.shipAIFrustrated = function(context)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBountyChanged</code> ====<br />
{{Oolite-method-added|1.77}}<br />
<br />
The <code>shipBountyChanged</code> handler is sent when an event tries to change the bounty level of the ship. <code>delta</code> may be zero, positive or negative. <code>reason</code> is a string that may either contain a standard value or a custom value set by an OXP. The standard values are:<br />
* '''setup actions''': Bounty level settings in the system populator or as a side effect of launching a ship from a station with a particular role.<br />
* '''scripted''': OXP scripted changes to bounties, with no specified cause.<br />
* '''attacked police''': The ship attacked a police ship<br />
* '''attacked main station''': The ship attacked the main station<br />
* '''attacked innocent''': The ship attacked a Clean ship and was seen doing so<br />
* '''seen by police''': The ship was seen by police committing a crime<br />
* '''distress call''': A police ship responded to a distress call from a ship that this ship is attacking<br />
* '''illegal exports''': The ship launched from a main station while carrying illegal goods (player only)<br />
* '''assisting offenders''': The bounty adjustment applied when a clean ship escorts an offender, or vice versa (NPC only)<br />
* '''new galaxy''': The ship entered a new galaxy (player only)<br />
* '''new system''': The ship entered a new system<br />
* '''paid fine''': The ship was marked for fines by police, and then paid them on docking (player only)<br />
* '''escape pod''': The ship is a replacement ship from escape pod insurance (player only)<br />
* '''assisting police''': The ship helped out a police ship in combat<br />
* '''unknown''': The bounty changed for an unknown reason. This should not occur.<br />
<br />
this.shipBountyChanged = function(delta,reason)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCloseContact</code> ====<br />
<br />
The <code>shipCloseContact</code> handler is sent when approaching otherShip and when "track_contacts" in shipData is true.<br />
<br />
this.shipCloseContact = function(otherShip)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCollided</code> ====<br />
<br />
The <code>shipCollided</code> handler is sent after a collision with otherShip.<br />
<br />
this.shipCollided = function(otherShip)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipDumpedCargo</code> ====<br />
{{oolite-method-added|1.83}}<br />
<br />
The <code>shipDumpedCargo</code> handler is sent when this ship dumps a cargo pod.<br />
<br />
this.shipDumpedCargo = function(cargo: ship)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipNowFacingDestination</code> ====<br />
{{Oolite-method-added|1.79}}<br />
The <code>shipNowFacingDestination</code> handler is called when the ship is facing its destination during certain flight behaviours.<br />
<br />
this.shipNowFacingDestination = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipReachedEndPoint</code> ====<br />
<br />
The <code>shipReachedEndPoint</code> handler is sent after reaching the last navigation point when in mode <code>performFlyRacepoints</code>.<br />
<br />
shipReachedEndPoint = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipReachedNavPoint</code> ====<br />
<br />
The <code>shipReachedNavPoint</code> handler is sent after reaching a navigation point when in mode <code>performFlyRacepoints</code>.<br />
<br />
this.shipReachedNavPoint = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipScoopedOther</code> ====<br />
<br />
The <code>shipScoopedOther</code> handler is called when a ship scoops scripted_cargo. ("cargo_type" = CARGO_SCRIPTED_ITEM) Other cargo, even scooping escapepods, doesn't trigger a handler.<br>The scooped item is transferred as argument. The scooped cargo itselfs gets the handler: <code>shipWasScooped</code> with the scooper as argument. Starting with Oolite 1.77 this handler will fire on every scooped object.<br />
<br />
this.shipScoopedOther = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLaunchedEscapePod</code> ====<br />
<br />
The <code>shipLaunchedEscapePod</code> handler is called when the pilot bails out. This will be followed by a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds when it is the player that is ejecting.<br />
<br />
this.shipLaunchedEscapePod = function(escapepod, passengers)<br />
{<br />
// Your code here<br />
}<br />
<br />
<code>escapepod</code> contains the main pod with the pilot. <code>passengers</code> will be added with Oolite 1.77 and is an array with passenger pods for those ships that have more than one escape-capsule defined.<br />
<br />
=== NPC only ===<br />
<br />
==== <code>aiAwoken</code> ====<br />
{{oolite-method-added|1.79}}<br />
This is sent to the ship periodically when <code>ship.AIScriptWakeTime</code> passes. One of the actions of this handler should be to cause a new wake time to be set. It is received by both the ship script and the AI script but usually only of interest to the latter.<br />
<br />
==== <code>aiStarted</code> ====<br />
{{oolite-method-added|1.79}}<br />
This is sent to the ship when a new Javascript-based AI is loaded. The AI Script should then use it to do initialisation. The ship script can usually ignore it.<br />
<br />
==== <code>coordinatesForEscortPosition</code> ====<br />
<br />
The <code>coordinatesForEscortPosition</code> handler fires whenever the game engine wishes to know the positions of escorts relative to their group leader, and fires in the group leader's ship script at that time. It is given two parameters: the number of the escort, and the maximum number of escorts the group leader might have (which is not necessarily the number of escorts it currently has, of course). Unlike most ship script handlers, which return void, ''this handler is required to return a Vector'' (or a value equivalent to a Vector) describing the relative position of the escort to the mothership.<br />
<br />
coordinatesForEscortPosition = function(num,max)<br />
{<br />
// Your code here<br />
return escort_position;<br />
}<br />
<br />
The escort position is relative to the mothership, and in the mothership's coordinate system. For example, to place an escort 500m to the right of the mothership, return <code>new Vector(500, 0, 0);</code>. You are responsible for ensuring that there is sufficient space between the escorts and the mothership, and between any pair of escorts, or they will spend most of their time trying to avoid collisions with each other. If you intend to use the same ship script on several ships of varying sizes, you may wish to include the mothership's [[Oolite_JavaScript_Reference:_Entity#collisionRadius|collisionRadius]] in the calculations.<br />
<br />
Placing escorts directly ahead of the mothership (e.g. <code>new Vector(0, 0, 500);</code>) or too close to the mothership will trigger collision warnings for the mothership, making it difficult to maintain level flight for any significant time.<br />
<br />
==== <code>entityDestroyed</code> ====<br />
<br />
The <code>entityDestroyed</code> handler fires immediately ''after'' the ship becomes invalid, regardless of the reason, except when the game restarts. This is the best place for all kind of 'clean-up' code, for example stopping [[Oolite_JavaScript_Reference:_Timer|Timers]] associated with the ship script. (Added with Oolite 1.75.1)<br />
<br />
entityDestroyed = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>escortAccepted</code> ====<br />
<br />
The <code>escortAccepted</code> handler is called when a mother ship accepts this ship as an escort. The mothership simultaneously gets a <code>shipAcceptedEscort</code> event.<br />
<br />
this.escortAccepted = function(mothership)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>escortDock</code> ====<br />
<br />
The <code>escortDock</code> handler is called by a mother ships that uses the AI command: <code>dockEscorts</code>. Escorts are instructed to change AI into dockingAI.plist and enter the ABORT state of this AI after a certain delay. Than this event is send to all his escorts, each with a different delay with 3 seconds spacing.<br />
<br />
this.escortDock = function(delay)<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>escortRejected</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>escortRejected</code> handler is called when a mother ship rejects this ship as an escort.<br />
<br />
this.escortRejected = function(mothership)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>offenceCommittedNearby</code> ====<br />
<br />
The <code>offenceCommittedNearby</code> handler is only send to police ships in scanner range of a hostile action. It transfers the attacker and the victim to the police vessel.<br />
<br />
this.offenceCommittedNearby = function(attacker, victim)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>scriptedAI</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>scriptedAI</code> handler is called each frame while the ship's AI is in "performScriptedAI" or "performScriptedAttackAI" mode. It must return an object defining the ship's flight parameters. The <code>delta</code> parameter is the length of the current frame in seconds. [[OXP_Scripted_AI|More information on using this functionality]]<br />
<br />
this.scriptedAI = function(delta)<br />
{<br />
// Your code here<br />
return flightParameters;<br />
}<br />
<br />
==== <code>shipAcceptedEscort</code> ====<br />
<br />
The <code>shipAcceptedEscort</code> handler is called when this ship accepts a new ship as an escort. The escort simultaneously gets a <code>escortAccepted</code> event. <br />
<br />
this.shipAcceptedEscort = function(newEscort)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLandedOnPlanet</code> ====<br />
<br />
The <code>shipLandedOnPlanet</code> handler is called for ships landing on a planet. It transfers the <code>planet</code> parameter. (Will be added with Oolite 1.77)<br />
<br />
shipLandedOnPlanet = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipRemoved</code> ====<br />
<br />
The <code>shipRemoved</code> handler is called for ships removed by script. It transfers the <code>suppressDeathEvent</code> parameter so the script knows if there will also follow a shipDied() event.<br />
<br />
shipRemoved = function(suppressDeathEvent)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipSpawned</code> ====<br />
<br />
The <code>shipSpawned</code> handler is called for newly added ships. It does not trigger on adding but on the first update after adding. On a witchspace jump it means that first all ships are added to the system, then afterwards all the shipSpawned() events are triggered. Note that this is not called for subentities - if subentities need specific set up running, this must be called from the main ship's handler.<br />
<br />
this.shipSpawned = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>spawnedAsEscort</code> ====<br />
<br />
The <code>spawnedAsEscort</code> handler is called for newly added escort ships. It does trigger on adding the ship and before the shipSpawned() handlers is activated. It has the mothership as argument. <br />
<br />
this.spawnedAsEscort = function(mother)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipWasDumped</code> ====<br />
<br />
The <code>shipWasDumped</code> handler is sent to the cargopod when a ship jettisons it. The dumping ship is transferred as the argument. <br />
<br />
this.shipWasScooped = function(dumper)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipWasScooped</code> ====<br />
<br />
The <code>shipWasScooped</code> handler is send to the cargopod when a ship scoops scripted_cargo. ("cargo_type" = CARGO_SCRIPTED_ITEM) The scooper is transferred as argument. The scooper itself gets a trigger on the handler <code>shipScoopedOther</code>.<br />
<br />
this.shipWasScooped = function(scooper)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Stations only ===<br />
<br />
==== <code>alertConditionChanged</code> ====<br />
<br />
The <code>alertConditionChanged</code> handler is called when a station's alert status ([[Oolite_JavaScript_Reference:_Station#alertCondition|Station.alertCondition]]) changes. Only the player and stations have an alert condition. The equivalent player event is handled inside [[Oolite_JavaScript_Reference:_world_script_event_handlers|world scripts]].<br />
<br />
this.alertConditionChanged = function(newCondition, oldCondition)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>otherShipDocked</code> ====<br />
<br />
The <code>otherShipDocked</code> handler is called with a station script only, when an ship docks. It has the docked ship as argument.<br />
<br />
this.otherShipDocked = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationDockingQueuesAreEmpty</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>stationDockingQueuesAreEmpty</code> handler is called when the last ship in the queues docks with the station (or gives up docking and leaves).<br />
<br />
this.stationDockingQueuesAreEmpty = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationLaunchedShip</code> ====<br />
<br />
The <code>stationLaunchedShip</code> handler is called with a station script only, when a ship launches. It has the launched ship as argument.<br><br />
<br />
this.stationLaunchedShip = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationAcceptedDockingRequest</code> ====<br />
{{oolite-method-added|1.81}}<br />
The <code>stationReceivedDockingRequest</code> handler is called when a ship has requested docking clearance and has been allocated a dock. Due to the way in which docking clearance works, this is likely to be called several times for the same ship as it moves through the docking sequence.<br />
<br />
this.stationReceivedDockingRequest = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationReceivedDockingRequest</code> ====<br />
{{oolite-method-added|1.81}}<br />
The <code>stationReceivedDockingRequest</code> handler is called when a ship requests docking clearance. The ship requesting is passed as a parameter. This is often necessary for carriers which will need to come to a stop before ships can dock with them. Due to the way in which docking clearance works, this is likely to be called several times for the same ship as it moves through the docking sequence.<br />
<br />
this.stationReceivedDockingRequest = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
(note: a handler by this name was present in 1.79 and 1.80, but was called at the wrong time and should not be used. Set a minimum version of 1.81 if you use this event handler)<br />
<br />
==== <code>willOpenDockingPortFor</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>willOpenDockingPortFor</code> handler is called with a station script only, when a ship requests docking, in cases where a dock is set to generally disallow docking (i.e. [[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsDocking]] is false). It returns a Boolean:<br />
* if it returns false (or this function isn't defined), this dock will not be opened later for the requesting ship, and it should not try again.<br />
* if it returns true, this dock will be opened later for the requesting ship, and it should try again later if it cannot find another suitable dock on this station.<br />
The handler is passed the identity of the dock and the requesting ship<br />
<br />
this.willOpenDockingPortFor = function(dock, ship)<br />
{<br />
// Your code here<br />
return allow;<br />
}<br />
<br />
=== Docks Only ===<br />
{{oolite-method-added|1.77}}<br />
<br />
==== acceptDockingRequestFrom ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>acceptDockingRequestFrom</code> handler is called when a ship is looking for docking clearance from the station, and is considering this dock. To get as far as calling this handler, the dock must have [[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsDocking]] true, and be large enough to physically fit the ship.<br />
<br />
It returns a boolean: true to accept the request (which, depending on docking queue lengths will not necessarily mean that this dock is the one that the ship heads for), and false to reject the request. 'true' is assumed if this handler is not defined.<br />
<br />
This handler may be called multiple times for the same ship if the ship is having difficulty finding a suitable docking queue.<br />
<br />
this.acceptDockingRequestFrom = function(ship)<br />
{<br />
// Your code here<br />
return allow;<br />
}<br />
<br />
==== acceptLaunchingRequestFrom ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>acceptLaunchingRequestFrom</code> handler is called when a ship is looking for launching clearance from the station, and is considering this dock. To get as far as calling this handler, the dock must have [[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsLaunching]] true, and be large enough to physically fit the ship (unless the ship is the player).<br />
<br />
It returns a boolean: true to accept the request (which, depending on launching queue lengths will not necessarily mean that this dock is the one that the ship uses), and false to reject the request. 'true' is assumed if this handler is not defined.<br />
<br />
this.acceptLaunchingRequestFrom = function(ship)<br />
{<br />
// Your code here<br />
return allow;<br />
}<br />
<br />
<br />
<br />
<br />
<br />
=== Missing Events ===<br />
<br />
All initially planned events have a corresponding event handler in v1.74.<br />
<br />
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].<br />
<br />
'''See also:''' [[Oolite JavaScript Reference: world_script_event_handlers|world_script_event_handlers]]<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Ship_script_event_handlers&diff=48448Oolite JavaScript Reference: Ship script event handlers2015-08-15T09:09:51Z<p>Cim: /* Miscellaneous */ shipDumpedCargo in 1.83</p>
<hr />
<div>This page provides a list of event handlers which can be implemented by [[Scripting Oolite with JavaScript|JavaScript scripts for Oolite]].<br />
<br />
Ship scripts are linked to Oolite either using the appropriate [[shipdata.plist#script|shipdata.plist]] setting or via javascript using [[Oolite JavaScript Reference: Ship#setScript|ship.setScript]] and are only active when the ship is present. More than one ship can be assigned the same ship script. Each ship will create its own separate copy of the script, each one independent from the others.<br />
<br />
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.<br />
<br />
Note that a ship script event which affects the player ship (therefore not those marked NPC only, station only, etc.) will also appear as a [[Oolite JavaScript Reference: world_script_event_handlers|world script event]].<br />
<br />
In Oolite 1.79 onwards, each ship has two scripts: the "ship script" as in previous versions (<code>ship.script</code>) and an AI script (<code>ship.AIScript</code>) which manages [[Oolite_Javascript_AI|Javascript-based AI]]. The former is intended for constant events related to the ship itself, and the latter is intended for event handling which varies based on what the ship is currently doing. Both scripts receive all events which do not expect a return value. Events expecting a return value are sent to the ship script ''only''.<br />
<br />
=== Docking ===<br />
<br />
==== <code>shipWillDockWithStation</code> ====<br />
<br />
The <code>shipWillDockWithStation</code> handler is called at the beginning of the docking tunnel effect.<br />
<br />
this.shipWillDockWithStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
At this moment "ship.dockedStation == nil", "ship.status == STATUS_DOCKING"<br />
<br />
<br />
==== <code>shipDockedWithStation</code> ====<br />
<br />
The <code>shipDockedWithStation</code> handler is called at the end of the docking tunnel effect.<br />
<br />
this.shipDockedWithStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
At this moment "ship.dockedStation == the station", "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.<br />
<br />
<br />
==== <code>shipWillLaunchFromStation</code> ====<br />
This handler was added for npc ships with test release 1.75, before it was a worldScript only handler.<br />
<br />
The <code>shipWillLaunchFromStation</code> handler is called for ship scripts on ship creation, before the shipSpawned event. <br />
<br />
this.shipWillLaunchFromStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLaunchedFromStation</code> ====<br />
<br />
The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tract, when the ship has clearly left the station and AI updating begins.<br />
<br />
this.shipLaunchedFromStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationWithdrewDockingClearance</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>stationWithdrewDockingClearance</code> handler is received when the station the ship is trying to dock with unexpectedly withdraws clearance (e.g. if <code>station.abortAllDockings</code> is called).<br />
<br />
this.stationWithdrewDockingClearance = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
=== Witchspace Jumps ===<br />
<br />
==== <code>playerWillEnterWitchspace</code> ====<br />
<br />
The <code>playerWillEnterWitchspace</code> handler is called just before a witchspace jump starts and after the <code>shipWillEnterWitchspace</code> handler fires. It is send to all ships in the system to signal that the player is about to leave the system. (By jump or by wormhole)<br />
<br />
this.playerWillEnterWitchspace = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedWormhole</code> ====<br />
<br />
The <code>shipExitedWormhole</code> handler is called when a ship exits a wormhole.<br />
<br />
this.shipExitedWormhole = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipWillEnterWormhole</code> ====<br />
<br />
The <code>shipWillEnterWormhole</code> handler is called when a ship enters a wormhole. only<br />
<br />
this.shipWillEnterWormhole = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>shipWitchspaceBlocked</code> ====<br />
{{oolite-method-added|1.79}}<br />
<br />
The <code>shipWitchspaceBlocked</code> handler is called when a ship is prevented from entering witchspace by the presence of a nearby large mass. The blocking object is passed as a parameter<br />
<br />
this.shipWitchspaceBlocked = function(blocker)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>wormholeSuggested</code> ====<br />
{{oolite-method-added|1.79}}<br />
<br />
The <code>wormholeSuggested</code> handler is called when another ship enters witchspace and suggests that this ship follows. The wormhole used is passed as a parameter. This is most commonly called when a group leader enters witchspace and wishes to take its escorts with it.<br />
<br />
this.wormholeSuggested = function(wormhole)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Enter/Exit Aegis ===<br />
<br />
==== <code>shipEnteredStationAegis</code> ====<br />
<br />
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.<br />
<br />
this.shipEnteredStationAegis = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedStationAegis</code> ====<br />
<br />
The <code>shipExitedStationAegis</code> handler is called when the player leaves the aegis of the main-station (2x scanner range from main-station).<br />
<br />
this.shipExitedStationAegis = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipEnteredPlanetaryVicinity</code> ====<br />
<br />
The <code>shipEnteredPlanetaryVicinity</code> handler is called when the player enters the planet aegis (3x planet radius).<br />
<br />
this.shipEnteredPlanetaryVicinity = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedPlanetaryVicinity</code> ====<br />
<br />
The <code>shipExitedPlanetaryVicinity</code> handler is called when the player leaves the planet aegis (3x planet radius).<br />
<br />
this.shipExitedPlanetaryVicinity = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipApproachingPlanetSurface</code> ====<br />
<br />
The <code>shipApproachingPlanetSurface</code> handler is called when the player is very close to the planet (crosses a border ± 500 meter above the surface).<br />
<br />
this.shipApproachingPlanetSurface = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLeavingPlanetSurface</code> ====<br />
<br />
The <code>shipLeavingPlanetSurface</code> handler is called when the player leaves the planet (crosses a border ± 500 meter above the surface).<br />
<br />
this.shipLeavingPlanetSurface = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Combat ===<br />
<br />
==== <code>cascadeWeaponDetected</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>cascadeWeaponDetected</code> handler fires when a Q-bomb (or equivalent device) detonates within scanner range of the player. The stock Q-mine (and potentially OXP equivalents) will also send this handler at the start of the countdown, giving ships more time to react. The weapon entity will be passed as a parameter.<br />
<br />
this.cascadeWeaponDetected = function(weapon)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>defenseTargetDestroyed</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>defenseTargetDestroyed</code> handler is sent when a defense (i.e. secondary) target is destroyed. A reference to the destroyed ship (which will become invalid shortly) is passed as a parameter.<br />
<br />
this.defenseTargetDestroyed = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>escortAttack</code> ====<br />
<br />
The <code>escortAttack</code> handler is sent to all escorts of a mothership that are deployed. The mother first changes the escorts AI to interceptAI.plist and also sets the escort target to his own target before sending this handler to the escorts.<br />
<br />
this.escortAttack = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>helpRequestReceived</code> ====<br />
{{oolite-method-added|1.79}}<br />
<br />
The <code>helpRequestReceived</code> handler is sent when an ally of this ship is being attacked and requires help. There are two parameters, the ally and the enemy.<br />
<br />
this.helpRequestReceived = function(ally, enemy)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAttackedOther</code> ====<br />
The <code>shipAttackedOther</code> handler is called when this ship hits another with a laser shot. <code>other</code> is the identity of the ship being hit (added in test version 1.74.2).<br />
<br />
this.shipAttackedOther = function(other)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAttackedWithMissile</code> ====<br />
<br />
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.<br />
<br />
this.shipAttackedWithMissile = function(missile, whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAttackerDistracted</code> ====<br />
<br />
The <code>shipAttackerDistracted</code> handler is called when the ship's current attacker is distracted by another ship. <code>whom</code> contains the ship which is doing the distracting.<br />
<br />
this.shipAttackerDistracted = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBeingAttacked</code> ====<br />
<br />
The <code>shipBeingAttacked</code> handler is called when a laser shot hits. <code>whom</code> the identity of the ship that attacked.<br />
<br />
this.shipBeingAttacked = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBeingAttackedByCloaked</code> ====<br />
<br />
The <code>shipBeingAttackedByCloaked</code> handler is called when a laser shot from a cloaked ship hits. There is no parameter provided to identify the cloaked ship.<br />
<br />
this.shipBeingAttackedByCloaked = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBeingAttackedUnsuccessfully</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>shipBeingAttackedUnsuccessfully</code> handler is called when a laser shot narrowly misses the ship, when fired by an uncloaked ship intending to hit. <code>whom</code> the identity of the ship that attacked.<br />
<br />
this.shipBeingAttackedUnsuccessfully = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCloakActivated</code> ====<br />
<br />
The <code>shipCloakActivated</code> handler is called whenever the script's target ship activates its cloaking device. No parameters are required for this handler (added in test version 1.74).<br />
<br />
this.shipCloakActivated = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCloakDeactivated</code> ====<br />
<br />
The <code>shipCloakDeactivated</code> handler is called whenever the script's target ship deactivates its cloaking device. No parameters are required for this handler (added in test version 1.74).<br />
<br />
this.shipCloakDectivated = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetDestroyed</code> ====<br />
<br />
The <code>shipTargetDestroyed</code> handler is called when the target gets destroyed by this ship. <code>target</code> contains the destroyed target entity. This command is always preceded by the <code>shipTargetLost</code> handler.<br />
<br />
this.shipTargetDestroyed = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipDied</code> ====<br />
<br />
The <code>shipDied</code> handler is called when the ship or player dies.<br />
<br />
this.shipDied = function(whom, why)<br />
{<br />
// Your code here<br />
}<br />
'''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".<br><br />
("cascade weapon" is new in 1.74 and "removed" / "energy damage" were accidentally switched in 1.73)<br />
<br />
==== <code>shipEnergyBecameFull </code> ====<br />
<br />
The <code>shipEnergyBecameFull </code> handler is called when the energy level reaches its maximum value again. <br />
<br />
this.shipEnergyBecameFull = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipEnergyIsLow</code> ====<br />
<br />
The <code>shipEnergyIsLow</code> handler is called every time when a ship gets energy damage while the energy level lies below 25% of its maximum value.<br />
<br />
this.shipEnergyIsLow = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipHitByECM</code> ====<br />
<br />
The <code>shipHitByECM</code> handler is called when a ship receives a ECM pulse. <code>pulsesRemaining</code> contains the number of pulses that still have to be send by the sending ship. When a ship activates his ecm, he will send 4 pulses with 0.5 seconds interval and increasing range.: 6400 --> 12800 --> 19200 --> 25600. (Handler added in test version 1.71)<br />
<br />
this.shipHitByECM = function(pulsesRemaining)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipFiredMissile</code> ====<br />
<br />
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. (Handler added in test version 1.74)<br />
<br />
this.shipFiredMissile = function(missile, target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipKilledOther</code> ====<br />
<br />
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. (Handler added in test version 1.75) <br />
<br />
this.shipKilledOther = function(whom,damageType)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetAcquired</code> ====<br />
<br />
The <code>shipTargetAcquired</code> handler is called whenever a new target is selected. (Handler added in test version 1.74) <br />
<br />
this.shipTargetAcquired = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetCloaked</code> ====<br />
<br />
The <code>shipTargetCloaked</code> handler is called when the target cloakes.<br />
<br />
this.shipTargetCloaked = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetLost</code> ====<br />
<br />
The <code>shipTargetLost</code> handler is called when the target gets lost. <code>target</code> contains the lost target entity.<br>(Handler introduced in 1.74 as replacement with consistent name for the old handler: 'shipLostTarget'.)<br />
<br />
this.shipTargetLost = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTakingDamage</code> ====<br />
<br />
The <code>shipTakingDamage</code> handler is called when a ship sustains damage. Handler is added in Oolite 1.75<br><br />
It transfers the <code>amount</code> of damage, <code>who</code> caused the damage and the <code>type</code> of damage.<br />
<br />
For the player ship, only damage not absorbed by the shields will appear in <code>amount</code>, but the handler will be called anyway with zero as the amount if the shields absorb all the damage.<br />
<br />
this.shipTakingDamage = function(amount, whom, type)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Miscellaneous ===<br />
<br />
==== <code>cargoDumpedNearby</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>cargoDumpedNearby</code> handler is sent when a nearby ship - not this ship - dumps a cargo pod.<br />
<br />
this.cargoDumpedNearby = function(cargo: ship, releasedBy: ship)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>commsMessageReceived</code> ====<br />
<br />
The <code>commsMessageReceived</code> handler is sent when receiving a message from other ships. Handler is added in Oolite 1.75<br />
<br />
this.commsMessageReceived = function(message: string, sender: ship)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>distressMessageReceived</code> ====<br />
<br />
The <code>distressMessageReceived</code> handler is sent when receiving a distress message from other ships. Handler is added in Oolite 1.75<br />
<br />
this.distressMessageReceived = function(aggressor: ship, sender: ship)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>equipmentAdded</code> ====<br />
{{Oolite-method-added|1.81}}<br />
The <code>equipmentAdded</code> handler is called whenever a 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.<br />
<br />
this.equipmentAdded = function(equipmentKey)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>equipmentRemoved</code> ====<br />
{{Oolite-method-added|1.81}}<br />
The <code>equipmentRemoved</code> handler is called whenever a 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.<br />
<br />
this.equipmentAdded = function(equipmentKey)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAchievedDesiredRange</code> ====<br />
{{Oolite-method-added|1.79}}<br />
The <code>shipAchievedDesiredRange</code> handler is called when the ship reaches the desired range from its destination during certain flight behaviours.<br />
<br />
this.shipAchievedDesiredRange = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAIFrustrated</code> ====<br />
{{Oolite-method-added|1.79}}<br />
The <code>shipAIFrustrated</code> handler is called when the ship's low-level behaviour is unable to achieve the desired result (e.g. a <code>performFlee</code> request is not getting further from the target). A short string describing the context of the frustration is passed as a parameter.<br />
<br />
this.shipAIFrustrated = function(context)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBountyChanged</code> ====<br />
{{Oolite-method-added|1.77}}<br />
<br />
The <code>shipBountyChanged</code> handler is sent when an event tries to change the bounty level of the ship. <code>delta</code> may be zero, positive or negative. <code>reason</code> is a string that may either contain a standard value or a custom value set by an OXP. The standard values are:<br />
* '''setup actions''': Bounty level settings in the system populator or as a side effect of launching a ship from a station with a particular role.<br />
* '''scripted''': OXP scripted changes to bounties, with no specified cause.<br />
* '''attacked police''': The ship attacked a police ship<br />
* '''attacked main station''': The ship attacked the main station<br />
* '''attacked innocent''': The ship attacked a Clean ship and was seen doing so<br />
* '''seen by police''': The ship was seen by police committing a crime<br />
* '''distress call''': A police ship responded to a distress call from a ship that this ship is attacking<br />
* '''illegal exports''': The ship launched from a main station while carrying illegal goods (player only)<br />
* '''assisting offenders''': The bounty adjustment applied when a clean ship escorts an offender, or vice versa (NPC only)<br />
* '''new galaxy''': The ship entered a new galaxy (player only)<br />
* '''new system''': The ship entered a new system<br />
* '''paid fine''': The ship was marked for fines by police, and then paid them on docking (player only)<br />
* '''escape pod''': The ship is a replacement ship from escape pod insurance (player only)<br />
* '''assisting police''': The ship helped out a police ship in combat<br />
* '''unknown''': The bounty changed for an unknown reason. This should not occur.<br />
<br />
this.shipBountyChanged = function(delta,reason)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCloseContact</code> ====<br />
<br />
The <code>shipCloseContact</code> handler is sent when approaching otherShip and when "track_contacts" in shipData is true.<br />
<br />
this.shipCloseContact = function(otherShip)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCollided</code> ====<br />
<br />
The <code>shipCollided</code> handler is sent after a collision with otherShip.<br />
<br />
this.shipCollided = function(otherShip)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipDumpedCargo</code> ====<br />
{{oolite-method-added|1.83}}<br />
The <code>shipDumpedCargo</code> handler is sent when this ship dumps a cargo pod.<br />
<br />
this.shipDumpedCargo = function(cargo: ship)<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>shipNowFacingDestination</code> ====<br />
{{Oolite-method-added|1.79}}<br />
The <code>shipNowFacingDestination</code> handler is called when the ship is facing its destination during certain flight behaviours.<br />
<br />
this.shipNowFacingDestination = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipReachedEndPoint</code> ====<br />
<br />
The <code>shipReachedEndPoint</code> handler is sent after reaching the last navigation point when in mode <code>performFlyRacepoints</code>.<br />
<br />
shipReachedEndPoint = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipReachedNavPoint</code> ====<br />
<br />
The <code>shipReachedNavPoint</code> handler is sent after reaching a navigation point when in mode <code>performFlyRacepoints</code>.<br />
<br />
this.shipReachedNavPoint = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipScoopedOther</code> ====<br />
<br />
The <code>shipScoopedOther</code> handler is called when a ship scoops scripted_cargo. ("cargo_type" = CARGO_SCRIPTED_ITEM) Other cargo, even scooping escapepods, doesn't trigger a handler.<br>The scooped item is transferred as argument. The scooped cargo itselfs gets the handler: <code>shipWasScooped</code> with the scooper as argument. Starting with Oolite 1.77 this handler will fire on every scooped object.<br />
<br />
this.shipScoopedOther = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLaunchedEscapePod</code> ====<br />
<br />
The <code>shipLaunchedEscapePod</code> handler is called when the pilot bails out. This will be followed by a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds when it is the player that is ejecting.<br />
<br />
this.shipLaunchedEscapePod = function(escapepod, passengers)<br />
{<br />
// Your code here<br />
}<br />
<br />
<code>escapepod</code> contains the main pod with the pilot. <code>passengers</code> will be added with Oolite 1.77 and is an array with passenger pods for those ships that have more than one escape-capsule defined.<br />
<br />
=== NPC only ===<br />
<br />
==== <code>aiAwoken</code> ====<br />
{{oolite-method-added|1.79}}<br />
This is sent to the ship periodically when <code>ship.AIScriptWakeTime</code> passes. One of the actions of this handler should be to cause a new wake time to be set. It is received by both the ship script and the AI script but usually only of interest to the latter.<br />
<br />
==== <code>aiStarted</code> ====<br />
{{oolite-method-added|1.79}}<br />
This is sent to the ship when a new Javascript-based AI is loaded. The AI Script should then use it to do initialisation. The ship script can usually ignore it.<br />
<br />
==== <code>coordinatesForEscortPosition</code> ====<br />
<br />
The <code>coordinatesForEscortPosition</code> handler fires whenever the game engine wishes to know the positions of escorts relative to their group leader, and fires in the group leader's ship script at that time. It is given two parameters: the number of the escort, and the maximum number of escorts the group leader might have (which is not necessarily the number of escorts it currently has, of course). Unlike most ship script handlers, which return void, ''this handler is required to return a Vector'' (or a value equivalent to a Vector) describing the relative position of the escort to the mothership.<br />
<br />
coordinatesForEscortPosition = function(num,max)<br />
{<br />
// Your code here<br />
return escort_position;<br />
}<br />
<br />
The escort position is relative to the mothership, and in the mothership's coordinate system. For example, to place an escort 500m to the right of the mothership, return <code>new Vector(500, 0, 0);</code>. You are responsible for ensuring that there is sufficient space between the escorts and the mothership, and between any pair of escorts, or they will spend most of their time trying to avoid collisions with each other. If you intend to use the same ship script on several ships of varying sizes, you may wish to include the mothership's [[Oolite_JavaScript_Reference:_Entity#collisionRadius|collisionRadius]] in the calculations.<br />
<br />
Placing escorts directly ahead of the mothership (e.g. <code>new Vector(0, 0, 500);</code>) or too close to the mothership will trigger collision warnings for the mothership, making it difficult to maintain level flight for any significant time.<br />
<br />
==== <code>entityDestroyed</code> ====<br />
<br />
The <code>entityDestroyed</code> handler fires immediately ''after'' the ship becomes invalid, regardless of the reason, except when the game restarts. This is the best place for all kind of 'clean-up' code, for example stopping [[Oolite_JavaScript_Reference:_Timer|Timers]] associated with the ship script. (Added with Oolite 1.75.1)<br />
<br />
entityDestroyed = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>escortAccepted</code> ====<br />
<br />
The <code>escortAccepted</code> handler is called when a mother ship accepts this ship as an escort. The mothership simultaneously gets a <code>shipAcceptedEscort</code> event.<br />
<br />
this.escortAccepted = function(mothership)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>escortDock</code> ====<br />
<br />
The <code>escortDock</code> handler is called by a mother ships that uses the AI command: <code>dockEscorts</code>. Escorts are instructed to change AI into dockingAI.plist and enter the ABORT state of this AI after a certain delay. Than this event is send to all his escorts, each with a different delay with 3 seconds spacing.<br />
<br />
this.escortDock = function(delay)<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>escortRejected</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>escortRejected</code> handler is called when a mother ship rejects this ship as an escort.<br />
<br />
this.escortRejected = function(mothership)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>offenceCommittedNearby</code> ====<br />
<br />
The <code>offenceCommittedNearby</code> handler is only send to police ships in scanner range of a hostile action. It transfers the attacker and the victim to the police vessel.<br />
<br />
this.offenceCommittedNearby = function(attacker, victim)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>scriptedAI</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>scriptedAI</code> handler is called each frame while the ship's AI is in "performScriptedAI" or "performScriptedAttackAI" mode. It must return an object defining the ship's flight parameters. The <code>delta</code> parameter is the length of the current frame in seconds. [[OXP_Scripted_AI|More information on using this functionality]]<br />
<br />
this.scriptedAI = function(delta)<br />
{<br />
// Your code here<br />
return flightParameters;<br />
}<br />
<br />
==== <code>shipAcceptedEscort</code> ====<br />
<br />
The <code>shipAcceptedEscort</code> handler is called when this ship accepts a new ship as an escort. The escort simultaneously gets a <code>escortAccepted</code> event. <br />
<br />
this.shipAcceptedEscort = function(newEscort)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLandedOnPlanet</code> ====<br />
<br />
The <code>shipLandedOnPlanet</code> handler is called for ships landing on a planet. It transfers the <code>planet</code> parameter. (Will be added with Oolite 1.77)<br />
<br />
shipLandedOnPlanet = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipRemoved</code> ====<br />
<br />
The <code>shipRemoved</code> handler is called for ships removed by script. It transfers the <code>suppressDeathEvent</code> parameter so the script knows if there will also follow a shipDied() event.<br />
<br />
shipRemoved = function(suppressDeathEvent)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipSpawned</code> ====<br />
<br />
The <code>shipSpawned</code> handler is called for newly added ships. It does not trigger on adding but on the first update after adding. On a witchspace jump it means that first all ships are added to the system, then afterwards all the shipSpawned() events are triggered. Note that this is not called for subentities - if subentities need specific set up running, this must be called from the main ship's handler.<br />
<br />
this.shipSpawned = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>spawnedAsEscort</code> ====<br />
<br />
The <code>spawnedAsEscort</code> handler is called for newly added escort ships. It does trigger on adding the ship and before the shipSpawned() handlers is activated. It has the mothership as argument. <br />
<br />
this.spawnedAsEscort = function(mother)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipWasDumped</code> ====<br />
<br />
The <code>shipWasDumped</code> handler is sent to the cargopod when a ship jettisons it. The dumping ship is transferred as the argument. <br />
<br />
this.shipWasScooped = function(dumper)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipWasScooped</code> ====<br />
<br />
The <code>shipWasScooped</code> handler is send to the cargopod when a ship scoops scripted_cargo. ("cargo_type" = CARGO_SCRIPTED_ITEM) The scooper is transferred as argument. The scooper itself gets a trigger on the handler <code>shipScoopedOther</code>.<br />
<br />
this.shipWasScooped = function(scooper)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Stations only ===<br />
<br />
==== <code>alertConditionChanged</code> ====<br />
<br />
The <code>alertConditionChanged</code> handler is called when a station's alert status ([[Oolite_JavaScript_Reference:_Station#alertCondition|Station.alertCondition]]) changes. Only the player and stations have an alert condition. The equivalent player event is handled inside [[Oolite_JavaScript_Reference:_world_script_event_handlers|world scripts]].<br />
<br />
this.alertConditionChanged = function(newCondition, oldCondition)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>otherShipDocked</code> ====<br />
<br />
The <code>otherShipDocked</code> handler is called with a station script only, when an ship docks. It has the docked ship as argument.<br />
<br />
this.otherShipDocked = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationDockingQueuesAreEmpty</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>stationDockingQueuesAreEmpty</code> handler is called when the last ship in the queues docks with the station (or gives up docking and leaves).<br />
<br />
this.stationDockingQueuesAreEmpty = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationLaunchedShip</code> ====<br />
<br />
The <code>stationLaunchedShip</code> handler is called with a station script only, when a ship launches. It has the launched ship as argument.<br><br />
<br />
this.stationLaunchedShip = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationAcceptedDockingRequest</code> ====<br />
{{oolite-method-added|1.81}}<br />
The <code>stationReceivedDockingRequest</code> handler is called when a ship has requested docking clearance and has been allocated a dock. Due to the way in which docking clearance works, this is likely to be called several times for the same ship as it moves through the docking sequence.<br />
<br />
this.stationReceivedDockingRequest = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationReceivedDockingRequest</code> ====<br />
{{oolite-method-added|1.81}}<br />
The <code>stationReceivedDockingRequest</code> handler is called when a ship requests docking clearance. The ship requesting is passed as a parameter. This is often necessary for carriers which will need to come to a stop before ships can dock with them. Due to the way in which docking clearance works, this is likely to be called several times for the same ship as it moves through the docking sequence.<br />
<br />
this.stationReceivedDockingRequest = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
(note: a handler by this name was present in 1.79 and 1.80, but was called at the wrong time and should not be used. Set a minimum version of 1.81 if you use this event handler)<br />
<br />
==== <code>willOpenDockingPortFor</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>willOpenDockingPortFor</code> handler is called with a station script only, when a ship requests docking, in cases where a dock is set to generally disallow docking (i.e. [[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsDocking]] is false). It returns a Boolean:<br />
* if it returns false (or this function isn't defined), this dock will not be opened later for the requesting ship, and it should not try again.<br />
* if it returns true, this dock will be opened later for the requesting ship, and it should try again later if it cannot find another suitable dock on this station.<br />
The handler is passed the identity of the dock and the requesting ship<br />
<br />
this.willOpenDockingPortFor = function(dock, ship)<br />
{<br />
// Your code here<br />
return allow;<br />
}<br />
<br />
=== Docks Only ===<br />
{{oolite-method-added|1.77}}<br />
<br />
==== acceptDockingRequestFrom ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>acceptDockingRequestFrom</code> handler is called when a ship is looking for docking clearance from the station, and is considering this dock. To get as far as calling this handler, the dock must have [[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsDocking]] true, and be large enough to physically fit the ship.<br />
<br />
It returns a boolean: true to accept the request (which, depending on docking queue lengths will not necessarily mean that this dock is the one that the ship heads for), and false to reject the request. 'true' is assumed if this handler is not defined.<br />
<br />
This handler may be called multiple times for the same ship if the ship is having difficulty finding a suitable docking queue.<br />
<br />
this.acceptDockingRequestFrom = function(ship)<br />
{<br />
// Your code here<br />
return allow;<br />
}<br />
<br />
==== acceptLaunchingRequestFrom ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>acceptLaunchingRequestFrom</code> handler is called when a ship is looking for launching clearance from the station, and is considering this dock. To get as far as calling this handler, the dock must have [[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsLaunching]] true, and be large enough to physically fit the ship (unless the ship is the player).<br />
<br />
It returns a boolean: true to accept the request (which, depending on launching queue lengths will not necessarily mean that this dock is the one that the ship uses), and false to reject the request. 'true' is assumed if this handler is not defined.<br />
<br />
this.acceptLaunchingRequestFrom = function(ship)<br />
{<br />
// Your code here<br />
return allow;<br />
}<br />
<br />
<br />
<br />
<br />
<br />
=== Missing Events ===<br />
<br />
All initially planned events have a corresponding event handler in v1.74.<br />
<br />
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].<br />
<br />
'''See also:''' [[Oolite JavaScript Reference: world_script_event_handlers|world_script_event_handlers]]<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_PlayerShip&diff=48443Oolite JavaScript Reference: PlayerShip2015-08-12T19:25:21Z<p>Cim: /* hudAllowsBigGui */ new property</p>
<hr />
<div><small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Ship|Ship]]</code></small><br /><br />
<small>'''Subtypes:''' none</small><br />
<br />
The '''<code>PlayerShip</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing the player’s ship. The <code>PlayerShip</code> has all the properties and methods of a <code> [[Oolite JavaScript Reference: Ship|Ship]]</code>, and several others. There is always exactly one PlayerShip object in existence, which can be accessed through <code>[[Oolite JavaScript Reference: Global#player|player]].ship</code>.<br />
<br />
Like any entity, the player ship can become [[Oolite JavaScript Reference: Entity#Stale References|invalid]] – specifically, when the player dies or ejects. Unlike other entities, the player ship can become valid again (after ejecting and being rescued). This is a technicality and it’s not guaranteed to work this way in future.<br />
<br />
== Properties ==<br />
=== <code>aftShield</code> ===<br />
'''aftShield''' : Number (read/write, nonnegative)<br />
The current aft shield level, ranging from 0 to <code>[[#maxAftShield|maxAftShield]]</code>.<br />
<br />
'''See also''': <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#forwardShield|forwardShield]]</code>, <code>[[#maxAftShield|maxAftShield]]</code><br />
<br />
=== <code>aftShieldRechargeRate</code> ===<br />
'''aftShieldRechargeRate''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)<br />
The rate at which the aft shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, but this is not the case from 1.81.<br />
<br />
'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code><br />
<br />
=== <code>cargoSpaceAvailable</code> ===<br />
'''cargoSpaceAvailable''' : Number (read-only integer)<br />
The ship’s available cargo space, in tons.<br />
<br />
=== <code>cargoSpaceUsed</code> ===<br />
'''cargoSpaceUsed''' : Number (read-only integer)<br />
The ship’s current cargo, in tons.<br />
<br />
=== <code>compassMode</code> ===<br />
'''compassMode''' : String (read-only)<br />
Returns the current compass mode, which can be any one of the following:<br />
* COMPASS_MODE_BASIC<br />
* COMPASS_MODE_PLANET<br />
* COMPASS_MODE_STATION<br />
* COMPASS_MODE_SUN<br />
* COMPASS_MODE_TARGET<br />
* COMPASS_MODE_BEACONS<br />
<br />
=== <code>compassTarget</code> ===<br />
'''compassTarget''' : Entity(read-only)<br />
Points at the entity currently targeted by the compass.<br />
<br />
=== <code>crosshairs</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''crosshairs''' : String (read/write)<br />
The name of the [[Crosshairs.plist|crosshairs.plist]] defining the ship’s weapon crosshairs. HUDs can define crosshairs separately. This value will be <code>null</code> if the HUD built-in crosshairs are in use, and setting it to <code>null</code> will revert to the default HUD crosshairs.<br />
<br />
If the HUD is changed, the old value of this property will be discarded, and the HUD's default crosshairs will be used.<br />
<br />
=== <code>currentWeapon</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''currentWeapon''' : EquipmentInfo (read/write)<br />
A shortcut property to whichever of [[Oolite_JavaScript_Reference:_Ship#aftWeapon|aftWeapon]], [[Oolite_JavaScript_Reference:_Ship#forwardWeapon|forwardWeapon]], [[Oolite_JavaScript_Reference:_Ship#portWeapon|portWeapon]] or [[Oolite_JavaScript_Reference:_Ship#starboardWeapon|starboardWeapon]] is the currently active player weapon.<br />
<br />
If the player is on a screen with no active weapon (e.g. docked, or viewing the status screens) then this will always be null, and attempting to write to it will give an error.<br />
<br />
=== <code>cursorCoordinates</code> ===<br />
'''cursorCoordinates''' : Vector3D (read-only)<br />
'''Discouraged in favour of <code>[[#cursorCoordinatesInLY|cursorCoordinatesInLY]]</code>.'''<br /><br />
The current x and y cursor coordinates on the long range screen in the internal coordinate system. The <code>z</code> coordinate is always 0.<br />
<br />
=== <code>cursorCoordinatesInLY</code> ===<br />
'''cursorCoordinatesInLY''' : Vector3D (read-only)<br />
The current x and y cursor coordinates on the long range screen, in light years. The <code>z</code> coordinate is always 0.<br />
<br />
=== <code>docked</code> ===<br />
'''docked''' : Boolean (read-only)<br />
True if the player is docked with a station or carrier.<br />
<br />
=== <code>dockedStation</code> ===<br />
'''dockedStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only)<br />
The station with which the player is currently docked.<br />
<br />
=== <code>forwardShield</code> ===<br />
'''forwardShield''' : Number (read/write, nonnegative)<br />
The current forward shield level, ranging from 0 to <code>[[#maxForwardShield|maxForwardShield]]</code>.<br />
<br />
'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code><br />
<br />
=== <code>forwardShieldRechargeRate</code> ===<br />
'''forwardShieldRechargeRate''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)<br />
The rate at which the forward shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, but this is no longer the case in 1.81<br />
<br />
'''See also''': <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#forwardShield|forwardShield]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code><br />
<br />
=== <code>fuelLeakRate</code> ===<br />
'''fuelLeakRate''' : Number (read/write)<br />
The rate at which the player is losing fuel, in tenths of a LY per second. May not be negative. Reset to 0 when fuel is empty.<br />
<br />
=== <code>galacticHyperspaceBehaviour</code> ===<br />
'''galacticHyperspaceBehaviour''' : String (read/write)<br />
A string indicating what the effect of a galactic hyperspace jump will be. The available options are:<br />
* <code>"BEHAVIOUR_STANDARD"</code>: the player arrives in the closest system to the starting point that is part of the main group of stars. Small groups (as seen in [[Oolite planet list/Galaxy 6|galaxy 6]], among others) can’t be reached.<br />
* <code>"BEHAVIOUR_ALL_SYSTEMS_REACHABLE"</code>: The player arrives at the closest system to the starting point, even if it is in a small group. '''Important:''' this can leave the player stranded, unless there are missions providing the possibility of escape!<br />
* <code>"BEHAVIOUR_FIXED_COORDINATES"</code>: The player arrives at the system closest to <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>.<br />
<br />
'''See also:''' <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code><br />
<br />
=== <code>galacticHyperspaceFixedCoords</code> ===<br />
'''galacticHyperspaceFixedCoords''' : [[Oolite JavaScript Reference: Vector3D|Vector3D]] (read/write)<br />
'''Discouraged in favour of <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>.'''<br /><br />
Like <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>, but in the internal coordinate system.<br />
<br />
=== <code>galacticHyperspaceFixedCoordsInLY</code> ===<br />
'''galacticHyperspaceFixedCoordsInLY''' : [[Oolite JavaScript Reference: Vector3D|Vector3D]] (read/write)<br />
The destination coordinates when <code>[[#galacticHyperspaceBehaviour|galacticHyperspaceBehaviour]]</code> mode is <code>"GALACTIC_HYPERSPACE_BEHAVIOUR_FIXED_COORDINATES"</code>. The coordinate system corresponds to <code>[[#galaxyCoordinatesInLY|galaxyCoordinatesInLY]]</code>. Currently, when assigning a value its <code>x</code> and <code>y</code> coordinates will be rounded to integer internal coordinates, and the <code>z</code> coordinate will be rejected.<br />
<br />
'''See also:''' <code>[[#galacticHyperspaceBehaviour|galacticHyperspaceBehaviour]]</code><br />
<br />
=== <code>galaxyCoordinates</code> ===<br />
'''galaxyCoordinates''' : Vector3D (read-only)<br />
'''Discouraged in favour of <code>[[#galaxyCoordinatesInLY|galaxyCoordinatesInLY]]</code>.'''<br /><br />
The player’s location in galactic space, in the internal coordinate system. The <code>z</code> coordinate is always 0.<br />
<br />
=== <code>galaxyCoordinatesInLY</code> ===<br />
'''galaxyCoordinatesInLY''' : Vector3D (read-only)<br />
The player’s location in galactic space, in light years (measured from the top left of the map). The <code>z</code> coordinate is always 0.<br />
<br />
=== <code>hud</code> ===<br />
'''hud''' : String (read/write)<br />
The name of the [[hud.plist|HUD plists]] defining the ship’s head up display.<br />
<br />
=== <code>hudAllowsBigGui</code> ===<br />
{{oolite-prop-added|1.83}}<br />
<br />
'''hudAllowsBigGui''' : Boolean (read-only)<br />
Whether the HUD allows a "big GUI" or not. Most useful for determining whether mission screens will have 21 or 27 lines.<br />
<br />
If <code>hudHidden</code> is true this will also be true, even if the HUD which is hidden would not normally allow a big GUI.<br />
<br />
=== <code>hudHidden</code> ===<br />
'''hudHidden''' : Boolean (read/write)<br />
Whether the HUD should be visible.<br />
<br />
=== <code>hyperspaceSpinTime</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''hyperspaceSpinTime''' : Number (read-only, read/write in 1.81)<br />
The length of the ship's hyperspace countdown.<br />
<br />
Setting this to a negative value disables the drive entirely.<br />
<br />
=== <code>injectorsEngaged</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorsEngaged''' : Boolean(read-only)<br />
Is the player ship currently using fuel injection.<br />
<br />
=== <code>manifest</code> ===<br />
'''manifest''' : [[Oolite JavaScript Reference: Manifest|Manifest]] (read/write)<br />
The manifest contains all the cargo the player carries. It can be addressed as a property of playerShip as well as a class [[Oolite JavaScript Reference: Manifest|Manifest]] of its own.<br />
<br />
=== <code>maxAftShield</code> ===<br />
'''maxAftShield''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)<br />
The highest possible value of <code>[[#aftShield|aftShield]]</code>. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#maxForwardShield|maxForwardShield]]</code>, but this is not necessarily true from 1.81.<br />
<br />
'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code><br />
<br />
=== <code>maxForwardShield</code> ===<br />
'''maxAftShield''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)<br />
The highest possible value of <code>[[#forwardShield|forwardShield]]</code>. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#maxAftShield|maxAftShield]]</code>, but this is not necessarily true from 1.81.<br />
<br />
'''See also''': <code>[[#forwardShield|forwardShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code><br />
<br />
=== <code>missilesOnline</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''missilesOnline''' : Boolean (read-only)<br />
True if the ship's targeting system is currently in missile targeting mode, false if it is currently in identification mode.<br />
<br />
=== <code>multiFunctionDisplayList</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''multiFunctionDisplayList''' : Array (read-only, strings)<br />
The IDs of the currently active multi-function displays<br />
<br />
e.g.<br />
[null, "myoxp_mfd1"] // My OXP MFD1 in the second display, first display blank<br />
<br />
=== <code>multiFunctionDisplays</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''multiFunctionDisplays''' : Number (read-only, integer)<br />
The number of multi-function displays available on the current HUD.<br />
<br />
=== <code>price</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''price''' : Number (read-only, positive integer in decicredits)<br />
The value the player's ship would have, including equipment, if in a perfect servicing state. The ship can be exchanged at a shipyard for 75% of this value if it really is in perfect servicing state.<br />
<br />
=== <code>renovationCost</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''renovationCost''' : Number (read-only, positive integer in decicredits)<br />
The current price in decicredits to service the ship. Depending on the [[#serviceLevel|serviceLevel]] it may not be possible to actually purchase renovation at this time.<br />
<br />
=== <code>renovationMultiplier</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''renovationMultiplier''' : Number (read-only, positive)<br />
The multiplier applied to the base cost of renovation (<code>renovationCost</code> already includes this multiplier) to allow for some ships being more difficult to maintain than others. The default is 1.0 - other values are set in [[Shipyard.plist#renovation_multiplier|shipyard.plist]]<br />
<br />
=== <code>reticleTargetSensitive</code> ===<br />
'''reticleTargetSensitive''' : Boolean (read/write)<br />
If true, and Scanner Targeting Enhancement is installed, the selected target reticle will light up in red when the target is in the player’s sights. This is equivalent to the <code>reticle_target_sensitive</code> key in [[hud.plist|HUD plists]].<br />
<br />
=== <code>routeMode</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''routeMode''' : String (read-only)<br />
Gives the current mode of the [[Advanced Navigational Array]]. Three possible values<br />
* "OPTIMIZED_BY_NONE": off, or not fitted<br />
* "OPTIMIZED_BY_JUMPS": shortest route<br />
* "OPTIMIZED_BY_TIME": quickest route<br />
<br />
=== <code>scannerNonLinear</code> ===<br />
'''scannerNonLinear''' : Boolean (read/write)<br />
If <code>true</code>, the scanner is operating in non-linear mode. This property will be reset to the HUD default if the HUD is changed.<br />
<br />
=== <code>scannerUltraZoom</code> ===<br />
'''scannerUltraZoom''' : Boolean (read/write)<br />
If <code>true</code>, the scanner has 1x, 2x, 4x, 8x and 16x zoom modes, rather than the conventional 1x, 2x, 3x, 4x and 5x. This property will be reset to the HUD default if the HUD is changed.<br />
<br />
=== <code>scoopOverride</code> ===<br />
'''scoopOverride''' : Boolean (read/write)<br />
If <code>true</code>, and the player has a fuel scoop, the fuel scoop effect will run even if not close to a sun or scooping cargo.<br />
<br />
=== <code>serviceLevel</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''serviceLevel''' : Number (read/write, positive integer in range 75-100)<br />
The level of servicing the player's ship has. Renovation will be offered in shipyards at 85 or below, and malfunctions are more likely at lower values. This affects the sales price of the ship.<br />
<br />
=== <code>specialCargo</code> ===<br />
'''specialCargo''' : String (read-only)<br />
The special cargo the player is carrying, if any; otherwise <code>null</code>.<br />
<br />
'''See also''': <code>[[#useSpecialCargo|useSpecialCargo]]()</code><br />
<br />
=== <code>targetSystem</code> ===<br />
'''targetSystem''' : Integer (read-only, sometimes read/write in 1.77)<br />
The ID of the selected hyperspace target system. In 1.77, it can be written to if the player's ship is docked.<br />
<br />
=== <code>torusEngaged</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''torusEngaged''' : Boolean(read-only)<br />
Is the player ship currently using torus drive<br />
<br />
=== <code>viewDirection</code> ===<br />
'''viewDirection''' : String (read-only)<br />
Returns the view direction as string: <code>"VIEW_FORWARD"</code>, <code>"VIEW_AFT"</code>, <code>"VIEW_PORT"</code>, <code>"VIEW_STARBOARD"</code>, <code>"VIEW_CUSTOM"</code> or <code>"VIEW_GUI_DISPLAY"</code>.<br />
<br />
=== <code>viewPosition*</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''viewPositionAft''' : Vector (read-only)<br />
'''viewPositionForward''' : Vector (read-only)<br />
'''viewPositionPort''' : Vector (read-only)<br />
'''viewPositionStarboard''' : Vector (read-only)<br />
The ship's 4 point-of-view positions in XYZ relative to the model. The corresponding ''[[shipdata.plist]]'' keys start with <code>view_position_</code>.<br />
<br />
=== <code>weaponsOnline</code> ===<br />
'''weaponsOnline''' : Boolean (read-only)<br />
Returns the weapon safety status. Player can toggle the status with the underscore-key.<br />
<br />
== Methods ==<br />
=== <code>addParcel</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''addParcel'''(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean<br />
Add a parcel contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.<br />
<br />
Returns <code>false</code> when there is already a parcel with that name or the arrival time is invalid.<br />
<br />
The <code>advance</code> and <code>risk</code> parameters were added in Oolite 1.79. <code>advance</code> is purely advisory and describes any up-front payment given for the parcel. <code>risk</code> can be 0, 1 or 2 - the higher the number, the more likely that assassins are likely to try to kill the player while they carry this parcel.<br />
<br />
=== <code>addPassenger</code> ===<br />
function '''addPassenger'''(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean<br />
Add a passenger contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.<br />
<br />
Returns <code>false</code> when there is no room for the passenger, there is already a passenger with that name or the arrival time is invalid.<br />
<br />
'''Example:'''<br />
player.ship.addPassenger("cmdr Jameson", 34, 67, clock.seconds+3*24*3600, 1500);<br />
<br />
If successful - and in galaxy chart 1 - the player will have cmdr Jameson as a passenger, his documents will show that he boarded the ship at Inus, to go to Cemave, within exactly 3 days, and the player will be given 1500 credits if he gets there on time (early or late arrival will affect the amount paid).<br />
<br />
'''N.B.''' Normally a passenger will pay the captain a small advance upon boarding. Using this method, no initial payment is made. In versions after 1.77, an optional parameter can be added to describe what the advance ''was'', without actually making it.<br />
<br />
The risk parameter was added in Oolite 1.79. <code>risk</code> can be 0, 1 or 2 - the higher the number, the more likely that assassins are likely to try to kill the player while they carry this passenger.<br />
<br />
=== <code>awardContract</code> ===<br />
function '''awardContract'''(quantity : Number, commodity : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, premium : Number]) : Boolean<br />
Add a cargo contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.<br />
<br />
Returns <code>false</code> when there is no room for the cargo, the arrival time is invalid.<br />
<br />
'''Example:'''<br />
player.ship.awardContract(12, "Food", 34, 67, clock.seconds+7*24*3600, 5000)<br />
<br />
If successful - and in galaxy chart 1 - the player will have 12 more food containers on board, the manifest will show that the cargo was picked up at Inus, to be delivered at Cemave, within exactly 7 days, and the player will be given 5000 credits if the cargo is delivered on time (early or late delivery will affect the amount paid).<br />
<br />
'''N.B.''' Normally to get a contract, the player will have to pay a deposit similar in value to the cargo. Using this method, no deposit payment is made. In versions after 1.77, an optional parameter can be added to describe what the deposit payment ''was'', without actually making it.<br />
<br />
=== <code>awardEquipmentToCurrentPylon</code> ===<br />
function '''awardEquipmentToCurrentPylon'''(item : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Replace the missile or mine currently being launched with the specified item (which must be an external store). This will only have an effect if called while a missile or mine is being launched. Effectively this means that this method must be used within the <code>shipFiredMissile()</code> handler or in the ENTER message of the GLOBAL state of an missileAI.plist.<br />
<br />
'''Bug:''' In Oolite 1.74.0, if <code>awardEquipmentToCurrentPylon()</code> fails the script will be halted without any error message. In future versions, it will simply return <code>false</code>.<br />
<br />
'''See also:''' <code>[[Oolite JavaScript Reference: Ship#awardEquipment|Ship.awardEquipment()]]</code><br />
<br />
=== <code>beginHyperspaceCountdown</code> ===<br />
{{oolite-method-added|1.77}}<br />
function beginHyperspaceCountdown( [ length : Number ] ) : Boolean<br />
This function begins the witchspace sequence for the player ship. It returns true if the sequence is started successfully, and false otherwise (no destination selected, insufficient fuel, out of range, etc.). Optionally, the length of the countdown can be varied. Values between 5 and 60 seconds are accepted. If this parameter is omitted the default sequence length for this class of ship will be used.<br />
<br />
'''See also:''' <code>[[#cancelHyperspaceCountdown|cancelHyperspaceCountdown]]</code><br />
<br />
=== <code>cancelHyperspaceCountdown</code> ===<br />
{{oolite-method-added|1.77}}<br />
function cancelHyperspaceCountdown() : Boolean<br />
This function cancels the witchspace sequence for the player ship. It returns true if there was an ongoing sequence to cancel, and false otherwise.<br />
<br />
'''See also:''' <code>[[#beginHyperspaceCountdown|beginHyperspaceCountdown]]</code><br />
<br />
=== <code>disengageAutopilot</code> ===<br />
function disengageAutopilot()<br />
Disenable autopilot.<br />
<br />
'''See also:''' <code>[[#engageAutopilotToStation|engageAutopilotToStation()]]</code><br />
<br />
=== <code>engageAutopilotToStation</code> ===<br />
function engageAutopilotToStation(station : [[Oolite JavaScript Reference: Station|Station]]) : Boolean<br />
Engage autopilot, set to dock with the specified station.<br />
<br />
'''See also:''' <code>[[#disengageAutopilot|disengageAutopilot()]]</code><br />
<br />
=== <code>hideHUDSelector</code> ===<br />
{{oolite-method-added|1.79}}<br />
function hideHUDSelector(selector : String)<br />
Hide all dials using the specified selector on the HUD display. For example<br />
<br />
player.ship.hideHUDSelector("drawScanner:");<br />
<br />
'''See also:''' <code>[[#showHUDSelector|showHUDSelector()]]</code><br />
<br />
=== <code>launch</code> ===<br />
function '''launch'''()<br />
Launches the player’s ship if it is currently docked.<br />
<br />
=== <code>removeAllCargo</code> ===<br />
function '''removeAllCargo'''()<br />
Removes all cargo from the ship’s cargo bay that are measured in tons. Does not affect Gold, Platinum or Gemstones. Can only be used while docked.<br />
<br />
=== <code>removeContract</code> ===<br />
function '''removeContract'''(commodity : String, destination : Number)<br />
Remove the cargo contract matching that commodity and destination.<br />
<br />
=== <code>removeParcel</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''removeParcel'''(name : String)<br />
Remove a named parcel.<br />
<br />
=== <code>removePassenger</code> ===<br />
function '''removePassenger'''(name : String)<br />
Remove a named passenger.<br />
<br />
=== <code>resetCustomView</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''resetCustomView'''()<br />
Resets the custom view back to the last-used setting defined in [[shipdata.plist]]<br />
<br />
This function gives an error if used when the custom view camera is not selected.<br />
<br />
=== <code>resetScannerZoom</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''resetScannerZoom'''()<br />
Resets the scanner zoom back to 1:1<br />
<br />
=== <code>setCustomView</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''setCustomView'''(Vector : position, Quaternion : orientation [,WeaponDirection weapon])<br />
Set the position and orientation of the custom view camera to those specified. As with the custom views specified through [[shipdata.plist]], these are relative to the player's ship's position, and the coordinate frame defined by the ship's forward, right and up Vectors.<br />
<br />
The optional weapon parameter can be "FORWARD", "AFT", "PORT" or "STARBOARD" and sets the active weapon accordingly. If omitted, the active weapon for the previous custom view will be preserved.<br />
<br />
This function gives an error if used when the custom view camera is not selected. Setting the custom view does not affect the custom views defined in [[shipdata.plist]], which will be switched back to the next time 'v' is pressed, or when [[#resetCustomView|resetCustomView]] is called.<br />
<br />
=== <code>setCustomHUDDial</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''setCustomHUDDial'''(key : String, value : Value)<br />
Sets the custom HUD dial [[hud.plist#data_source|data source]] 'key' to the specified value. Different types of custom HUD dial will expect different types of values; a value of an incorrect type will be converted if possible.<br />
<br />
=== <code>setMultiFunctionDisplay</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setMultiFunctionDisplay'''(index : Number, key : String) : Boolean<br />
Sets the multi-function display with the specified number to display the given multi-function display <code>key</code> set earlier with [[#setMultiFunctionText|setMultiFunctionText()]]. Multi-function displays are numbered from 0 to [[#multiFunctionDisplays|multiFunctionDisplays]]-1. If the index given is outside this range, the first unused multi-function display will be used, or the function will return <code>false</code> if all are currently in use.<br />
Example:<br />
// picks first unused one<br />
player.ship.setMultiFunctionDisplay(player.ship.multiFunctionDisplays, "myOxp_mfd");<br />
<br />
As the player can cycle the contents of their displays between the various active keys themselves using keyboard controls, it is advisable not to call this function to override a specific display except in emergencies, as this is likely to annoy the player.<br />
<br />
=== <code>setMultiFunctionText</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setMultiFunctionText'''(key : String [, contents : String [, reflow : Boolean]])<br />
Set the text for the multi-function display with the specified <code>key</code> to be <code>contents</code>. The limit on space for a multi-function display is ten lines of text, each 15 blocks wide. <br />
<br />
If you specify the optional <code>reflow</code> parameter, then the text given will automatically be fitted into the available space, with any extra discarded. Otherwise, line-breaks will not be added automatically, so you must enter them into <code>contents</code> yourself. If any individual line is more than 15 blocks long, the text will be compressed to fit it into the available space. This looks bad and is best avoided.<br />
<br />
=== <code>showHUDSelector</code> ===<br />
{{oolite-method-added|1.79}}<br />
function showHUDSelector(selector : String)<br />
Show all dials using the specified selector on the HUD display if they were previously hidden. For example<br />
<br />
player.ship.showHUDSelector("drawScanner:");<br />
<br />
'''See also:''' <code>[[#hideHUDSelector|hideHUDSelector()]]</code><br />
<br />
=== <code>takeInternalDamage</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''takeInternalDamage'''()<br />
Causes the player ship to potentially take "internal damage". Internal damage can also be caused by hits on the hull and some witchdrive malfunctions, and this function uses the same algorithm to determine the damage taken, which can be:<br />
* damage to cargo<br />
* damage to equipment (according to the damage_probability)<br />
* reduction in [[#serviceLevel|service level]]<br />
* no damage<br />
The function will return 'false' if "no damage" was selected, and 'true' otherwise. The relative probabilities of the three options vary depending on the size of the player ship, its cargo capacity, cargo carried and installed equipment.<br />
<br />
=== <code>useSpecialCargo</code> ===<br />
function '''useSpecialCargo'''(description : String)<br />
Fills the cargo bay with the cargo described, effectively disabling the use of the cargo bay until the cargo is removed.<br />
<br />
'''See also''': <code>[[#specialCargo|specialCargo]]</code><br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_World_script_event_handlers&diff=48442Oolite JavaScript Reference: World script event handlers2015-08-12T19:23:40Z<p>Cim: /* playerDockingClearanceExpired */ new method</p>
<hr />
<div>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.<br />
<br />
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. <br />
<br />
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.<br />
<br />
World scripts are always active.<br />
<br />
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 '$').<br />
<br />
=== Game State ===<br />
<br />
==== <code>gamePaused</code> ====<br />
{{oolite-method-added|1.81}}<br />
<br />
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.<br />
<br />
this.gamePaused = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>gameResumed</code> ====<br />
{{oolite-method-added|1.81}}<br />
<br />
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.<br />
<br />
this.gameResumed = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerWillSaveGame</code> ====<br />
<br />
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'<br />
<br />
this.playerWillSaveGame = function(message : String)<br />
{<br />
// Your code here<br />
}<br />
<br />
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.<br />
<br />
==== <code>startUp</code> ====<br />
<br />
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)<br />
<br />
this.startUp = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
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.<br />
<br />
==== <code>startUpComplete</code> ====<br />
{{oolite-method-added|1.79}}<br />
<br />
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:<br />
* <code>startUp</code><br />
* <code>systemWillPopulate</code> (or an alternative handler specified by the system info)<br />
* <code>startUpComplete</code><br />
<br />
=== Docking ===<br />
<br />
==== <code>shipWillDockWithStation</code> ====<br />
<br />
The <code>shipWillDockWithStation</code> handler is called at the beginning of the docking tunnel effect.<br />
<br />
this.shipWillDockWithStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
At this moment "ship.dockedStation == null", "ship.docked == true", "ship.status == STATUS_DOCKING"<br />
<br />
<br />
==== <code>shipDockedWithStation</code> ====<br />
<br />
The <code>shipDockedWithStation</code> handler is called at the end of the docking tunnel effect.<br />
<br />
this.shipDockedWithStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
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.<br />
<br />
==== <code>shipWillLaunchFromStation</code> ====<br />
<br />
The <code>shipWillLaunchFromStation</code> handler is called at the beginning of the launch tunnel effect.<br />
<br />
this.shipWillLaunchFromStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
At this moment "ship.dockedStation == the station", "ship.docked == false", "ship.status == STATUS_LAUNCHING".<br />
<br />
==== <code>shipLaunchedFromStation</code> ====<br />
<br />
The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect.<br />
<br />
this.shipLaunchedFromStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
At this moment "ship.dockedStation == null", "ship.docked == false", "ship.status == STATUS_IN_FLIGHT".<br />
<br />
==== <code>playerStartedAutoPilot</code> ====<br />
<br />
The <code>playerStartedAutoPilot</code> handler is called when the player starts autopilot docking. It is not called for the instantaneous dock command.<br />
<br />
this.playerStartedAutoPilot = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>playerCancelledAutoPilot</code> ====<br />
<br />
The <code>playerCancelledAutoPilot</code> handler is called when the player cancels autopilot docking.<br />
<br />
this.playerCancelledAutoPilot = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>playerDockingClearanceExpired</code> ====<br />
{{oolite-method-added|1.83}}<br />
<br />
The <code>playerDockingClearanceExpired</code> handler is called when the player exceeds the two minute window without requesting an extension<br />
<br />
this.playerDockingClearanceExpired = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerDockingRefused</code> ====<br />
<br />
The <code>playerDockingRefused</code> handler is called when a station refuses to provide autopilot docking instructions.<br />
<br />
this.playerDockingRefused = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerRequestedDockingClearance</code> ====<br />
<br />
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).<br />
<br />
this.playerRequestedDockingClearance = function(message)<br />
{<br />
// Your code here<br />
}<br />
<br />
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".<br />
<br />
==== <code>playerRescuedEscapePod</code> ====<br />
{{oolite-method-added|1.81}}<br />
<br />
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:<br />
# the rescue fee, in decicredits<br />
# the fee reason, which can be "insurance", "bounty" or "slave" (in the latter case, the fee will always be zero)<br />
# a dictionary like those in the <code>ship.crew</code> property describing the pod occupant<br />
<br />
this.playerRescuedEscapePod = function(fee, reason, occupant)<br />
{<br />
// Your code here<br />
}<br />
<br />
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.<br />
<br />
==== <code>playerCompletedContract</code> ====<br />
{{oolite-method-added|1.81}}<br />
<br />
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:<br />
# The type of contract, which can be "cargo", "parcel" or "passenger"<br />
# The result of the contract, which can be "success", "late", "failed", or for cargo contracts only "short"<br />
# The fee paid for the contract in decicredits<br />
# The contract information dictionary<br />
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.<br />
<br />
this.playerCompletedContract = function(type, result, fee, contract)<br />
{<br />
// Your code here<br />
}<br />
<br />
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.<br />
<br />
==== <code>playerEnteredContract</code> ====<br />
{{oolite-method-added|1.81}}<br />
<br />
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:<br />
# The type of contract, which can be "cargo", "parcel" or "passenger"<br />
# The contract information dictionary<br />
<br />
this.playerEnteredContract = function(type, contract)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Witchspace Jumps ===<br />
<br />
==== <code>playerStartedJumpCountdown</code> ====<br />
<br />
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.<br />
<br />
this.playerStartedJumpCountdown = function(type, seconds)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerCancelledJumpCountdown</code> ====<br />
<br />
The <code>playerCancelledJumpCountdown</code> handler is called when the user cancels a witchspace or galactic witchspace jump countdown.<br />
<br />
this.playerCancelledJumpCountdown = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>playerJumpFailed</code> ====<br />
<br />
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:<br />
* '''"insufficient fuel"''' - the ship no longer has enough fuel to make the jump (e.g. injector use or fuel leak).<br />
* '''"blocked"''' - a heavy ship is near the player (specifically <code>object mass</code> / <code>object distance</code><sup>2</sup> >= 10.0, and <code>object distance</code> <= scanner range).<br />
* '''"malfunction"''' - the jump malfunctioned in a way that leaves the player ship in the current system.<br />
* '''"malfunction"''' - the Galactic Hyperdrive is damaged or removed during a galactic jump countdown.<br />
<br />
Also theoretically possible but unlikely in current Oolite:<br />
* '''"too far"''' - the jump destination is outside the 7LY range (but wasn't when the countdown started).<br />
* '''"no target"''' - the jump destination is the current location (but wasn't when the countdown started).<br />
<br />
this.playerJumpFailed = function(reason)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipWillEnterWitchspace</code> ====<br />
<br />
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.<br />
<br />
// 1.80 or earlier<br />
this.shipWillEnterWitchspace = function(cause)<br />
{<br />
// Your code here<br />
}<br />
<br />
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)<br />
<br />
// 1.81 or later<br />
this.shipWillEnterWitchspace = function(cause, destination)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipWillExitWitchspace</code> ====<br />
<br />
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.<br />
<br />
this.shipWillExitWitchspace = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedWitchspace</code> ====<br />
<br />
The <code>shipExitedWitchspace</code> handler is called after a witchspace jump has concluded and the tunnel effect has been shown.<br />
<br />
this.shipExitedWitchspace = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerEnteredNewGalaxy</code> ====<br />
<br />
The <code>playerEnteredNewGalaxy</code> handler is called just before shipWillExitWitchspace.<br />
<br />
the sequence of events for a player jumping to a different galaxy is as follows:<br />
<br />
shipWillEnterWitchspace (world event)<br><br />
playerWillEnterWitchspace (NPC ship event)<br><br />
playerEnteredNewGalaxy (world event)<br><br />
shipWillExitWitchspace (world event)<br><br />
shipExitedWitchspace (world event)<br><br />
<br />
this.playerEnteredNewGalaxy = function(galaxyNumber)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Enter/Exit Aegis ===<br />
<br />
==== <code>shipEnteredStationAegis</code> ====<br />
<br />
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.<br />
<br />
this.shipEnteredStationAegis = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedStationAegis</code> ====<br />
<br />
The <code>shipExitedStationAegis</code> handler is called when the player leaves the aegis of the main-station (2x scanner range from main-station).<br />
<br />
this.shipExitedStationAegis = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipEnteredPlanetaryVicinity</code> ====<br />
<br />
The <code>shipEnteredPlanetaryVicinity</code> handler is called when the player enters the planet aegis (3x planet radius).<br />
<br />
this.shipEnteredPlanetaryVicinity = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedPlanetaryVicinity</code> ====<br />
<br />
The <code>shipExitedPlanetaryVicinity</code> handler is called when the player leaves the planet aegis (3x planet radius).<br />
<br />
this.shipExitedPlanetaryVicinity = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipApproachingPlanetSurface</code> ====<br />
<br />
The <code>shipApproachingPlanetSurface</code> handler is called when the player is very close to the planet (crosses a border ± 500 meter above the surface).<br />
<br />
this.shipApproachingPlanetSurface = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLeavingPlanetSurface</code> ====<br />
<br />
The <code>shipLeavingPlanetSurface</code> handler is called when the player leaves the planet (crosses a border ± 500 meter above the surface).<br />
<br />
this.shipLeavingPlanetSurface = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Combat ===<br />
<br />
==== <code>alertConditionChanged</code> ====<br />
<br />
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)<br />
<br />
this.alertConditionChanged = function(newCondition, oldCondition)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerTargetedMissile</code> ====<br />
<br />
The <code>playerTargetedMissile</code> handler is called when the player targets the nearest missile by pressing T (shift-t) on the keybord.<br />
<br />
this.playerTargetedMissile = function(missile)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAttackedOther</code> ====<br />
<br />
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.<br />
<br />
this.shipAttackedOther = function(other)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAttackedWithMissile</code> ====<br />
<br />
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.<br />
<br />
this.shipAttackedWithMissile = function(missile, whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBeingAttacked</code> ====<br />
<br />
The <code>shipBeingAttacked</code> handler is called when a laser shot hits. <code>whom</code> the identity of the ship that attacked.<br />
<br />
this.shipBeingAttacked = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBeingAttackedByCloaked</code> ====<br />
<br />
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!<br />
<br />
this.shipBeingAttackedByCloaked = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipKilledOther</code> ====<br />
<br />
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. (Handler added in test version 1.75) <br />
<br />
this.shipKilledOther = function(whom,damageType)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetDestroyed</code> ====<br />
<br />
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.<br />
<br />
this.shipTargetDestroyed = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipDied</code> ====<br />
<br />
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.<br />
<br />
this.shipDied = function(whom, why)<br />
{<br />
// Your code here<br />
}<br />
'''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".<br><br />
("cascade weapon" is new in 1.74 and "removed" / "energy damage" were accidentally switched in 1.73)<br />
<br />
<br />
==== <code>shipFiredMissile</code> ====<br />
<br />
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.<br />
<br />
this.shipFiredMissile = function(missile, target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetLost</code> ====<br />
<br />
The <code>shipTargetLost</code> handler is called when the target gets lost. <code>target</code> contains the lost target entity.<br />
<br />
this.shipTargetLost = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetCloaked</code> ====<br />
<br />
The <code>shipTargetCloaked</code> handler is called when the target cloakes.<br />
<br />
this.shipTargetCloaked = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Equipment and Cargo ===<br />
<br />
==== <code>equipmentAdded</code> ====<br />
{{Oolite-method-added|1.81}}<br />
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.<br />
<br />
this.equipmentAdded = function(equipmentKey)<br />
{<br />
// Your code here<br />
}<br />
<br />
This is often more convenient than monitoring both <code>equipmentRepaired</code> and <code>playerBoughtEquipment</code>, and will also detect equipment addition by script.<br />
<br />
==== <code>equipmentDamaged</code> ====<br />
<br />
The <code>equipmentDamaged</code> handler is called when equipment gets damaged. (world script only)<br />
<br />
this.equipmentDamaged = function(equipment)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>equipmentRemoved</code> ====<br />
{{Oolite-method-added|1.81}}<br />
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.<br />
<br />
this.equipmentRemoved = function(equipmentKey)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>equipmentRepaired</code> ====<br />
{{Oolite-method-added|1.77}}<br />
<br />
The <code>equipmentRepaired</code> handler is called when equipment gets repaired. (world script only)<br />
<br />
this.equipmentRepaired = function(equipment)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerBoughtCargo</code> ====<br />
{{Oolite-method-added|1.77}}<br />
<br />
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.<br />
<br />
this.playerBoughtCargo = function(commodity, units, price)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerBoughtEquipment</code> ====<br />
<br />
The <code>playerBoughtEquipment</code> handler is called when equipment is bought at the outfit screen.<br />
<br />
this.playerBoughtEquipment = function(equipment)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerBoughtNewShip</code> ====<br />
<br />
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.<br />
<br />
this.playerBoughtNewShip = function(ship, price)<br />
{<br />
// Your code here<br />
}<br />
<br />
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|player.replaceShip]]<br />
<br />
==== <code>playerSoldCargo</code> ====<br />
{{Oolite-method-added|1.77}}<br />
<br />
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.<br />
<br />
this.playerSoldCargo = function(commodity, units, price)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipScoopedFuel</code> ====<br />
{{Oolite-method-added|1.77}}<br />
<br />
The <code>shipScoopedFuel</code> handler is called whenever the player's ship transfers 0.1LY of fuel from the scoops to the tank.<br />
<br />
this.shipScoopedFuel = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipScoopedOther</code> ====<br />
<br />
The <code>shipScoopedOther</code> handler is called when a ship scoops cargo. The scooped item is transferred as argument.<br>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.<br />
<br />
this.shipScoopedOther = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Other ===<br />
<br />
==== <code>compassTargetChanged</code> ====<br />
<br />
The <code>compassTargetChanged</code> handler is called when a new target is selected. Mode can be any of the following:<br />
<br />
COMPASS_MODE_BASIC<br />
COMPASS_MODE_PLANET<br />
COMPASS_MODE_STATION<br />
COMPASS_MODE_SUN<br />
COMPASS_MODE_TARGET<br />
COMPASS_MODE_BEACONS<br />
<br />
script example <br />
<br />
this.compassTargetChanged = function(whom, mode)<br />
{<br />
log(' Now targeting ' + whom);<br />
// Your code here<br />
}<br />
<br />
==== <code>dayChanged</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
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.<br />
<br />
this.dayChanged = function(newday)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>guiScreenChanged</code> ====<br />
<br />
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)<br><br />
This handler will not fire for every screen the player can switch to, but only when switching to any of the following screens: <br />
<br />
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><br />
<br />
1.77: adds <code>GUI_SCREEN_INTERFACES</code> and removes <code>GUI_SCREEN_CONTRACTS</code><br />
<br />
this.guiScreenChanged = function(to, from)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>guiScreenWillChange</code> ====<br />
<br />
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)<br />
<br />
this.guiScreenWillChange = function(to, from)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>missionChoiceWasReset</code> ====<br />
<br />
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)<br />
<br />
this.missionChoiceWasReset= function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>missionScreenEnded</code> ====<br />
<br />
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)<br />
<br />
this.missionScreenEnded = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>missionScreenOpportunity</code> ====<br />
<br />
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)<br />
<br />
this.missionScreenOpportunity= function()<br />
{<br />
// Your code here<br />
}<br />
<br />
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.<br />
<br />
==== <code>reportScreenEnded</code> ====<br />
<br />
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)<br />
<br />
this.reportScreenEnded = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCollided</code> ====<br />
<br />
The <code>shipCollided</code> handler is send after a collision with otherShip.<br />
<br />
this.shipCollided = function(otherShip)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipSpawned</code> ====<br />
<br />
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.<br><br />
This handler for the woldScript 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.<br />
<br />
this.shipSpawned = function(ship)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLaunchedEscapePod</code> ====<br />
<br />
The <code>shipLaunchedEscapePod</code> handler is called when the player bails out. This will be followed by a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds.<br />
<br />
this.shipLaunchedEscapePod = function(escapepod)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>systemInformationChanged</code> ====<br />
{{oolite-method-added|1.79}}<br />
<br />
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.<br />
<br />
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.<br />
<br />
this.systemInformationChanged = function(galaxy,system,key,newValue)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>viewDirectionChanged</code> ====<br />
<br />
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",<br />
"VIEW_CUSTOM",<br />
"VIEW_GUI_DISPLAY".<br />
<br />
this.viewDirectionChanged = function(viewString)<br />
{<br />
if (viewString == "VIEW_PORT")<br />
{<br />
// Your code here<br />
}<br />
}<br />
<br />
=== System population ===<br />
<br />
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.<br />
<br />
=== Defunct ===<br />
<br />
==== <code>equipmentDestroyed</code> ====<br />
''Handler no longer exists in current stable version 1.80''<br />
<br />
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)<br />
<br />
this.equipmentDestroyed = function(equipment)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>tickle</code> (removed in 1.77) ====<br />
<br />
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.<br />
<br />
=== Missing Events ===<br />
<br />
All the initially planned events have been implemented in 1.74.<br />
<br />
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].<br />
<br />
'''See also:''' [[Oolite JavaScript Reference: ship_script_event_handlers|ship_script_event_handlers]]<br />
<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Hud.plist&diff=48427Hud.plist2015-08-10T20:24:07Z<p>Cim: /* viewscreen_only */ Note bug</p>
<hr />
<div>'''hud.[[plist]]''' and '''hud-small.[[plist]]''' are two different HUDs used by Oolite. They provide Oolite with the information necessary to display the players hud. The 'hud-small' is used on ships like the Cobra MkI and the Adder, while the 'hud.plist' is the standard default Cobra MkIII hud. The main difference lies in their width. 'hud-small' is smaller (narrower) than 'hud', to help you imagine a smaller cockpit in a smaller ship.<br />
<br />
== allow_big_gui ==<br />
In Oolite 1.81 and onwards this is a statement that there is nothing in the lower part of the screen (-256 <= x <= -160 , -256 <= y <= 256) when GUI screens are being displayed. Currently this allows the mission screen to take up 27 text rows instead of 21, which previously required the HUD to be hidden entirely.<br />
<br />
This setting is not validated by the game. Setting this to 'yes' when the HUD does in fact use that space may end up looking very messy.<br />
<br />
The default value is no.<br />
<br />
Example:<br />
allow_big_gui = yes;<br />
<br />
== cloak_indicator_on_status_light ==<br />
This key determines if the statuslight also should show the cloaked status.<br />
<br />
Example:<br />
cloak_indicator_on_status_light = yes;<br />
<br />
== crosshair_scale ==<br />
Affects the size of the crosshair. (default 32.0)<br />
<br />
Example:<br />
crosshair_scale = 32.0;<br />
<br />
== crosshair_width ==<br />
Affects the width of the crosshair. (default 1.5)<br />
<br />
Example:<br />
crosshair_width = 1.5;<br />
<br />
== crosshair_color ==<br />
Affects the color of the crosshair. color can be a [[Materials_in_Oolite#Named_colours|named color]] or any of the other [[Materials_in_Oolite#Colour_specifiers|Colour_specifiers]]. (Default is greenColor)<br />
<br />
Example:<br />
crosshair_color= "greenColor";<br />
<br />
== crosshairs ==<br />
This entry contains a directory with crosshairs that overrides those defined in the internal [[crosshairs.plist]]<br />
<br />
Example:<br />
crosshairs = {<br />
WEAPON_BEAM_LASER =<br />
(<br />
(0.25, 0.25, 1.0, 0.75, 0.0, 0.50),<br />
(0.25, 0.25, -1.0, 0.75, 0.0, -0.50),<br />
(0.25, 1.0, 0.25, 0.75, 0.50, 0.0),<br />
(0.25, -1.0, 0.25, 0.75, -0.50, 0.0),<br />
(0.25, -0.25, 1.0, 0.75, 0.0, 0.50),<br />
(0.25, -0.25, -1.0, 0.75, 0.0, -0.50),<br />
(0.25, 1.0, -0.25, 0.75, 0.50, 0.0),<br />
(0.25, -1.0, -0.25, 0.75, -0.50, 0.0)<br />
);<br />
}<br />
<br />
== crosshair_file ==<br />
(Oolite 1.77 or later)<br />
This entry names an external crosshairs plist file that defines the default crosshairs for this HUD. If this is specified at the same time as the <code>crosshairs</code> property, then <code>crosshair_file</code> takes precedence.<br />
<br />
== dials ==<br />
The dials are listed here as an array of individual dials. Each dial is a separate directory. Some examples are:<br />
{<br />
"equipment_required" = "EQ_SCANNER_SHOW_MISSILE_TARGET";<br />
selector = "drawTargetReticle:";<br />
},<br />
{ // scanner<br />
selector = "drawScanner:";<br />
alpha = 1.0;<br />
x = 0;<br />
y = 60;<br />
y_origin = -1;<br />
height = 72.0;<br />
width = 288.0;<br />
rgb_color = (1.0, 0.0, 0.0);<br />
},<br />
{ // energy bars<br />
"draw_surround" = yes;<br />
height = 48;<br />
selector = "drawEnergyGauge:";<br />
width = 80;<br />
x = 200;<br />
y = 35;<br />
"y_origin" = "-1";<br />
labelled = yes;<br />
n_bars = 3;<br />
}<br />
<br />
=== selector ===<br />
The selector is a hardcoded name, like: drawTargetReticle:, drawScanner:, drawScannerZoomIndicator:, drawStickSensitivityIndicator:, drawCompass:, drawAegis:, drawScoopStatus:, drawSpeedBar:, drawRollBar:, drawPitchBar:, drawYawBar:, drawEnergyGauge:, drawForwardShieldBar:, drawAftShieldBar:, drawYellowSurround:, drawGreenSurround:, drawFuelBar:, drawCabinTempBar:, drawWeaponTempBar:, drawAltitudeBar:, drawMissileDisplay:, drawStatusLight:, drawClock:, drawWeaponsOfflineText: or drawFPSInfoCounter:<br />
<br />
1.79 also adds:<br />
drawWaypoints:, drawPrimedEquipment:, drawASCTarget:, drawWitchspaceDestination:<br />
<br />
1.81 also adds:<br />
drawSurround: (like drawYellowSurround: but allows a "color" attribute to be specified),<br />
drawCustomBar:, drawCustomIndicator:, drawCustomText:, drawCustomLight:, drawCustomImage:<br />
<br />
=== align ===<br />
In 1.79, for the "drawASCTarget:" selector, right-aligns the text to the X coordinate rather than the standard left alignment.<br />
<br />
=== alpha ===<br />
alpha is the transpacency of the dial ranging from 0 to 1.<br />
<br />
=== alert_conditions ===<br />
In Oolite 1.79 or later, this controls which alert conditions the dial appears at. It is a number from 0 to 15, formed by adding together the numbers for the individual alert conditions - 1=docked, 2=green, 4=yellow, 8=red. For example, a dial which only appeared at yellow and red alert condition would have<br />
alert_conditions = 12;<br />
<br />
The default value, which reflects previous behaviour, is 15 (show at all conditions)<br />
<br />
=== color* ===<br />
From Oolite 1.79 there are several color parameters - <code>color, color_low, color_medium, color_high, color_critical, color_surround</code> for influencing the following dials.<br />
* '''drawSpeedBar''': color_low, color_medium, color_high, color_surround<br />
* '''drawRollBar/drawPitchBar/drawYawBar''': color, color_surround<br />
* '''drawEnergyGauge''': color_low, color_medium, color_surround<br />
* '''drawForwardShieldBar/drawAftShieldBar''': color_low, color_medium, color_high, color_surround<br />
* '''drawFuelBar''': color_low, color_medium, color_high, color_surround<br />
* '''drawCabinTempBar''': color_low, color_medium, color_high, color_critical, color_surround<br />
* '''drawAltitudeBar''': color_low, color_medium, color_high, color_critical, color_surround<br />
* '''drawCustomBar''': color_low, color_medium, color_high, color_surround<br />
In general, low, medium and high represent ranges of the size of the bar (with critical for particularly dangerous levels on some dials). On the fuel bar, 'medium' is used for the bar itself, while 'high' and 'low' are used for the distance marker for the current destination system.<br />
<br />
All of these parameters accept any standard format of color specifier.<br />
<br />
=== data_source ===<br />
(1.81 or later)<br />
<br />
The data key set with [[Oolite_JavaScript_Reference:_PlayerShip#setCustomHUDDial|player.ship.setCustomHUDDial]]. Different custom selectors expect different values:<br />
* drawCustomBar: - a number between 0 and 1<br />
* drawCustomIndicator: - a number between -1 and 1<br />
* drawCustomLight: - any valid colour specifier (e.g. "greenColor" or [0.0,0.5,1.0,1.0])<br />
* drawCustomText: - a string<br />
* drawCustomImage: - a string, matching the filename of an image in the Images folder. Note that width and height can but do not need to be set on this dial. If they are set, all images will be scaled to that size. If they are not set, images will appear at their natural size. The image, like legend images, will be centred on the x and y coordinates.<br />
<br />
=== draw_surround ===<br />
A box is drawn around the dial when set to 'yes'.<br />
<br />
=== equipment_required ===<br />
The dials is only drawn if the required equipment is present.<br />
<br />
=== height ===<br />
The height of the dial.<br />
<br />
=== labeled ===<br />
Adds bank numbers to the energy banks. Does nothing for other dials.<br />
<br />
=== n_bars ===<br />
For "drawEnergyGauge:", determines how many energy banks are drawn. Without this key, the system chops the total energy in banks with a minimum of 64 units for each bank. (more precisely: n_bars = integer(maxEnergy/64) )<br />
<br />
For "drawPrimedEquipment:", if this is set to >1 (odd numbers may be better than even) also shows some previous and next primable equipment in the cycle.<br />
<br />
Ignored for other dials.<br />
<br />
=== rgb_color ===<br />
Determines the color of some dials.<br />
Example:<br />
rgb_color = (1.0, 0.0, 0.0);<br />
<br />
=== reticle_scale ===<br />
(1.79 or later)<br />
<br />
Determines the minimum proportion of the screen taken up by the targeting reticle in 'drawTargetReticle' and the waypoint indicator in 'drawWaypoints'. Does nothing for other dials<br />
<br />
=== spacing ===<br />
Determines spacing between the missile icons in the 'drawMissileDisplay'. Does nothing for other dials.<br />
<br />
=== viewscreen_only ===<br />
(1.81 or later)<br />
<br />
If this is set to true, then the HUD dial will only be displayed when looking at space (internal or external view) and not on GUI screens such as the market or the charts. This should generally be set for any dial positioned with 'x' between -256 and +256 and 'y' between -160 and +256, as otherwise they will overlap the GUI text.<br />
<br />
Note: in Oolite 1.82 and earlier there is a bug with the processing of this setting which mean that the only 'true' value which is accepted is '1' - 'yes' and 'true' will be incorrectly treated as 'false'. Use <code>viewscreen_only = 1;</code> for compatibility with both 1.82 and later versions.<br />
<br />
=== x ===<br />
x is the x-position of the dial on screen.<br />
<br />
=== y ===<br />
y is the y-position of the dial on screen. <br />
<br />
=== x_origin ===<br />
x_origin = 1.0 means that the x co-ordinate is interpreted relative to the right hand side of the screen. If x_origin is set to 0 or unspecified, then x is interpreted relative to the middle of the screen. x_origin = -1.0 means that the x co-ordinate is interpreted relative to the left hand side of the screen.<br />
N.B. it is preferable to define hud elements relative to the screen borders, so that hud elements fit better on all height/width ratio screens. <br />
<br />
=== y_origin ===<br />
y_origin = -1.0 means that y is relative to the screen bottom. If y_origin is set to 0 or unspecified, then y is interpreted relative to the middle of the screen , and similarly for y_origin. y_origin = 1.0 means that the y co-ordinate is interpreted relative to the top of the screen.<br />
<br />
=== width ===<br />
The width of the dial.<br />
<br />
== legends ==<br />
The legends are listed here as an array of individual legends. Each legends is a separate directory. The legends looks for example like:<br />
legends = (<br />
{<br />
text = "FWD";<br />
align = 1;<br />
x = -245;<br />
y = 86;<br />
y_origin = -1;<br />
height = 12;<br />
width = 12;<br />
with_dial = "drawForwardShieldBar:";<br />
}, <br />
{<br />
image = "myImage.png";<br />
x = -164;<br />
y = 72;<br />
y_origin = 1;<br />
height = 40;<br />
width = 40;<br />
alpha = 0.5;<br />
}<br />
)<br />
<br />
"text" is the text to be displayed, while "image" is a texture file to be shown. If both are specified, "image" is used.<br />
<br />
"alpha", "viewscreen_only" (1.81 onwards), "x", "y", "x_origin" and "y_origin" have the same meaning as on the dials. "height" and "width" control the height and width of the text characters (and should generally be the same number). "align", on a text dial, can be set to 1 to right-align the text (as with the "drawASCTarget:" dial) from 1.79 onwards.<br />
<br />
"with_dial" in 1.79 onwards indicates that this legend should only be shown if the corresponding dial is [[Oolite_JavaScript_Reference:_PlayerShip#hideHUDSelector|visible]]<br />
<br />
In 1.81, the "color" property of a legend may be set. In previous versions text legends are always green.<br />
<br />
== multi_function_displays ==<br />
In 1.79 or later the multi-function displays are listed here as an array. Each entry is a dictionary of parameters<br />
multi_function_displays = (<br />
{<br />
width = 198;<br />
height = 132;<br />
x = -156;<br />
y = -72;<br />
y_origin = 1;<br />
},<br />
{<br />
width = 198;<br />
height = 132;<br />
x = 156;<br />
y = -72;<br />
y_origin = 1;<br />
}<br />
);<br />
<br />
In 1.81 or later the "color" property is also available to change them from green if this suits the HUD better.<br />
<br />
== overall_alpha ==<br />
The overall tranparency of the hud can be set with overall_alpha.<br />
<br />
Example:<br />
overall_alpha = 0.75;<br />
<br />
== reticle_target_sensitive ==<br />
This key determines if the reticle should become red when on-target.<br />
<br />
Example:<br />
reticle_target_sensitive = no;<br />
<br />
== comm_log_gui ==<br />
Determines the location and the specifications of the comm_log_gui and contains a directory of keys.<br />
<br />
Example:<br />
<br />
"comm_log_gui" = {<br />
alpha = "0.75";<br />
width = 360;<br />
height = 100;<br />
x = 0;<br />
y = 180;<br />
row_height = 12;<br />
permanent = no;<br />
automatic = yes;<br />
background_rgba = "0.0 0.05 0.45 0.5"; // = default color<br />
};<br />
<br />
== message_gui ==<br />
Determines the location and the specifications of the message_gui and contains a directory of keys.<br />
<br />
Example:<br />
<br />
"message_gui" = {<br />
alpha = "0.75";<br />
width = 480;<br />
height = 160;<br />
x = 0;<br />
y = "-40";<br />
"row_height" = 16;<br />
};<br />
<br />
<br />
--------------------------------------------------------------------------------<br />
[[Category:Oolite]]<br />
[[Category:Oolite scripting]]</div>Cimhttps://wiki.alioth.net/index.php?title=SOTL_Exploration&diff=48417SOTL Exploration2015-08-09T19:42:43Z<p>Cim: SOTL Exploration initial page</p>
<hr />
<div>'''Song of the Labyrinth: Exploration''' is an experimental scenario OXP for Oolite, set in a very different part of space, and a considerably lower-tech environment than the Oolite setting. It currently only works with the nightly builds.<br />
<br />
The colony ship ''Local Maximum'' suffered an extremely severe hyperspace misjump around seventy years ago, arriving in an uncharted system thousands of light years away from known space. The colony ship's hyperdrive was severely damaged, and the dim red star they named Max's Drift had no habitable planets and poor mineral reserves. Most of the ship's internal equipment survived the accident, and the colonists have been able to survive using hydroponics facilities and extracting water and metals from the system's asteroids.<br />
<br />
Mining has recently obtained a small surplus of Uranium and Osmium required for the production of hyperspace fuel, and a cargo shuttle has been extensively refitted to carry a small hyperdrive and a range of survey gear. Its initial task is to survey the local cluster, hoping to find minerals which so far have not been located in exploitable quantities, both to restock the colonists' reserves and to allow fuel and equipment to be produced for a more extended mission.<br />
<br />
==Download==<br />
[http://compsoc.dur.ac.uk/~cim/oolite/SOTL_Exploration_0.4.oxz Download SOTL Exploration 0.4]<br />
<br />
As this is a scenario OXP which changes many of Oolite's basic rules, it is disabled in conventional Oolite games, and requires the starting of a new game from a special position to play it. This position is available in the [http://compsoc.dur.ac.uk/~cim/oolite/Song_of_the_Labyrinth_Startup_1.1.oxz SOTL Startup 1.1] OXP (for technical reasons this must be downloaded separately)<br />
<br />
None of your normal OXPs will be used in a SOTL Exploration game.<br />
<br />
For more information, see [http://aegidian.org/bb/viewtopic.php?f=4&t=17603 the forum thread]<br />
<br />
===Warning===<br />
This is currently an experimental OXP, and the Startup OXP may need to be updated sometimes when the main OXP is - which will mean you lose any progress (and of course, you also have to use a nightly Oolite build). Comments during development are extremely welcome but don't get too attached to your progress yet.<br />
<br />
==Equipment fitting==<br />
The Shaula-class survey ship you fly can carry ten modules (in addition to the generator and flight computer which must be carried). The initial fitting is 3 fuel tanks, 3 capacitors, 1 gravity sensor, 1 spectroscopic sensor, and 1 prospecting laser, though you can customise this as much as you like before you leave.<br />
<br />
===Flight computer===<br />
The flight computer provides navigation support in both normal space and hyperspace, and integrates the output from your ships sensors - without it, you will have to carry out many more tasks manually, and you are recommended to return to base immediately for repairs. <br />
<br />
It will automatically mark planets once you approach closely enough to get accurate information on their position and speed, and give them a preliminary designation. Information about the currently selected target will be displayed on your HUD<br />
<br />
[[Image:Sotl-scan.png|right]]<br />
<br />
It has three primable modes:<br />
* '''bookmark''': place a waypoint at your current location and heading. Useful if you spot something interesting but can't immediately check it out. Only one bookmark can be used at once.<br />
* '''lagrange''': places a waypoint at each of the 5 Lagrange points of the currently selected planet. Both the planet and star must have mass estimates recorded for this to work. The L4 and L5 points are stable and may contain small clusters of asteroids.<br />
* '''engine mode''': switches the engines between "precision" and "cruise" mode. Cruise mode is significantly faster and will generally be used, but precision mode will make flying near asteroids and docking with the Local Maximum considerably safer. You must be stationary to switch engine modes.<br />
<br />
===Fuel tanks===<br />
Fuel tanks carry hyperspace fuel. Each tank carries 6 tonnes of fuel. A hyperspace jump consumes fuel in tonnes equal to the square root of its distance in LY (i.e. longer jumps are more fuel-efficient). Exiting a jump early will not save fuel. The only current source of fuel is the Local Maximum - plan your jumps carefully or risk being stranded in another system forever.<br />
<br />
===Capacitors===<br />
Capacitors store energy from your generator to provide boosts to particular energy-intensive systems such as the lasers and hyperdrive. The more you have, the more margin for error you have in carrying out tasks, and the longer hyperspace jumps you can safely carry out.<br />
<br />
===Gravity scanner===<br />
[[Image:Sotl-gravity.png|right]]<br />
The gravity scanner allows the mass of nearby stars and planets to be estimated. If multiple are fitted, they are used in parallel to provide more accurate readings. You must be at a complete stop to use it. You may turn with it in use, but this will interfere with the readings.<br />
<br />
Use the mode key ('b') to cycle between the four modes of operation, and press 'n' to activate the current mode:<br />
* power on/off: initial mode, you must switch it off to re-engage drives<br />
* scan on/off: while scanning, it will collect gravitational data, giving you the intensity and direction of the net gravitation force (in the screenshot, below and slightly ahead of the ship). The longer the scan runs for, the more precise a reading you'll get. You can turn the ship while the scan is running, but this will affect the data quality and you'll then need to wait a little bit for it to settle. Once you're happy with the data collected, press 'n' to stop the scan<br />
* assign scan: assigns the scan data to the selected compass target (you need to pick for yourself what object you believe to be the gravitationally dominant one). The system will filter out components of the gravitational force not parallel to the direction of the target, and then use that to calculate surface gravity<br />
* filter scan: if you already know the approximate mass of an object from a previous scan, you can filter it out of the scan by selecting it with the compass and pressing 'n' in this mode. This lets you get more accurate readings for unmeasured objects, and with sufficient practice and luck can also help you find undiscovered planets.<br />
<br />
===Spectroscopic scanner and prospecting laser===<br />
The spectroscopic scanner lets you determine the composition of stars, planets and asteroids by measuring emitted or reflected light. It returns the relative amounts of ten elements or compounds of particular survey interest, on a logarithmic scale.<br />
[[Image:Sotl-spectroscopic.png|right]]<br />
To use it, point your ship at the thing you want to scan, target it with compass or ident as appropriate, activate the sensor with 'n', and cycle the mode to the correct scan (star, planet or asteroid) with 'b'. Then, activate the scan with 'n' and watch the composition bars climb.<br />
<br />
If the target is an asteroid, you'll need to fire the prospecting laser to get anything decent out of the scan.<br />
<br />
When the scan looks done, press 'n' again to stop the scan and assign the results to the targeted body. Stars and planets are targeted with the compass; asteroids with the ident system.<br />
<br />
Try to stop the scan when the highest of the ten bars reaches the top but no later. Stop too soon and you'll not have collected enough light and may miss some important trace components or have inaccuracies in parameters; stop too late and you'll oversaturate the sensors and corrupt the result.<br />
<br />
The bars will go up faster the closer you are to the object, which reduces measurement noise - as does fitting multiple units - though this must be balanced against the risk of oversaturation.<br />
<br />
You get different information depending on what you targeted<br />
* '''Stars''': brightness, and metallicity. Metallicity gives you a very rough idea of how likely the system is to be dense in heavy elements, based on the traces of them in the corona.<br />
* '''Planets''': surface temperature and atmosphere type<br />
* '''Asteroids''': mineral composition (there are a lot of potential minerals, so there's two scan types). Any minerals detected in exploitable amounts will be noted on scan completion - the threshold is a lot lower for the rare ones.<br />
<br />
===Sampling laser and sample collection bay===<br />
The sampling laser will break small chunks off an asteroid - ideally one you have previously scanned with the prospecting laser - which can then be scooped into the sample collection bay and returned to the Local Maximum for extraction of valuable minerals. Each collection bay will hold 15 samples. (On particularly mineral-rich asteroids, a single sample may contain multiple usable minerals)<br />
<br />
==Hyperspace==<br />
Hyperspace travel is dangerous - especially in a ship as improvised as the Shaula-class. When you activate the hyperdrive, an additional instrument display will be projected on to your HUD<br />
[[Image:sotl-hyperspace.png|right]]<br />
<br />
# Above: progress to destination. This starts with you leaving the gravitational influence of your current system, then travelling through hyperspace, then entering your destination system. If you need to drop out mid-jump, this will determine where you end up.<br />
# Right: current energy reserves. Hyperspace travel is energy-intensive. If you run out of energy mid-jump, your ship will be destroyed as it fails to maintain hyperspatial integrity. You can press 'h' again to abort the jump and drop out away from your destination, which will damage your ship due to the rough exit, but you should at least survive.<br />
# Centre: jump status. If this is yellow or green the jump is going well. If orange, you are losing energy fast but should have sufficient reserves to finish the jump. If red, you do not have sufficient reserves at the current rate of energy loss to complete the jump (this will start flashing red/black if you have fewer than 5 seconds available)<br />
# Left, bottom: jump alignment. You need to handle a lot of the jump yourself. Keep the yellow marks aligned with the green ones using your pitch and roll controls - the closer the alignment, the less energy you will need to maintain hyperspatial integrity.<br />
<br />
The pattern you need to align to is a property of the particular jump you are making, so with practice you can use less energy. Additionally, the more times you complete a jump the more computer assistance you receive with future jumps on the same route, which reduces the precision needed to maintain energy levels. (This means you need to carry fewer energy banks and can carry more survey equipment instead)<br />
<br />
Jumps are non-linear:<br />
- time aligning in hyperspace needed to complete the jump is proportional to distance<br />
- real time taken is proportional to distance squared<br />
- fuel usage is proportional to the square root of the distance<br />
<br />
As large masses travel through normal space, they leave ripples behind them in the hyperspace medium, and semi-stable calm points. The larger the mass, the better the calm point. For this reason, a successful jump will place you in the calm point for the system's star. <br />
<br />
==Version History==<br />
* 0.1: unreleased, hyperspace changes only<br />
* 0.2: first public release, added gravity scanner, stars, planets<br />
* 0.3: added spectroscopic scanner, asteroids, prospecting laser<br />
* 0.4: added sampling laser and collection bay, adjusted HUD to be easier to read when facing star</div>Cimhttps://wiki.alioth.net/index.php?title=File:Sotl-hyperspace.png&diff=48416File:Sotl-hyperspace.png2015-08-09T19:29:44Z<p>Cim: </p>
<hr />
<div></div>Cimhttps://wiki.alioth.net/index.php?title=File:Sotl-spectroscopic.png&diff=48415File:Sotl-spectroscopic.png2015-08-09T19:19:30Z<p>Cim: </p>
<hr />
<div></div>Cimhttps://wiki.alioth.net/index.php?title=File:Sotl-gravity.png&diff=48414File:Sotl-gravity.png2015-08-09T19:16:15Z<p>Cim: </p>
<hr />
<div></div>Cimhttps://wiki.alioth.net/index.php?title=File:Sotl-scan.png&diff=48413File:Sotl-scan.png2015-08-09T19:15:24Z<p>Cim: </p>
<hr />
<div></div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Ship&diff=48209Oolite JavaScript Reference: Ship2015-07-09T17:07:20Z<p>Cim: /* equipmentStatus */ 1.81 notes</p>
<hr />
<div><small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Entity|Entity]]</code></small><br /><br />
<small>'''Subtypes:''' <code>[[Oolite JavaScript Reference: Station|Station]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code></small><br />
<br />
The '''<code>Ship</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing a ship, station, missile, cargo pod or other flying item – anything that can be specified in [[shipdata.plist]]. A <code>Ship</code> has all the properties and methods of a <code>Entity</code>, and several others.<br />
<br />
<code>[[Oolite JavaScript Reference: Station|Station]]</code>s and the <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code> are types of ship. Note that these more specific types have additional properties and methods.<br />
<br />
== Properties ==<br />
=== <code>accuracy</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''accuracy''' : Number (read/write, read-only and irrelevant for player ship)<br />
The accuracy of the ship's AI. Varies between -5 and +10 for ships, or 0 and +10 for missiles. Setting a value outside the allowed range will set the closest value within the allowed range.<br />
<br />
For missiles, this affects the missile tracking, with 0 being the default value.<br />
<br />
For NPC ships, this affects their combat AI in many ways. Values of +5 or higher enable various [[OXP_NPC_Combat_AI|special combat AIs]] for a tough fight.<br />
<br />
=== <code>aftWeapon</code> ===<br />
'''aftWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped aft weapon, or <code>null</code>.<br />
<br />
'''See also:''' <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>AI</code> ===<br />
'''AI''' : String (read-only)<br />
The name of the ship’s current plist-based state machine AI. If the ship is using Javascript-based AI, this will always be "<code>nullAI.plist</code>"<br />
<br />
'''See also:''' <code>[[#AIState|AIState]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AIScript|AIScript]]</code><br />
<br />
=== <code>AIFoundTarget</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''AIFoundTarget''' : Entity (read/write, read-only for player)<br />
The "found target" of the ship's AI. This is set by various AI state commands, and is often copied to the primary target with the <code>setTargetToFoundTarget</code> AI command.<br />
<br />
=== <code>AIPrimaryAggressor</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''AIPrimaryAggressor''' : Entity (read/write, read-only for player)<br />
The "primary aggressor" of the ship's AI. Often the last ship to attack this ship.<br />
<br />
=== <code>AIScript</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''AIScript''' : String (read-only)<br />
The name of the ship’s current Javascript-based AI. If the ship is using plist-based AI, this will always be "<code>oolite-nullAI.js</code>"<br />
<br />
'''See also:''' <code>[[#AIScriptWakeTime|AIScriptWakeTime]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AI|AI]]</code><br />
<br />
=== <code>AIScriptWakeTime</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''AIScriptWaketime''' : Number (read-write)<br />
The next game time at which the ship's Javascript-based AI script will receive an <code>aiAwoken</code> event.<br />
<br />
=== <code>AIState</code> ===<br />
'''AIState''' : String (read/write, read-only for player)<br />
The ship’s plist AI’s current state.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#reactToAIMessage|reactToAIMessage()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code><br />
<br />
=== <code>alertCondition</code> ===<br />
'''alertCondition''' : Number (read-only integer)<br />
The ship's current alert condition (Docked = 0, Green = 1, Yellow = 2, Red = 3). Non-Station non-Player ships are generally only found at condition Yellow or Red.<br />
<br />
'''See also:''' [[Oolite_JavaScript_Reference:_Station#alertCondition|station.alertCondition]]<br />
<br />
=== <code>autoAI</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''autoAI''' : Boolean (read-only)<br />
The value of the "<code>auto_ai</code>" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the AI of this ship to better fit into scenarios or roles. If this is false, the ship's provider would prefer you not to alter the AI of this ship but to use it as-is.<br />
<br />
=== <code>autoWeapons</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''autoWeapons''' : Boolean (read-only)<br />
The value of the "<code>auto_weapons</code>" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the properties of this ship to better fit into scenarios or roles. If this is false, the ship's provider would prefer you not to alter the properties of this ship but to use it as-is.<br />
<br />
=== <code>beaconCode</code> ===<br />
'''beaconCode''' : String (read-only in 1.76, read-write from 1.77)<br />
If the ship is a beacon, an identifying string. The first character is used for identification on the [[Advanced Space Compass]]. For non-beacons, this property is <code>null</code>. This can not be changed by script for either the player's ship or the main station.<br />
<br />
'''See also:''' <code>[[#isBeacon|isBeacon]]</code><br />
<br />
=== <code>beaconLabel</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''beaconLabel''' : String (read/write)<br />
A full label for the beacon. This is useful where the beacon code and the full beacon label do not begin with the same letter.<br />
<br />
=== <code>boundingBox</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''boundingBox''' : Vector (read-only)<br />
For ships, a vector describing the dimensions of the cuboid box containing the ship aligned to the ship axes, including all non-flasher sub-entities. For sub-entities, the dimensions of the box for the sub-entity alone.<br />
<br />
Vector components match the standard model order - <code>x</code> is width, <code>y</code> is height, <code>z</code> is length.<br />
<br />
=== <code>bounty</code> ===<br />
'''bounty''' : Number (read/write integer)<br />
The bounty on the ship.<br />
<br />
In 1.77, changes to the bounty are given a reason. If you change this directly, the reason sent to [[Oolite_JavaScript_Reference:_ship_script_event_handlers#shipBountyChanged|shipBountyChanged]] will be "scripted". To set a different reason, use [[#setBounty|setBounty]] instead.<br />
<br />
=== <code>cargoList</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''cargoList''' : Array (read-only)<br />
A list of the ship's current cargo, grouped by cargo type. For the player ship, this is equivalent to <code>player.ship.manifest.list</code><br />
<br />
=== <code>cargoSpaceCapacity</code> ===<br />
'''cargoSpaceCapacity''' : Number (read-only in 1.80, read/write in 1.81, integer)<br />
The ship’s cargo capacity, in tons.<br />
<br />
=== <code>collisionExceptions</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''collisionExceptions''' : Array (read-only)<br />
A list of ships this ship is currently prevented from colliding with. See [[#addCollisionException|addCollisionException]] and [[#removeCollisionException|removeCollisionException]].<br />
<br />
=== <code>commodity</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''commodity''' : String (read-only)<br />
The commodity for cargo containers as a lowercase string. Returns <code>null</code> for non-cargo ships. For scripted cargo that has no specific cargo defined, it returns the general description "goods".<br />
<br />
=== <code>commodityAmount</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''commodityAmount''' : Number (read-only)<br />
The amount of commodity in a cargo container. (not the number of containers in a ship)<br />
<br />
=== <code>contracts</code> ===<br />
'''contracts''' : Array (read-only NSDictionary)<br />
The ship’s contracts. (For now only available for the player). Each contract contains the entries: <code>commodity: string, quantity: integer, description: string, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
<br />
For example, the information of the first contract can be obtained by:<br />
player.ship.contracts[0].commodity<br />
player.ship.contracts[0].quantity<br />
player.ship.contracts[0].description<br />
player.ship.contracts[0].start<br />
player.ship.contracts[0].destination<br />
player.ship.contracts[0].startName<br />
player.ship.contracts[0].destinationName<br />
player.ship.contracts[0].eta // Estimated Time of Arrival.<br />
player.ship.contracts[0].etaDescription<br />
player.ship.contracts[0].fee // The profit of the contract, paid out on successful delivery.<br />
player.ship.contracts[0].premium // The sum paid to obtain the goods and paid back on successful delivery.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this contract, and premium was the amount the player had to pay to secure this contract.<br />
<br />
=== <code>cloakAutomatic</code> ===<br />
'''cloakAutomatic''' : Boolean (read/write)<br />
If <code>true</code> (the default), the ship will automatically engage its cloak while attacking. Otherwise, it must be managed by a script. The corresponding ''[[shipdata.plist]]'' key is <code>cloak_automatic</code>.<br />
<br />
=== <code>crew</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''crew''' : Array (read-only)<br />
An array containing the ship's crew. Each crew member is represented as a dictionary. Note that in current Oolite versions ships only have a single crew member defined.<br />
<br />
=== <code>cruiseSpeed</code> ===<br />
'''cruiseSpeed''' : Number (read-only nonnegative)<br />
The ship’s “normal” <code>[[#desiredSpeed|desiredSpeed]]</code>, used in normal flight. Normally this is 80 % of <code>[[#maxSpeed|maxSpeed]]</code>, but it may be lowered when accepting a slow escort.<br />
<br />
=== <code>currentWeapon</code> ===<br />
{{oolite-prop-added|1.77}} <br />
'''currentWeapon''' : EquipmentType (read/write)<br />
A shortcut property to whichever of <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code> or <code>[[#starboardWeapon|starboardWeapon]]</code> represents the ship's currently active laser mount.<br />
<br />
=== <code>dataKey</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''dataKey''' : String (read-only)<br />
The ship data key used to define this ship (e.g. <code>adder-player</code> or <code>coriolis-station</code>)<br />
<br />
=== <code>defenseTargets</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''defenseTargets''' : Array (read-only)<br />
The array of defense targets that the ship has. If the ship has point defense weapons (turrets, thargoid lasers) it may fire them at these targets if it cannot hit its primary target.<br />
<br />
'''See also:''' <code>[[#addDefenseTarget|addDefenseTarget]]</code>, <code>[[#clearDefenseTargets|clearDefenseTargets]]</code><br />
<br />
=== <code>desiredRange</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''desiredRange''' : Number (read/write nonnegative, read-only for player)<br />
The range the AI uses in various AI routines to set a distance between the ship and another object - for example, the radius of a sphere around a destination point, or the distance to flee from a hostile ship.<br />
<br />
=== <code>desiredSpeed</code> ===<br />
'''desiredSpeed''' : Number (read/write nonnegative, read-only for player)<br />
The speed the AI will attempt to maintain. The AI core and AI script may change this from time to time. The corresponding AI method is <code>setSpeedFactorTo:</code>; a speed factor of 1.0 corresponds to a <code>desiredSpeed</code> equal to <code>[[#maxSpeed|maxSpeed]]</code>.<br />
<br />
'''See also:''' <code>[[#cruiseSpeed|cruiseSpeed]]</code><br />
<br />
=== <code>destination</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''destination''' : Vector (read/write, read-only for player)<br />
The destination coordinates for the AI, used in behaviours such as <code>performFlyToRangeFromDestination</code>.<br />
<br />
=== <code>destinationSystem</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''destinationSystem''' : Number (read/write)<br />
The destination system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.<br />
<br />
=== <code>displayName</code> ===<br />
'''displayName''' : String (read/write, read-only for player)<br />
The name of the ship as seen by the player. By default in 1.78 or earlier it is the same as <code>[[#name|name]]</code>. In 1.79 or later it is a combination of [[#shipClassName|shipClassName]] and [[#shipUniqueName|shipUniqueName]]<br />
<br />
=== <code>dockingInstructions</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''dockingInstructions''' : Object (read-only)<br />
If the ship is currently attempting to dock with a station, this describes the next step on its docking procedure<br />
<br />
{<br />
station: [Station "Coriolis Station" "Coriolis Station" position: (-31043.6, -94232.3, 619036) scanClass: CLASS_STATION status: STATUS_ACTIVE],<br />
match_rotation: 0,<br />
ai_message: "APPROACH_COORDINATES",<br />
speed: 512,<br />
destination: {<br />
x: -28033.37401563089,<br />
y: -92813.76688970842,<br />
z: 622226.0625336492<br />
},<br />
range: 96<br />
}<br />
<br />
'''See also:''' <code>[[#requestDockingInstructions|requestDockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code><br />
<br />
=== <code>energyRechargeRate</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''energyRechargeRate''' : Number (read-only, read/write from 1.81)<br />
The rate at which energy is replenished in every second. The corresponding ''[[shipdata.plist]]'' key is <code>energy_recharge_rate</code>.<br />
<br />
Note for the player ship that this includes the boost from an extra or naval energy unit, and NPC (but not player) ships with military shield boosters also have an increase to this in lieu of actual shields.<br />
<br />
=== <code>entityPersonality</code> ===<br />
'''entityPersonality''' : Number (read-only integer, read/write in 1.81 onwards)<br />
A random number in the range 0..32767 which is generated when the ship is created. Equivalent to the <code>entityPersonalityInt</code> [[Shaders in Oolite: uniforms#Ship|uniform binding]].<br />
<br />
Altering this value is possible in 1.81 onwards, but requires a re-bind of the materials and shaders, and so is a relatively slow process.<br />
<br />
=== <code>equipment</code> ===<br />
'''equipment''' : Array of [[Oolite_JavaScript_Reference:_EquipmentInfo|EquipmentInfo ]] (read-only)<br />
The equipment a ship is carrying.<br />
<br />
=== <code>escortGroup</code> ===<br />
'''escortGroup''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]<br />
The ship’s deployed escorts.<br />
<br />
'''See also:''' <code>[[#maxEscorts|maxEscorts]]</code><br />
<br />
=== <code>escorts</code> ===<br />
'''escorts''' : Array (read-only array of [[Oolite JavaScript Reference: Entity|Entity]]s)<br />
The ship’s deployed escorts.<br />
<br />
=== <code>exhaustEmissiveColor</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''exhaustEmissiveColor''' : Color (read/write)<br />
The baseline colour of the ship's exhaust. Damage to the ship, and use of injectors and torus drive, apply a fixed transformation to this colour, so not all colours are effective as exhaust colours.<br />
<br />
=== <code>exhausts</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''exhausts''' : Array (read-only)<br />
An array of the ship's [[Oolite_JavaScript_Reference:_ExhaustPlume|ExhaustPlume]] subentities.<br />
<br />
=== <code>extraCargo</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''extraCargo''' : Number (read-only integer)<br />
The amount the cargo capacity increases when an extra cargobay is installed. The corresponding ''[[shipdata.plist]]'' key is <code>extra_cargo</code>.<br />
<br />
=== <code>flashers</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''flashers''' : Array (read-only)<br />
An array of the ship's [[Oolite_JavaScript_Reference:_Flasher|Flasher]] subentities.<br />
<br />
=== <code>forwardWeapon</code> ===<br />
'''forwardWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped forward weapon, or <code>null</code>.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>fuel</code> ===<br />
'''fuel''' : Number (read/write)<br />
The ship’s current fuel capacity, in LY. The game will limit this to the range 0..7, and round it off to the nearest tenth.<br />
<br />
'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#fuelLeakRate|PlayerShip.fuelLeakRate]]</code><br />
<br />
=== <code>fuelChargeRate</code> ===<br />
'''fuelChargeRate''' : Number (read-only)<br />
The cost, relative to the cost for a new Cobra III, of a unit of fuel. When buying fuel for a ship, the price in [[equipment.plist]] will be multiplied by this number.<br />
<br />
=== <code>group</code> ===<br />
'''group''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]<br />
Contains ship’s belonging to each other. Added pirate groups are an example or a station with its launched defenders.<br><br />
A group is an individual object that can be linked to several ships belonging to the same group. When a ship dies and the group object has still owners, the group stays active as object. The group is only removed from memory after the last ship that had this group as property is removed.<br><br />
Adding a group to a ship does not automatic puts that ship in the group. For that to happen you need also use the addShip() command. <br />
e.g. <br />
this.ship.group = new ShipGroup();<br />
this.ship.group.addShip(this.ship);<br />
<br />
=== <code>hasHostileTarget</code> ===<br />
'''hasHostileTarget''' : Boolean (read-only)<br />
<code>true</code> if the ship’s AI is trying to kill something, <code>false</code> otherwise. Always <code>false</code> for the player.<br />
<br />
=== <code>hasHyperspaceMotor</code> ===<br />
'''hasHyperspaceMotor''' : Boolean (read-only)<br />
True if the ship can make witchspace jumps. The corresponding ''[[shipdata.plist]]'' entry is <code>hyperspace_motor</code>.<br />
<br />
=== <code>hasSuspendedAI</code> ===<br />
'''hasSuspendedAI''' : Boolean (read-only)<br />
<code>true</code> if the ship has suspended AIs, <code>false</code> otherwise.<br />
<br />
=== <code>heatInsulation</code> ===<br />
'''heatInsulation''' : Number (read/write)<br />
The ship’s heat insulation factor. 1.0 is normal, higher values mean more resistance to heat.<br />
<br />
Note that in 1.80 and earlier writes to this property had no effect on the player ship.<br />
<br />
=== <code>homeSystem</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''homeSystem''' : Number (read/write)<br />
The home system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.<br />
<br />
=== <code>hyperspaceSpinTime</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''hyperspaceSpinTime''' : Number (read/write)<br />
The length of the ship's hyperspace countdown.<br />
<br />
Setting this to a negative value disables the drive entirely.<br />
<br />
Note that most NPC ship jumps use <code>ship.exitSystem()</code> to make the jump, which does not have a delay. Provided this value is zero or positive, the ship will jump instantly if <code>ship.exitSystem()</code> is called. The AI must use this property elsewhere if a delay before jumping is required.<br />
<br />
=== <code>injectorBurnRate</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorBurnRate''' : Number (read/write)<br />
The rate at which the ship's injectors burn fuel in deci-LY per second. The default is 0.25.<br />
<br />
=== <code>injectorSpeedFactor</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorSpeedFactor''' : Number (read/write)<br />
The multiplier to maximum speed granted to this ship when it is using injectors. The default is 7, and values must be between 1.0 and 32.0 (the torus drive's speed)<br />
<br />
=== <code>isBeacon</code> ===<br />
'''isBeacon''' : Boolean (read-only)<br />
<code>true</code> if the ship is a beacon (i.e., can show up on the [[Advanced Space Compass]] with a character indicating its identity), <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#beaconCode|beaconCode]]</code><br />
<br />
=== <code>isBoulder</code> ===<br />
'''isBoulder''' : Boolean (read/write)<br />
<code>true</code> if the ship is a boulder (i.e., has the role "boulder in its roleset)<br />
<br />
=== <code>isCargo</code> ===<br />
'''isCargo''' : Boolean (read-only)<br />
<code>true</code> if the ship is cargo (i.e., has scan_class CLASS_CARGO and contains at least one unit)<br />
<br />
=== <code>isCloaked</code> ===<br />
'''isCloaked''' : Boolean (read/write)<br />
<code>true</code> if the ship has a cloaking device which is currently active <code>false</code> otherwise. If the ship has a cloaking device and sufficient energy to use it (<code>energy > 0.75 * [[Oolite JavaScript Reference: Entity#maxEnergy|maxEnergy]]</code>), you can activate it by setting <code>isCloaked</code> to <code>true</code>.<br />
<br />
=== <code>isDerelict</code> ===<br />
'''isDerelict''' : Boolean (read-only)<br />
<code>true</code> if the ship is a derelict (i.e., the pilot has ejected from the ship, or the ship was created with the ship-key: "is_hulk")<br />
<br />
=== <code>isFleeing</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isFleeing''' : Boolean (read-only)<br />
<code>true</code> if the ship is currently fleeing combat. This may be queried for the player ship too, though the value is somewhat of a guess in that case as it's impossible to say for certain what the player is intending by their actions.<br />
<br />
=== <code>isFrangible</code> ===<br />
'''isFrangible''' : Boolean (read-only)<br />
<code>true</code> if the ship is frangible (i.e., its subentities can be destroyed separately from the main ship), <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>isJamming</code> ===<br />
'''isJamming''' : Boolean (read-only)<br />
<code>true</code> if the ship has a military scanner jammer which is currently active <code>false</code> otherwise.<br />
<br />
=== <code>isMinable</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isMinable''' : Boolean (read-only)<br />
<code>true</code> if the ship will break up usefully when hit by a mining laser, <code>false</code> otherwise. By default this is true for anything with "asteroid" or "boulder" in its role list - if you need to add anything which miners shouldn't be shooting at to those roles, give it <code>"no_boulders" = yes;</code> in its [[shipdata.plist]].<br />
<br />
=== <code>isMine</code> ===<br />
'''isMine''' : Boolean (read-only)<br />
<code>true</code> if the ship is a mine, <code>false</code> otherwise.<br />
<br />
=== <code>isMissile</code> ===<br />
'''isMissile''' : Boolean (read-only)<br />
<code>true</code> if the ship is a missile, <code>false</code> otherwise.<br />
<br />
=== <code>isPiloted</code> ===<br />
'''isPiloted''' : Boolean (read-only)<br />
<code>true</code> if the ship has a pilot on board, <code>false</code> otherwise. Generally have ships, station and escape pods pilots and have cargo, rocks, missiles or buoys no pilots.<br />
<br />
=== <code>isPirate</code> ===<br />
'''isPirate''' : Boolean (read-only)<br />
<code>true</code> if the ship is a pirate vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "pirate"</code>.<br />
<br />
=== <code>isPirateVictim</code> ===<br />
'''isPirateVictim''' : Boolean (read-only)<br />
<code>true</code> if the ship’s [[#primaryRole|primary role]] is listed in ''pirate-victim-roles.plist'', <code>false</code> otherwise. This is the same test used by the pirate AI to select victims.<br />
<br />
=== <code>isPolice</code> ===<br />
'''isPolice''' : Boolean (read-only)<br />
<code>true</code> if the ship is a police vessel, <code>false</code> otherwise. Currently equivalent to <code>[[Oolite JavaScript Reference: Entity#scanClass|scanClass]] == "CLASS_POLICE"</code>.<br />
<br />
=== <code>isRock</code> ===<br />
'''isRock''' : Boolean (read-only)<br />
<code>true</code> if the ship is a rock (i.e., has scan_class: CLASS_ROCK)<br />
<br />
=== <code>isThargoid</code> ===<br />
'''isThargoid''' : Boolean (read-only)<br />
<code>true</code> if the ship is a Thargoid vessel, <code>false</code> otherwise. Currently equivalent to <code>[[Oolite JavaScript Reference: Entity#scanClass|scanClass]] == "CLASS_THARGOID"</code>.<br />
<br />
=== <code>isTrader</code> ===<br />
'''isTrader''' : Boolean (read-only)<br />
<code>true</code> if the ship is a merchant vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "trader" || isPlayer</code>. '''Note:''' <code>[[#isPirateVictim|isPirateVictim]]</code> may be a better choice in many cases.<br />
<br />
=== <code>isTurret</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isTurret''' : Boolean (read-only)<br />
<code>true</code> if the ship is a plasma turret sub-entity, <code>false</code> otherwise.<br />
<br />
=== <code>isWeapon</code> ===<br />
'''isWeapon''' : Boolean (read-only)<br />
<code>true</code> if the ship is a weapon, <code>false</code> otherwise. Currently equivalent to <code>[[#isMissile|isMissile]] || [[#isMine|isMine]] </code>, but new categories of weapon could be added in future.<br />
<br />
=== <code>laserHeatLevel</code>* ===<br />
{{Oolite-prop-added|1.77}}<br />
'''laserHeatLevel''' : Number (read-only, 0 to 1)<br />
The temperature of the ship's currently active weapon. Thermal cut-out is active above 0.85. For non-player ships, if their forward weapon is empty, then the temperature of the forward weapon may be the temperature of a subentity forward weapon.<br />
'''laserHeatLevelAft''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelForward''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelPort''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelStarboard''' : Number (read-only, 0 to 1)<br />
The temperature of specific laser mounts can also be queried.<br />
<br />
=== <code>lightsActive</code> ===<br />
'''lightsActive''' : Boolean (read-write)<br />
Setting this property to <code>true</code> turns on all the entity’s flashers, and setting it to <code>false</code> turns them off. Setting it sets the <code>lightsActive</code> property for all subentities, but subentities’ setting can also be manipulated separately. In addition to affecting flashers, the value can be used by shaders.<br />
<br />
Note: <code>lightsActive</code> is always <code>true</code> when a ship is spawned, although individual flashers may be off because they have <code>initially_on</code> set to false in their ''shipdata.plist'' declarations.<br />
<br />
=== <code>markedForFines</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''markedForFines''' : Boolean (read-only)<br />
<code>True</code> if the ship has been marked for fines the next time it docks at this system's main station.<br />
<br />
'''See also''' : [[#markTargetForFines|markTargetForFines()]]<br />
<br />
=== <code>maxEscorts</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxEscorts''' : Number (read/write)<br />
The maximum number of escorts this ship can have. This cannot be set lower than the number of escorts it currently has, or higher than the value of the MAX_ESCORTS constant (currently 16). There may be other reasons why a ship can have fewer escorts than the value of <code>maxEscorts</code> (for instance, ships which are escorts cannot have their own escorts)<br />
<br />
'''See also:''' <code>[[#escortGroup|escortGroup]]</code><br />
<br />
=== <code>maxPitch</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxPitch''' : Number (read-only, read/write from 1.81)<br />
The maximum pitch rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#pitch|pitch]]</code><br />
<br />
=== <code>maxRoll</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxRoll''' : Number (read-only, read/write from 1.81)<br />
The maximum roll rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#roll|roll]]</code><br />
<br />
=== <code>maxSpeed</code> ===<br />
'''maxSpeed''' : Number (read-only, read/write from 1.81)<br />
The ship’s maximum speed under normal power. Note that <code>[[#speed|speed]]</code> may exceed this when [[witch fuel injectors]] or [[hyperspeed]] are in use.<br />
<br />
'''See also:''' <code>[[#speed|speed]]</code><br />
<br />
=== <code>maxThrust</code> ===<br />
'''maxThrust''' : Number (read-only, read/write from 1.81)<br />
The ship’s maximum <code>[[#thrust|thrust]]</code>. This value is the one defined as <code>thrust</code> in ''[[Shipdata.plist#thrust|shipdata.plist]]''.<br />
<br />
=== <code>maxYaw</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxYaw''' : Number (read-only, read/write from 1.81)<br />
The maximum yaw rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#yaw|yaw]]</code><br />
<br />
=== <code>missileCapacity</code> ===<br />
'''missileCapacity''' : Number (read-only integer)<br />
The maximum number of missiles the ship can carry.<br />
<br />
=== <code>missileLoadTime</code> ===<br />
'''missileLoadTime''' : Number (read-write nonnegative)<br />
The minimum amount of time between two missiles. The corresponding ''[[shipdata.plist]]'' key is <code>missile_load_time</code>.<br />
<br />
=== <code>missiles</code> ===<br />
'''missiles''' : Array (read-only array of [[Oolite JavaScript Reference: EquipmentInfo|EquipmentInfo]])<br />
The ship’s loaded missiles.<br />
<br />
=== <code>name</code> ===<br />
'''name''' : String (read/write, read-only for player)<br />
The name of the ship type (<code>name</code> key in [[shipdata.plist]]).<br />
<br />
''Note'': while <code>name</code> can be changed, this is discouraged (and will probably not be supported in Oolite 2.0). Use <code>[[#displayName|displayName]]</code> instead.<br />
<br />
=== <code>parcelCount</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''parcelCount''' : Number (read-only integer)<br />
The ship’s current number of parcels.<br />
<br />
=== <code>parcels</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''parcels''' : Array (read-only NSDictionary)<br />
The ship’s parcels. (For now only available for the player). Each parcel list contains the entries: <code>name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
For example, the information of the first contract can be obtained by:<br />
player.ship.parcels[0].name<br />
player.ship.parcels[0].start<br />
player.ship.parcels[0].destination<br />
player.ship.parcels[0].startName<br />
player.ship.parcels[0].destinationName<br />
player.ship.parcels[0].eta<br />
player.ship.parcels[0].etaDescription<br />
player.ship.parcels[0].fee // The final fee, paid out on successful delivery.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this parcel.<br />
<br />
=== <code>passengerCapacity</code> ===<br />
'''passengerCapacity''' : Number (read-only integer)<br />
The ship’s maximum passenger capacity.<br />
<br />
=== <code>passengerCount</code> ===<br />
'''passengerCount''' : Number (read-only integer)<br />
The ship’s current number of passengers.<br />
<br />
=== <code>passengers</code> ===<br />
'''passengers''' : Array (read-only NSDictionary)<br />
The ship’s passengers. (For now only available for the player). Each passengers list contains the entries: <code>name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
For example, the information of the first contract can be obtained by:<br />
player.ship.passengers[0].name<br />
player.ship.passengers[0].start<br />
player.ship.passengers[0].destination<br />
player.ship.passengers[0].startName<br />
player.ship.passengers[0].destinationName<br />
player.ship.passengers[0].eta<br />
player.ship.passengers[0].etaDescription<br />
player.ship.passengers[0].fee // The final fee, paid out on successful delivery.<br />
player.ship.passengers[0].premium // The advance fee, already paid on acceptance of the contract.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this passenger, and premium shows the amount the player received when the passenger boarded the ship.<br />
<br />
=== <code>pitch</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''pitch''' : Number (read-only)<br />
The rate of pitch of the ship in radians/second (positive for dive, negative for climb)<br />
<br />
=== <code>portWeapon</code> ===<br />
'''portWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped port weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>potentialCollider</code> ===<br />
'''potentialCollider''' : [[Oolite JavaScript Reference: Entity|Entity]] (read-only)<br />
The entity the ship is currently trying not to crash into, if any.<br />
<br />
=== <code>primaryRole</code> ===<br />
'''primaryRole''' : String (read/write, read-only for player)<br />
The main role of the ship; the role for which it was created. For instance, if a ship’s ''shipdata.plist'' entry specifies the roles “pirate trader(0.5) escort”, and a ship of that type is spawned to be a trader, its <code>primaryRole</code> is <code>"trader"</code>, its <code>roles</code> is <code>["escort", "pirate", "trader"]</code> and its <code>roleWeights</code> is <code> { "escort":1, "pirate":1, "trader":0.5}</code>.<br />
<br />
'''See also:''' <code>[[#roles|roles]]</code>, <code>[[#roleWeights|roleWeights]]</code><br />
<br />
=== <code>reportAIMessages</code> ===<br />
'''reportAIMessages''' : Boolean (read/write)<br />
Debugging facility: set to <code>true</code> to dump information about AI activity to the log. <br />
<br />
=== <code>roleWeights</code> ===<br />
'''roleWeights''' : Object (read-only)<br />
The probabilities for each role in <code>[[#roles|roles]]</code>.<br />
<br />
Example:<br />
this.pirateProb = ship.roleWeights["pirate"]<br />
<br />
'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roles|roles]]</code><br />
<br />
=== <code>roles</code> ===<br />
'''roles''' : Array (read-only array of Strings)<br />
The roles of the ship. This consists of the roles specified in the ship’s ''shipdata.plist'' entry, as well as the <code>[[#primaryRole|primaryRole]]</code> if it is not among those.<br />
<br />
'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roleWeights|roleWeights]]</code>, <code>[[#hasRole|hasRole()]]</code><br />
<br />
=== <code>roll</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''roll''' : Number (read-only, read/write for stations)<br />
The rate of roll of the ship in radians/second (positive for anti-clockwise, negative for clockwise)<br />
<br />
For stations, this can be set to any value between -2 and +2 to adjust their roll rate. The default is 0.4, or the value specified by the <code>station_roll</code> key in shipdata.plist.<br />
<br />
=== <code>savedCoordinates</code> ===<br />
'''savedCoordinates''' : [[Oolite JavaScript Reference: Vector|Vector]] (read-write)<br />
The savedCoordinates of the ship in system co-ordinates. The savedCoordinates vector is only used by AI scripting to store a coordinate that can be used by other AI commands like <code>setDestinationFromCoordinates</code>. It are the same coordinates that are set by the AI command: <code>"setCoordinates: X Y Z"</code><br />
<br />
=== <code>scanDescription</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''scanDescription''' : String (read/write)<br />
The description of the ship in the "legal status" text shown by the [[Scanner Targeting Enhancement]]. If this is null then the default text for the ship's scan class and bounty level will be shown.<br />
<br />
=== <code>scannerDisplayColor1</code> ===<br />
'''scannerDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The first of two colours used by the ship’s scanner “lollipop”. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning <code>null</code> will restore the value from [[shipdata.plist]], or the default value for the ship’s scan class.<br />
<br />
'''See also:''' <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code>, <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code><br />
<br />
=== <code>scannerDisplayColor2</code> ===<br />
'''scannerDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The second scanner colour. If both <code>scannerDisplayColor1</code> and <code>scannerDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.<br />
<br />
'''See also:''' <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code>, <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code><br />
<br />
=== <code>scannerHostileDisplayColor1</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''scannerHostileDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The first of two colours used by the ship’s scanner “lollipop” when the ship is specifically targeting the player with hostile intent. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning <code>null</code> will restore the value from [[shipdata.plist]], or the default value for the ship’s scan class.<br />
<br />
If hostile colours are set but normal colours aren't, then the normal colours will default to those for the ship's scan class. If normal colours are set but hostile colours aren't, the scanner blip will not change colour when the ship is hostile.<br />
<br />
'''See also:''' <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code>, <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code><br />
<br />
=== <code>scannerHostileDisplayColor2</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''scannerHostileDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The second scanner colour when the ship is specifically targeting the player with hostile intent.. If both <code>scannerHostileDisplayColor1</code> and <code>scannerHostileDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.<br />
<br />
'''See also:''' <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code>, <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code><br />
<br />
=== <code>scannerRange</code> ===<br />
'''scannerRange''' : Number (read-only)<br />
The range of the ship’s scanner.<br />
<br />
=== <code>script</code> ===<br />
'''script''' : [[Oolite JavaScript Reference: Script|Script]] (read-only)<br />
The ship’s script.<br />
<br />
=== <code>scriptedMisjump</code> ===<br />
'''scriptedMisjump''' : Boolean (read/write)<br />
When <code>true</code>, the next hyperspace jump will be a misjump. The <code>scriptedMisjump</code> flag will remain <code>true</code> during the <code>shipWillExitWitchspace()</code> event handler, and will be set to <code>false</code> after the <code>shipExitedWitchspace()</code> event.<br />
<br />
=== <code>scriptedMisjumpRange</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''scriptedMisjumpRange''' : Number (read/write)<br />
If this ship misjumps, this number will be consulted to determine the length of the resulting misjump relative to the normal jump range. Setting this does not in itself force a misjump - this must occur through the usual mechanisms. Values must be greater than 0.0 and less than 1.0, and the default is 0.5 for a traditional half-way misjump. This will be reset to 0.5 at the same time as <code>[[#scriptedMisjump|scriptedMisjump]]</code> is reset to <code>false</code>.<br />
<br />
=== <code>scriptInfo</code> ===<br />
'''scriptInfo''' : Object (read-only)<br />
The contents of the <code>script_info</code> key in the ship’s ''[[shipdata.plist]]'' entry, if any. This may be any [[property list]] object, but the recommended approach is to use a dictionary whose keys have a unique prefix (such as you should be using for file names, ship names etc.). A property list dictionary is converted to a JavaScript object with properties corresponding to the dictionary’s keys. All other property list types used with Oolite have directly corresponding JavaScript types.<br><br />
When using numeric values in the scriptInfo, the JS engine is not able to detect the type reliably on all systems, so you always must explicitly convert its content to a number by using parseInt(scriptInfo.myKey) or parseFloat(scriptInfo.myKey).<br />
<br />
=== <code>shipClassName</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''shipClassName''' : String (read/write)<br />
The name of the ship class (e.g. "Python")<br />
<br />
=== <code>shipUniqueName</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''shipUniqueName''' : String (read/write)<br />
The name of this specific ship (e.g. "Sunrise of Lave")<br />
<br />
=== <code>speed</code> ===<br />
'''speed''' : Number (read-only)<br />
The ship’s current speed.<br />
<br />
'''See also:''' <code>[[#maxSpeed|maxSpeed]]</code><br />
<br />
=== <code>starboardWeapon</code> ===<br />
'''starboardWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped forward weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code><br />
<br />
=== <code>subEntities</code> ===<br />
'''subEntities''' : Array (read-only array of Ships)<br />
The ships subentities, or <code>null</code> if it has none. Special subentities such as flashers and exhaust plumes are not included.<br />
<br />
'''See also:''' <code>[[#isFrangible|isFrangible]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>subEntityCapacity</code> ===<br />
'''subEntityCapacity''' : Number (read-only integer)<br />
The original number of subentities on the ship. <br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>subEntityRotation</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''subEntityRotation''' : Quaternion (read/write)<br />
The subentity rotational velocity, expressed as a quaternion. This much rotation will be applied per second. Exact 180 degree rotations should not be specified, as it is not possible to determine what route to use to make that rotation. This property is ignored when set on non-subentities.<br />
<br />
=== <code>sunGlareFilter</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''sunGlareFilter''' : Number (read/write)<br />
The strength of the sun glare filter on this ship. It must be in the range 0 to 1 (0 is no filter).<br />
<br />
=== <code>target</code> ===<br />
'''target''' : Ship (read-write)<br />
The ship’s primary target, i.e. the entity it will attempt to shoot at. This value is automatically co-ordinated between a ship and its subentities.<br />
<br />
=== <code>temperature</code> ===<br />
'''temperature''' : Number (read/write)<br />
The ship’s temperature, normalized such that a temperature of 1.0 is the level at which a ship starts taking heat damage.<br />
<br />
=== <code>thrust</code> ===<br />
'''thrust''' : Number (read/write for NPCs, read-only for player before 1.81)<br />
The ship’s thrust, ranging from 0 to <code>maxThrust</code>. This value determines how fast the ship accelerates or decelerates, specified in m/s².<br />
<br />
'''See also:''' <code>[[#thrustVector|thrustVector]]</code><br />
<br />
=== <code>thrustVector</code> ===<br />
'''thrustVector''' : Vector3D (read-only)<br />
The inertialess velocity generated by the engines.<br />
<br />
'''See also:''' <code>[[#thrust|thrust]]</code>, <code>[[#velocity|velocity]]</code><br />
<br />
=== <code>trackCloseContacts</code> ===<br />
'''trackCloseContacts''' : Boolean (read/write)<br />
If true, AI events are generated for near collisions.<br />
<br />
=== <code>vectorForward</code> ===<br />
'''vectorForward''' : Vector3D (read-only)<br />
The vector pointing forwards from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorForward|vectorForward]]</code>.<br />
<br />
=== <code>vectorRight</code> ===<br />
'''vectorRight''' : Vector3D (read-only)<br />
The vector pointing right from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorRight|vectorRight]]</code>.<br />
<br />
=== <code>vectorUp</code> ===<br />
'''vectorUp''' : Vector3D (read-only)<br />
The vector pointing up from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorUp|vectorUp]]</code>.<br />
<br />
=== <code>velocity</code> ===<br />
'''velocity''' : Vector3D (read/write)<br />
The ship’s velocity.<br />
<br />
'''Note:''' A ship’s velocity consists of two components, inertial velocity and inertialess thrust. Generally, inertial velocity is zero (so <code>velocity</code> is equal to <code>[[#thrustVector|thrustVector]]</code>), but inertial impulses may be applied if a ship collides or is caught in an explosion. If inertial velocity is non-zero, the ship’s engines will work to counteract it. Changing the ship’s velocity will always apply inertial velocity, so for ships with non-zero <code>[[#maxThrust|maxThrust]]</code> the effect will be temporary.<br />
<br />
'''See also:''' <code>[[#thrustVector|thrustVector]]</code><br />
<br />
=== <code>weaponFacings</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''weaponFacings''' : Number (read-only, integer in range 0-15)<br />
The weapon facings available for the ship. The format is the same as the equivalent property in [[shipyard.plist]] or [[shipdata.plist]] - a bitmask with the following bits:<br><br />
1 - fore<br><br />
2 - aft<br><br />
4 - port<br><br />
8 - starboard<br />
<br />
=== <code>weaponPosition*</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''weaponPositionAft''' : Vector (read-only)<br />
'''weaponPositionForward''' : Vector (read-only)<br />
'''weaponPositionPort''' : Vector (read-only)<br />
'''weaponPositionStarboard''' : Vector (read-only)<br />
The position relative to the ship at which the appropriate laser beam will start. These properties do not imply that the ship has or can have any such weapon.<br />
<br />
=== <code>weaponRange</code> ===<br />
'''weaponRange''' : Number (read-only)<br />
The maximum range of the ship’s primary weapon. For the player it is the range of the weapon that fired as last, even when the view direction changed.<br><br />
Range values are: WEAPON_PLASMA_CANNON: 5000, WEAPON_PULSE_LASER: 12500, WEAPON_BEAM_LASER: 15000, WEAPON_MINING_LASER: 12500, WEAPON_THARGOID_LASER: 17500, WEAPON_MILITARY_LASER: 30000, WEAPON_NONE: 32000.<br><br />
(Turrets are secondary weapons with a maximum range of 6000)<br />
<br />
=== <code>withinStationAegis</code> ===<br />
'''withinStationAegis''' : Boolean (read-only)<br />
<code>true</code> if the ship is within the aegis of the system’s main station (i.e., no more than 51 200 game metres from the station, or twice scanner range).<br />
<br />
=== <code>yaw</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''yaw''' : Number (read-only)<br />
The rate of yaw of the ship in radians/second (positive for right, negative for left)<br />
<br />
== Methods ==<br />
=== <code>abandonShip</code> ===<br />
function '''abandonShip'''() : Boolean<br />
Returns <code>true</code> when the ship has an escapepod. It will launch all escapeposd on board leaving the ship behind as a empty hulk. (scanClass = CLASS_CARGO). This command does nothing when no escape-pod is present.<br><br />
Pressence of an escapepod can be tested with: <code>equipmentStatus("EQ_ESCAPE_POD") == "EQUIPMENT_OK"</code><br />
<br />
=== <code>addCollisionException</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''addCollisionException'''(exception : Ship)<br />
Prevented this ship and the selected ship from colliding. See [[#collisionExceptions|collisionExceptions]] and [[#removeCollisionException|removeCollisionException]].<br />
<br />
Prevention from collision will specifically prevent the following:<br />
<br />
* the ships colliding with each other and suffering collision damage and/or momentum change<br />
* the ships receiving collision warning events if they come close to each other<br />
* if one of the ships is a station, the other ship will not be able to dock with it even if it enters a dock<br />
<br />
This has no useful effect when applied to a subentity.<br />
<br />
Adding a collision exception which already exists has no effect but will not cause an error.<br />
<br />
=== <code>addDefenseTarget</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''addDefenseTarget'''(target : Ship)<br />
Adds the target ship to this ship's list of point [[#defenseTargets|defense targets]], if it isn't already.<br />
<br />
=== <code>adjustCargo</code>===<br />
{{oolite-method-added|1.81}}<br />
function '''adjustCargo'''(commodity : String, amount : Number) : Boolean<br />
Adjust the quantity of the specified commodity carried by the ship. Amount may be negative to remove cargo. The method will return false if the operation would fail due to insufficient free space or carried cargo, and will not make a partial adjustment in this case.<br />
<br />
=== <code>awardEquipment</code> ===<br />
function '''awardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Adds the given piece of equipment to the ship, if possible, returning <code>true</code> if successful and <code>false</code> otherwise.<br />
<br />
Example:<br />
ship.awardEquipment("EQ_ECM");<br />
<br />
'''See also:''' <code>[[#canAwardEquipment|canAwardEquipment()]]</code>, <code>[[#removeEquipment|removeEquipment()]]</code><br />
<br />
=== <code>canAwardEquipment</code> ===<br />
function '''canAwardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Tests whether it is possible to add a given equipment type. This command takes the conditions for offering inside equipment.plist into account. Returns <code>true</code> if <code>[[#awardEquipment|awardEquipment()]]</code> is expected to succeed, <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#awardEquipment|awardEquipment()]]</code><br />
<br />
=== <code>becomeCascadeExplosion</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''becomeCascadeExplosion'''()<br />
This method causes the ship to explode as if it were hit by a quirium cascade.<br />
<br />
=== <code>broadcastCascadeImminent</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''broadcastCascadeImminent'''()<br />
This method causes the ship to broadcast a message to the AIs of all nearby ships warning them of an imminent cascade explosion. It is polite to call this a few seconds before calling <code>becomeCascadeExplosion</code><br />
<br />
=== <code>broadcastDistressMessage</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''broadcastDistressMessage'''()<br />
This method causes the ship to broadcast a distress message to the AIs of all nearby ships (received also by the player as a comms message). Ships receiving a distress message will often intervene in the fight, depending on their own AI and the roles of the ships already involved.<br />
<br />
=== <code>checkCourseToDestination</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''checkCourseToDestination'''()<br />
Checks the line between the ship's current position and its destination, and returns either null or an Entity (usually a planet, sun or other ship) that this ship would risk collision with if it travelled along that course.<br />
<br />
'''See also''': [[#getSafeCourseToDestination|getSafeCourseToDestination()]]<br />
<br />
=== <code>checkScanner</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''checkScanner'''([poweredOnly : Boolean]) : Array<br />
Runs a fast scanner check and returns the results. At most 32 objects within scanner range will be returned. If the <code>poweredOnly</code> parameter is present and set to true, then only powered objects will be returned (i.e. ships with a scan class other than CLASS_CARGO or CLASS_ROCK).<br />
<br />
This method is usually considerably quicker than [[Oolite_JavaScript_Reference:_System#filteredEntities|system.filteredEntities()]] and similar methods, with little loss of accuracy, though it is still advisable to cache the result for a while before re-scanning.<br />
<br />
=== <code>clearDefenseTargets</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''clearDefenseTargets'''()<br />
Clears the ship's list of point [[#defenseTargets|defense targets]].<br />
<br />
=== <code>commsMessage</code> ===<br />
function '''commsMessage'''(message : String [,target : Ship])<br />
Make the ship broadcast the specified message. Works on buoys and subentities as well as normal ships and stations. Messages are send to a maximum of 16 ships in range and always to the player when in range. When the optional target is used, the message goes only to that ship.<br />
<br />
=== <code>damageAssessment</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''damageAssessment'''() : Number<br />
Returns a number indicating the amount of damage or supply usage by this ship. Zero means that the ship is in excellent fighting condition, while higher numbers indicate increasing amounts of damage or supply shortages.<br />
<br />
=== <code>dealEnergyDamage</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''dealEnergyDamage'''(damage : Number, idealRange : Number [, velocityBias : Number])<br />
Deals damage to all ships within a sphere centred on this ship. If this ship has an owner (e.g. it is a missile or a subentity) the damage will be credited to its owner. Damage is dealt according to the following formula:<br />
* Further away than MAX_SCANNER_RANGE (25.6km): deal no damage<br />
* At or closer than <code>idealRange</code>: deal <code>damage</code> plus (or minus, for receding objects) <code>velocityBias</code> damage for every 0.001LM of relative closing speed, up to a maximum of 1.0LM<br />
* Between <code>idealRange</code> and a derived maximum range: calculate the damage that would have been done at <code>idealRange</code>, and then divide it by the square of the ratio of <code>idealRange</code> and the real range (i.e inverse-square). The derived maximum range is the distance where a target with no relative closing speed would take 1 point of damage.<br />
<br />
As an example, the standard Oolite missile uses <code>dealEnergyDamage(170, 32.5, 0.25)</code>, has a maximum speed of 0.75LM, and its AI tries to detonate it 25m from its target. Some worked examples (for comparision, one energy bank can absorb 64 points of damage, and a standard shield generator can absorb 128 points of damage):<br />
* The missile is fired at a stationary asteroid. It detonates at 25m, within the ideal range, and the relative closing speed is 0.75LM. The asteroid takes 170 + (0.25 * 750) = 357.5 points of damage<br />
* The missile is fired at a Cobra Mk III, which tries to flee from and evade the missile at its top speed of 0.35LM. The missile detonates at 25m, and the evasive manoeuvres mean that it is not heading directly at the Cobra when it detonates. The relative closing speed is 0.38LM. The Cobra takes 170 + (0.25 * 380) = 265 points of damage.<br />
* An Anaconda freighter travelling at 0.2LM fires a missile at a distant Fer-de-lance. After the missile has travelled 150m away from the Anaconda, it is hit by an ECM pulse from the FDL, and detonates. The relative velocity is -0.55LM (the missile is travelling away from the Anaconda), so the damage at the ideal range would be 170 - (0.25 * 550) = 32.5. The damage is then divided by (150 / 32.5)<sup>2</sup>, so the Anaconda takes about 1.5 points of damage.<br />
* A missile fired at something else detonates 500m away from a Sidewinder. The inverse-square rule divides the damage by (500 / 32.5)<sup>2</sup>, so the base damage at this range (ignoring velocityBias) is only 0.7. The Sidewinder is therefore safely outside the blast radius, and is not considered for damage. <br />
<br />
=== <code>deployEscorts</code> ===<br />
function '''deployEscorts'''()<br />
Cause a random number (at least 1 if possible) of the ship's escorts which are not already attacking a target to attack this ship's primary target, unless this function has already been called for the current target without meanwhile being called for a different target.<br />
<br />
=== <code>dockEscorts</code> ===<br />
function '''dockEscorts'''()<br />
Dock the ship’s deployed escorts, if any.<br />
<br />
=== <code>dumpCargo</code> ===<br />
function '''dumpCargo'''([amount : Number, commodity: String]) : Ship<br />
Ejects one item of cargo from the ship, and returns the cargo item. Returns <code>null</code> if the ship has no cargo, anything has been ejected in the last 0.5 seconds, or if sent to the player while docked.<br />
<br />
In 1.79 or later, multiple items may be scheduled for dumping by passing the number as a parameter.<br />
<br />
In 1.81 or later, a preferred commodity may be specified (if this is not present, a random item will be dumped as usual). This preference only applies to the first item dropped, not subsequent ones.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code><br />
<br />
=== <code>ejectItem</code> ===<br />
function '''ejectItem'''(role : String) : Ship<br />
Spawns a ship of role <code>role</code> immediately behind the ship, with a slight backwards velocity. (Note: an equal and opposite reaction is applied to the parent ship, so doing this with large ships is rarely useful. <code>player.ejectItem("station")</code> may seem funny, but don’t come running to me if you have someone’s eye out.) Returns the generated ship, or <code>null</code> if no ship is generated. The scanClass of the ejected item will always be CLASS_CARGO.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code><br />
<br />
=== <code>ejectSpecificItem</code> ===<br />
function '''ejectSpecificItem'''(itemKey : String) : Ship<br />
Spawns a ship with the ''shipdata.plist'' key <code>itemKey</code> immediately behind the ship, with a slight backwards velocity. The scanClass of the ejected item will always be CLASS_CARGO.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectItem|ejectItem]]</code><br />
<br />
=== <code>enterWormhole</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''enterWormhole'''([wormhole : Wormhole])<br />
If the player has entered witchspace, but before the old system is removed from memory, this method may be used to add this ship to the contents of the specified outbound wormhole. If no parameter is given, add them to the player's wormhole.<br />
<br />
If the player is not entering witchspace, this method does nothing: the ship must fly to the wormhole in the normal way to enter it.<br />
<br />
=== <code>equipmentStatus</code> ===<br />
function '''equipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]] [, multiple : Boolean]) : String or Object<br />
Tests whether the specified type of equipment is installed, and whether it is functioning. Returns one of the following strings: <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>, <code>"EQUIPMENT_UNAVAILABLE"</code> or <code>"EQUIPMENT_UNKNOWN"</code>.<br />
<br />
In 1.81 and later, if the optional <code>multiple</code> parameter is set to true, it will instead return an object in this format:<br />
{<br />
"EQUIPMENT_OK": 3.<br />
"EQUIPMENT_DAMAGED": 2<br />
}<br />
to allow equipments which allow fitting multiple to be queried. If multiple equipments can be fitted, not setting the 'multiple' parameter will return the 'best' state of all items of that type.<br />
<br />
'''See also:''' <code>[[#setEquipmentStatus|setEquipmentStatus()]]</code><br />
<br />
=== <code>exitAI</code> ===<br />
function '''exitAI'''()<br />
Exit the current AI, restoring the previous one. Equivalent to the <code>[[AI_methods|exitAI]]:</code> AI method. May not be used on player. Will generate a warning if there are no suspended AI states.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code><br />
<br />
=== <code>exitSystem</code> ===<br />
function '''exitSystem'''([targetSystem : Number]) : Boolean<br />
Cause the ship to jump out of the system, if possible. If <code>targetSystem</code> is specified, it will attempt to jump to the specified system, otherwise a random system within range is chosen.<br />
<br />
This method can fail for various reasons, in which case it returns <code>false</code>. It always fails for the player ship.<br />
<br />
=== <code>explode</code> ===<br />
function '''explode'''()<br />
Causes the ship to explode. Works on all ships, including the main station and the player except when docked.<br />
<br />
'''See also:''' <code>[[#remove|remove()]]</code><br />
<br />
=== <code>fireECM</code> ===<br />
function '''fireECM'''()<br />
activates an ecm burst, identical as the AI command.<br />
<br />
=== <code>findNearestStation</code> ===<br />
function '''findNearestStation'''()<br />
Returns the nearest Station entity to this ship. This is quicker than manually searching <code>system.stations</code> and much quicker than using <code>system.filteredEntities()</code>.<br />
<br />
=== <code>fireMissile</code> ===<br />
function '''fireMissile'''([missile]) : Ship<br />
fireMissile() will try to fire the first available missile and will return the missile fired, or <code>null</code> if no missiles can be fired at this time. It can take the optional missile identifier parameter, to allow for a specific missile to be fired. Missiles cannot be fired if the ship hasn’t got a valid target, or if the previous missile was launched less than <code>missile_load_time</code> seconds before. If a missile type was specified, and not found on the ship, no missile will be fired.<br />
<br />
=== <code>getSafeCourseToDestination</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''getSafeCourseToDestination'''()<br />
Returns some coordinates which can be flown to as an intermediate destination to allow travel between the ship's current position and its destination without colliding with any objects on the way. Use this if <code>checkCourseToDestination</code> returns an object you are unable or unwilling to destroy to calculate a new route.<br />
<br />
'''See also''': [[#checkCourseToDestination|checkCourseToDestination()]]<br />
<br />
=== <code>getMaterials</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''getMaterials'''() : Object<br />
getMaterials() returns the ship's current materials dictionary, or if none present an empty dictionary.<br />
<br />
'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code><br />
<br />
=== <code>getShaders</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''getShaders'''() : Object<br />
getShaders() returns the ship's current shaders dictionary, or if none present an empty dictionary.<br />
<br />
'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code><br />
<br />
=== <code>hasEquipmentProviding</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''hasEquipmentProviding'''(key : String)<br />
This method returns <code>true</code> if the ship has any equipment providing the <code>key</code> equipment type, and <code>false</code> otherwise.<br />
<br />
=== <code>hasRole</code> ===<br />
function '''hasRole'''(role : String)<br />
Returns <code>true</code> if the ship has <code>role</code> among its roles, <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#roles|roles]]</code><br />
<br />
=== <code>markTargetForFines</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''markTargetForFines()'''<br />
If this ship is eligible to give out fines and the primary target has a bounty, mark the current primary target for fines, which will need to be paid when the ship docks. If used on a ship other than the player, of course, the fines are not particularly meaningful.<br />
<br />
=== <code>notifyGroupOfWormhole</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''notifyGroupOfWormhole()'''<br />
Tells the ship's group about a wormhole (usually the one this ship has just entered). Causes a <code>wormholeSuggested</code> event to occur in the scripts of other group members.<br />
<br />
=== <code>offerToEscort</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''offerToEscort(mother : Ship)'''<br />
Offer to escort the specified ship. The ship making the offer must have the same scan class as the mothership and must have one of the designated escort roles. After the mothership has made a decision this ship will receive either an <code>escortAccepted</code> or <code>escortRejected</code> ship script event.<br />
<br />
=== <code>perform*</code> ===<br />
Each of these functions switches the frame-by-frame behaviour of the ship to a different mode. It may not necessarily remain in that mode, however - for example, those modes which require a target will usually fall back to idle mode if the target is lost.<br />
<br />
==== <code>performAttack</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performAttack()'''<br />
Attack the current target with available weapons.<br />
<br />
==== <code>performCollect</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performCollect()'''<br />
Attempt to scoop up the current target. If the current target is not scoopable, it will be lost.<br />
<br />
==== <code>performEscort</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performEscort()'''<br />
Escort the group leader. If this ship is not an escort of the group leader, it will not receive escort position updates from that ship.<br />
<br />
==== <code>performFaceDestination</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFaceDestination()'''<br />
Come to a stop, and turn to face the current destination coordinates.<br />
<br />
==== <code>performFlee</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFlee()'''<br />
Flee from the current target, using injectors if possible, until it is out of scanner range.<br />
<br />
==== <code>performFlyToRangeFromDestination</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFlyToRangeFromDestination()'''<br />
Fly to the current [[#destination|destination]] coordinates, stopping when the distance between the ship and those coordinates is the [[#desiredRange|desiredRange]]. If the ship is already closer to the destination coordinates than the desired range, it will move away from the coordinates.<br />
<br />
==== <code>performHold</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performHold()'''<br />
Come to a stop, and continually turn to face the current target<br />
<br />
==== <code>performIdle</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performIdle()'''<br />
Cancel any current turns to return to level flight, then move forward at current speed.<br />
<br />
==== <code>performIntercept</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performIntercept()'''<br />
Fly to intercept (i.e. ram) the current target.<br />
<br />
==== <code>performLandOnPlanet</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performLandOnPlanet()'''<br />
Land on rather than crash into the planet. This is a slow flight, so it is recommended to get close to the planet surface before activating this behaviour.<br />
<br />
==== <code>performMining</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performMining()'''<br />
Attack the current target with a mining laser. This does not count as hostile behaviour, so cannot be used except on rocks.<br />
<br />
==== <code>performScriptedAI</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performScriptedAI()'''<br />
Request flight instructions from a [[OXP_Scripted_AI|scripted AI]] callback each frame.<br />
<br />
==== <code>performScriptedAttackAI</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performScriptedAttackAI()'''<br />
Request flight instructions, including weapons fire, from a [[OXP_Scripted_AI|scripted AI]] callback each frame.<br />
<br />
==== <code>performStop</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performStop()'''<br />
Come to a complete halt<br />
<br />
==== <code>performTumble</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performTumble()'''<br />
Come to a complete halt and rotate randomly.<br />
<br />
=== <code>reactToAIMessage</code> ===<br />
function '''reactToAIMessage'''(message : String)<br />
Immediately perform the specified handler in the ship’s current AI state.<br />
<br />
'''See also:''' <code>[[#sendAIMessage|sendAIMessage()]]</code><br />
<br />
=== <code>recallDockingInstructions</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''recallDockingInstructions'''() : Object<br />
Returns the current docking instructions as an object, and sets the destination, desired range and desired speed to match the instructions. Use this if the ship may have been interrupted while docking to ensure its flight parameters are set correctly.<br />
<br />
'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#requestDockingInstructions|requestDockingInstructions]]</code><br />
<br />
=== <code>remove</code> ===<br />
function '''remove'''([suppressDeathEvent : Boolean])<br />
Immediately removes the ship from the universe. Works on all ships except the player, including the main station.<br>It generates a [[Oolite JavaScript Reference: ship script event handlers#shipRemoved|this.shipRemoved(suppressDeathEvent)]] event. By default it will also trigger a [[Oolite JavaScript Reference: ship script event handlers#shipDied|this.shipDied()]] event, unless <code>suppressDeathEvent</code> is true.<br />
<br />
'''See also:''' <code>[[#explode|explode()]]</code><br />
<br />
=== <code>removeCollisionException</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''removeCollisionException'''(exception : Ship)<br />
Allow this ship and the selected ship to collide again. See [[#collisionExceptions|collisionExceptions]] and [[#addCollisionException|addCollisionException]].<br />
<br />
Removing a collision exception which does not exist has no effect but will not cause an error.<br />
<br />
=== <code>removeDefenseTarget</code>===<br />
{{oolite-method-added|1.79}}<br />
function '''removeDefenseTarget'''(target : Ship)<br />
Ensures that the target ship is not on this ship's list of point [[#defenseTargets|defense targets]].<br />
<br />
=== <code>removeEquipment</code> ===<br />
function '''removeEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]])<br />
Removes the given piece of equipment from the ship.<br />
This function can also be used to remove missiles (and mines). If more than one missile of the same type is found on board, only one of them will be removed.<br />
<br />
Note that in Oolite prior to 1.76.1 there was a bug which could sometimes cause the game to crash if this function was used on pylon-mounted equipment. Therefore, if you do this in your OXP, you should set (at least) 1.76.1 as the version in requires.plist<br />
<br />
Example:<br />
ship.removeEquipment("EQ_ECM");<br />
<br />
=== <code>requestDockingInstructions</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''requestDockingInstructions'''() : Object<br />
Requests the next docking instructions from the station, and returns them as an object, setting the destination, desired range and desired speed to match the instructions. Use this to get the next step in the docking sequence after completing the previous one.<br />
<br />
'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code><br />
<br />
<br />
=== <code>requestHelpFromGroup</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''requestHelpFromGroup'''()<br />
This function sends the <code>helpRequestReceived</code> event to the other ships in this ship's group and escort group, sending the name of this ship's current target as the aggressor.<br />
<br />
=== <code>restoreSubEntities</code> ===<br />
function '''restoreSubEntities'''() : Boolean<br />
Recreate all destroyed or removed subentities of the ship. Returns <code>true</code> if any subentities were added. Whether or not any subentities were added, this will also reset all subentities to their original configuration of position, orientation and other properties.<br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#isFrangible|isFrangible]]</code><br />
<br />
=== <code>selectNewMissile</code> ===<br />
function '''selectNewMissile'''() : equipmentKey<br />
selectNewMissile() will automatically select a missile for a specific ship. It uses the missile_role shipdata.plist key to find out which missiles to select. As with the system populator, there's a small chance that missiles other than the missile_role specified in shipdata will be selected.<br />
e.g.<br />
this.ship.awardEquipment(this.ship.selectNewMissile())<br />
will automatically add the 'right type' of missile to a ship, i.e. one that its captain would normally choose.<br />
<br />
=== <code>sendAIMessage</code> ===<br />
function '''sendAIMessage'''(message : String)<br />
Add a message to the ship’s AI deferred message queue. Messages in the queue are handled immediately after the next periodic <code>UPDATE</code> message. Identical messages are coalesced.<br />
<br />
'''See also:''' <code>[[#reactToAIMessage|reactToAIMessage()]]</code><br />
<br />
=== <code>setAI</code> ===<br />
function '''setAI'''(AIName : String)<br />
Set the current AI, leaving the old one suspended. Equivalent to the <code>[[AI_methods|setAITo]]:</code> AI method. May not be used on player. From 1.79 onwards AI files may either be plist-based (with a .plist extension) or Javascript-based (with a .js extension).<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code><br />
<br />
=== <code>setBounty</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''setBounty'''(bounty : Number, reason : String)<br />
Sets the ship's bounty to the new value. <code>reason</code> will be sent to [[Oolite_JavaScript_Reference:_ship_script_event_handlers#shipBountyChanged|shipBountyChanged()]].<br />
<br />
'''See also:''' <code>[[#bounty|bounty]]</code><br />
<br />
=== <code>setCargo</code> ===<br />
function '''setCargo'''(commodity : String [, count : Number]) : Boolean<br />
Attempts to create <code>count</code> weight units of the commodity <code>commodity</code> for a cargo barrel. (Can not be used to set cargo for ships) When more units are defined than 1 ton, the count is reduced to one ton. It returns false when the selected commodity is unknown. If <code>count</code> is not specified, one will be assumed.<br />
<br />
=== <code>setCargoType</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setCargoType'''(commodityType : String) : Boolean<br />
Attempts to set the ship's cargo hold to contain cargo of the specified type, discarding any cargo already present. This should generally only be used immediately after a ship is spawned. Valid cargo types are:<br />
* '''SCARCE_GOODS''': goods which are likely to be rare in the current system, usually legal.<br />
* '''PLENTIFUL_GOODS''': goods which are likely to be plentiful in the current system, usually legal.<br />
* '''MEDICAL_GOODS''': narcotics (used for the Moray Medical Boat)<br />
* '''ILLEGAL_GOODS''': various goods likely to be rare in the current system, with a strong bias towards contraband<br />
* '''PIRATE_GOODS''': as ILLEGAL_GOODS, but the total amount carried will be lower<br />
This will return false if an unrecognised commodity type is used, and will throw an exception if used on a cargo pod rather than a cargo carrier. Using it on a ship like an Asp without a cargo hold is valid but pointless.<br />
<br />
=== <code>setCrew</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setCrew'''(Object) : Boolean<br />
Sets the ship's crew to one represented by the given object (or sets the ship to uncrewed if null is given as a parameter). Returns true if this succeeds, false otherwise (if the ship is ''always'' unpiloted). The object has the same keys as [[characters.plist]], all of which are optional and will be replaced with default values if unset. They are applied in the following order:<br />
* origin system<br />
* random seed<br />
* role<br />
* the rest<br />
You can therefore set a random seed or role to get particular behaviour, and use the other keys to override it.<br />
<br />
At the moment this function only sets the first crew member (the pilot of the ship)<br />
<br />
=== <code>setEquipmentStatus</code> ===<br />
function '''setEquipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]], statusKey : String)<br />
Changes the status of the given piece of equipment from the ship. The two only valid status keys are <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>.<br />
<br />
'''Note:''' by design, this method will throw an exception if called with an equipment type that does not exist. To test whether an equipment type exists, use <code>[[Oolite JavaScript Reference: EquipmentInfo#infoForKey|EquipmentInfo.infoForKey()]]</code>, which will return <code>null</code> for undefined equipment.<br />
<br />
'''See also:''' <code>[[#equipmentStatus|equipmentStatus()]]</code><br />
<br />
=== <code>setMaterials</code> ===<br />
function '''setMaterials'''(materialDictionary : Object [, shaderDictionary : Object]) : Boolean<br />
Set the materials of the ship’s model. This works exactly like the <code>materials</code> dictionary in [[shipdata.plist]]. The optional <code>shaderDictionary</code> argument overrides <code>materialDictionary</code> if shaders are active.<br />
<br />
'''Example:'''<br />
this.ship.setMaterials({"my_ship_diffuse.png": { diffuse_map: "my_ship_damaged_diffuse.png" }});<br />
<br />
'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code><br />
<br />
=== <code>setScript</code> ===<br />
function '''setScript'''(scriptName : String)<br />
Set, or completely replace, the javascript code associated to a ship entity.<br />
<br />
=== <code>setShaders</code> ===<br />
function '''setShaders'''(shaderDictionary : Object) : Boolean<br />
Set the shader materials of the ship’s model. Equivalent to <code>[[#setMaterials|setMaterials()]]</code> with the <code>materialDictionary</code> value set to the ship’s current material dictionary.<br />
<br />
'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code><br />
<br />
=== <code>spawn</code> ===<br />
function '''spawn'''(role : String [, count : Number]) : Array<br />
Attempts to create <code>count</code> (maximum: 64) ships of role <code>role</code> close to the ship – specifically, inside the ship’s collision radius. (Since creating ships may fail, the number created may be less than <code>count</code>). The created ships are returned in an array. If <code>count</code> is not specified, one will be assumed.<br />
<br />
<code>spawn()</code> is intended for cases when a ship splits into multiple parts or drops parts. In particular, it has the following special behaviour:<br />
* The spawned ships inherit most of the temperature of the parent.<br />
* If the parent is a missile and a child has the <code>[[shipdata.plist#is_submunition|is_submunition]]</code> property, the child will be considered a missile, its target will be set to that of the parent and the child’s owner will be set to the parent.<br />
* <code>spawn()</code> does not set up escorts for the new ships, or generate witchspace effects, or do any special AI handling.<br />
<br />
=== <code>spawnOne</code> ===<br />
function '''spawnOne'''(role : String) : Ship<br />
Convenience method which calls <code>[[#spawn|spawn]](role)</code> and returns the first element of the resulting array, or <code>null</code> if <code>spawn()</code> fails.<br />
<br />
=== <code>switchAI</code> ===<br />
function '''switchAI'''(AIName : String)<br />
Set the current AI, exiting the old one. Equivalent to the <code>[[AI_methods|switchAITo]]:</code> AI method. May not be used on player.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#exitAI|exitAI()]]</code><br />
<br />
=== <code>threatAssessment</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''threatAssessment'''(full : Boolean) : Number<br />
Returns a number indicating the relative strength of the ship. If the 'full' parameter is true, additional information will be considered as part of the assessment which would generally only be known by ships which know this ship or have seen it in combat. Otherwise, only data which could reasonably be expected to be common knowledge based on the class of the ship will be included.<br />
<br />
For example, which weapon facings are available is part of the basic assessment, but what forward laser the ship has is part of the full assessment.<br />
<br />
=== <code>throwSpark</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''throwSpark'''()<br />
Sets the ship to throw a spark as if it was seriously damaged. If this ship is already scheduled to throw a spark, this does nothing.<br />
<br />
=== <code>updateEscortFormation</code> ===<br />
function '''updateEscortFormation'''()<br />
Request that the game updates the target positions for the ship’s escorts by calling the ship’s script’s <code>coordinatesForEscortPosition()</code> method.<br />
<br />
== Static Methods ==<br />
=== <code>keys</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''keys'''() : Array<br />
Returns all dataKeys of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.<br />
var dataKeysArray = Ship.keys();<br />
<br />
=== <code>keysForRole</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''keysForRole'''(role : String) : Array<br />
Returns all dataKeys of ships defined in all [[shipdata.plist]] which contains the given role.<br />
<br />
var role = "trader";<br />
var roleKeys = Ship.keysForRole( role );<br />
log("keysForRole", role + ": " + roleKeys );<br />
<br />
=== <code>roleIsInCategory</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''roles'''(role : String, category : String) : Boolean<br />
Returns whether the role given is in a particular category as defined in [[role-categories.plist]]<br />
<br />
Ship.roleIsInCategory("trader","oolite-pirate-victims"); // true<br />
<br />
=== <code>roles</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''roles'''() : Array<br />
Returns all roles of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.<br />
<br />
var roles = Ship.roles();<br />
for( var i = 0; i < roles.length; i++ ) {<br />
var roleKeys = Ship.keysForRole( roles[i] );<br />
log("roles", i + ". "+roles[i] + ": " + roleKeys );<br />
}<br />
<br />
=== <code>shipDataForKey</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''shipDataForKey'''(datakey : String) : Object<br />
Returns an object containing a representation of the raw [[shipdata.plist]] entry for a given data key, or null if the data key does not exist. Keys not defined in the shipdata.plist entry will not be defined in the object - they won't get their default values.<br />
<br />
Using the ship object properties is generally a better way to get this information, but this is useful if you want to find out what a ship might be like if you did add it.<br />
<br />
var shipdata = Ship.shipDataForKey("cobra3-trader");<br />
log("test",shipdata["name"]); // "Cobra Mark III"<br />
log("test",shipdata["ship_class_name"]); // undefined<br />
log("test",shipdata["ship_unique_name"]); // undefined<br />
log("test",shipdata["display_name"]); // undefined<br />
<br />
==See also==<br />
*[[Shipdata.plist]]<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_Docking_Clearance_Protocol_(v1.72_or_later)&diff=48191Oolite Docking Clearance Protocol (v1.72 or later)2015-07-08T11:20:18Z<p>Cim: /* Overview */</p>
<hr />
<div>== Overview ==<br />
Starting from [[Oolite]] version 1.72, the GalCop Docking Clearance Protocol has been introduced. It is disabled by default in versions up to 1.80, and enabled by default from 1.81 onwards. From 1.77 it is configurable through the Game Options menu.<br />
<br />
If enabled, the commander will have to request authorization from the space station, before they attempt to dock. If there are vessels in the launching queue or in their final docking approach, the station will respond by asking the player to hold for a few moments while vessels which have priority complete their departure sequences or docking runs. Once this has been done, the station will notify the commander that they are clear to approach and give them a two minute window to complete the docking manouevre. The station will notify the commander 20 seconds before the window closes that their time is running out, at which point the commander can request an extension of the slot. At any point in time, the pilot can cancel out the request to dock and will have to leave the docking corridor to other ships on approach. It must also be noted that the ship's docking computer will always request docking permission as part of its automated approach procedure, so a manual clearance request is not necessary when using it.<br />
<br />
If a commander docks without requesting clearance or after their docking slot has expired, the GalCop Station Traffic Control Authority will impose a penalty equal to 5% of the commander's credit balance up to a maximum of 5000.0 Cr for unauthorized docking. No fees will be imposed if the commander has docked in accordance with the protocol. No change in legal record will occur as a result of docking without permission, however, fugitive pilots will not be granted clearance to dock on a GalCop station and they will be subjected to penalties whenever they dock.<br />
<br />
In the case of major emergencies, the protocol states that no authorizations to dock be required.<br />
<br />
== Enabling the Docking Clearance Protocol ==<br />
To enable the feature, you will need to edit the ''universal'' section of '''[[planetinfo.plist]]'''. You will have to change the entry that reads<br />
<pre>universal =<br />
{ <br />
// Default docking clearance requirement for main stations.<br />
stations_require_docking_clearance = no;<br />
};</pre><br />
to<br />
<pre>universal =<br />
{ <br />
// Default docking clearance requirement for main stations.<br />
stations_require_docking_clearance = yes;<br />
};</pre><br />
You can also set each station's docking clearance requirements individually by editing their corresponding '''shipdata.plist''' entry and adding the key<br />
<pre>requires_docking_clearance = yes/no;</pre><br />
The local ''requires_docking_clearance'' key has priority over the global ''stations_require_docking_clearance'' one. By combining these two keys you can adjust which stations you want to require clearance and which not to. It is noted that by default, the ''stations_require_docking_clearance'' key is set to '''no'''. This way, the default game behaviour remains unchanged with respect to what it was before the introduction of the DCP. Additionally, the rock hermit's ''requires_docking_clearance'' key is set to '''no''' by default. It is up to the player to enable this feature, if they want to experience the new gameplay elements.<br />
<br />
Instead of doing the changes yourself you can also download a small oxp that sets the universal docking clearance to true.<br>Download: [https://www.box.com/s/gyxdwj43yzjq9kzfa502 Docking Clearance]<br><br />
Starting with Oolite 1.77 the global clearance is set inside Oolite with the user settings and there is no longer any need to use this oxp or set the universal value manually.<br />
<br />
== Instructions ==<br />
To request docking clearance, the commander must first target the station they request clearance from.<br />
* [[Image:DC1.png]]<br />
<br />
Once the station has been targeted, the commander must contact GalCop Station Traffic Control and request clearance. This is done by pressing "'''L'''" (shift-l). Traffic Control will respond according to the status of traffic at the station at the time of the request. In this example, there are ships in the launching queue and the player will have to wait for a few moments. Note that in most cases, the station will inform the player how long they have to wait by giving them their number in the waiting queue.<br />
* [[Image:DC2.png]]<br />
<br />
As soon as the commander's turn is up, Traffic Control will inform accordingly and notify the commander that they have a two-minute window within which they will need to complete their docking approach.<br />
* [[Image:DC3.png]]<br />
<br />
If the commander is close to missing their approach window, the station will notify them so that they can take action as needed.<br />
* [[Image:DC4.png]]<br />
<br />
The commander can press "'''L'''" (shift-l) after the station has notified them in order to extend their docking clearance window. The station approves.<br />
* [[Image:DC5.png]]<br />
<br />
The commander can cancel the request to dock by pressing "'''L'''" at any time after their original request has been approved (unless they are timing out, in which case "'''L'''" (shift-l) will renew their permission).<br />
* [[Image:DC6.png]]<br />
<br />
This commander has failed to observe the Docking Clearance Protocol and has entered the station without requesting clearance. He is therefore subjected to a 5% on current balance penalty.<br />
* [[Image:DC7.png]]<br />
<br />
{{mechanics-OXP}}</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_SystemInfo&diff=48173Oolite JavaScript Reference: SystemInfo2015-07-04T19:36:50Z<p>Cim: 1.82 change</p>
<hr />
<div><small>'''Prototype:''' <code>Object</code></small><br /><br />
<br />
'''<code>SystemInfo</code>''' objects provide information about a specific system. <code>SystemInfo</code>s can be retrieved for any system in any galaxy as of version 1.82. In previous versions, only systems for the current galaxy could be read.<br />
<br />
In interstellar space, <code>system.info</code> refers to a temporary <code>SystemInfo</code> object whose properties cannot be written to. Attempting to read properties of such a temporary <code>SystemInfo</code> after leaving interstellar space will raise an exception.<br />
<br />
== Properties ==<br />
=== <code>coordinates</code> ===<br />
'''coordinates''' : {{oojsclass|Vector3D}} (read-only)<br />
The coordinates of the system in light years. e.g. for Lave: <code>(8, 34.6, 0)</code>. The z component is always zero.<br />
<br />
The upper left corner has the coordinate <code>(0, 0, 0)</code>. Going right increases the x value while going down on the map increases the y value.<br />
<br />
'''Example:'''<br />
System.infoForSystem(galaxyNumber, 7).coordinates<br />
returns the coordinates of the system with an ID number of 7 in the current galaxy. In the first galaxy that would be the coordinates for Lave: <code>(8, 34.6, 0)</code>.<br />
<br />
=== <code>galaxyID</code> ===<br />
'''galaxyID''' : Number (read-only nonnegative integer)<br />
The ID number of the galaxy.<br />
<br />
=== <code>internalCoordinates</code> ===<br />
'''internalCoordinates''' : {{oojsclass|Vector3D}} (read-only)<br />
'''Discouraged in favour of <code>[[#coordinates|coordinates]]</code>.'''<br /><br />
The coordinate of the system in the internal coordinate system.<br />
<br />
=== <code>systemID</code> ===<br />
'''systemID''' : Number (read-only nonnegative integer)<br />
The ID number of the system.<br />
<br />
== More properties ==<br />
In addition to the properties above, you can access many other system properties, using the same keys as [[planetinfo.plist]].<br />
<br />
'''Example:'''<br />
<code>system.info.description = "This is a dull planet."</code><br />
sets the description of the current planet to “This is a dull planet.”<br />
<br />
Modified properties are permanent and are stored in saved game. Changes made by scripts override those in ''[[planetinfo.plist]]''. Set a property to <code>null</code> to restore the ''[[planetinfo.plist]]'' value, or the default.<br />
<br />
== Methods ==<br />
=== <code>distanceToSystem</code> ===<br />
function '''distanceToSystem'''(system : SystemInfo) : Number<br />
Returns the distance in light years to another <code>SystemInfo</code>.<br />
<br />
'''Example:'''<br />
System.infoForSystem(galaxyNumber, 7).distanceToSystem(System.infoForSystem(galaxyNumber, 8))<br />
If galaxyNumber is 0, this returns 92.8.<br />
<br />
=== <code>routeToSystem</code> ===<br />
function '''routeToSystem'''(system : SystemInfo [, "OPTIMIZED_BY_JUMPS" | "OPTIMIZED_BY_TIME"] ) : Object<br />
Returns a dictionary containing the route information to another <code>SystemInfo</code>. The dictionary contains the array of system IDs that belong to the <code>route</code> found, the <code>distance</code> and the <code>time</code> corresponding to said route. Takes the optional parameter <code>"OPTIMIZED_BY_JUMPS"</code> (default) or <code>"OPTIMIZED_BY_TIME"</code> to calculate least number of jumps or fastest transit time routes respectively.<br />
<br />
'''Example:'''<br />
var myRoute = System.infoForSystem(galaxyNumber, 7).routeToSystem(System.infoForSystem(galaxyNumber, 8))<br />
myRoute.route<br />
myRoute.distance<br />
myRoute.time<br />
returns:<br />
7,129,227,73,89,222,29,42,131,62,150,36,28,16,185,86,138,51,8 (the route)<br />
96.40 (distance of added jumps)<br />
530.40 (travelled time)<br />
<br />
Warning: in version 1.76 or earlier there is a bug in this method which may cause a crash if either the start or end of the route is in interstellar space (i.e. system ID -1). In later versions this simply returns null.<br />
<br />
=== <code>samplePrice</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''samplePrice'''(commodity : String) : Array<br />
Return a sample main market price in decicredits for the commodity with that key in this system. As this requires reading system information, it will only work for systems in the current galaxy. There is of course no guarantee that the price returned by this function will be anywhere near the actual price when the system is next entered.<br />
<br />
=== <code>setProperty</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''setProperty'''(key : String, value: String, layer: Number [, manifest: String])<br />
<br />
This lets you set properties with more control than provided by writing directly to <code>systemInfo.property</code>. <code>layer</code> is the layer from 0 to 3 that the change should be applied at, as in [[planetinfo.plist]]. Layer 2 is the default layer for Javascript-initiated changes, but 3 may be used for changes absolutely crucial for OXP functionality.<br />
<br />
It is also possible to make changes on behalf of a different OXP by passing the manifest ID of that OXP as the fourth parameter. Otherwise the OXP responsible for the current script execution context will be used.<br />
<br />
=== <code>systemsInRange</code> ===<br />
function '''systemsInRange'''([range : Number]) : Array<br />
Returns an array of <code>SystemInfo</code>s in range (default: 7) from the given system.<br />
<br />
'''Note:''' will not produce correct results if used in interstellar space.<br />
<br />
'''Example:'''<br />
system.info.systemsInRange(5);<br />
<br />
== Static methods ==<br />
=== <code>filteredSystems</code> ===<br />
function '''filteredSystems'''(this : Object, predicate : Function) : Array of SystemInfo<br />
A list of the <code>SystemInfo</code>s for which <code>predicate</code> returns <code>true</code>.<br />
<br />
'''Example:'''<br />
// This is the actual implementation of <code>[[#systemsInRange|systemsInRange()]]</code>.<br />
SystemInfo.prototype.systemsInRange = function systemsInRange(range) <br />
{ <br />
if (range === undefined) <br />
{ <br />
range = 7; <br />
} <br />
<br />
return SystemInfo.filteredSystems(this, function(other) <br />
{ <br />
return (other.systemID !== this.systemID) && (this.distanceToSystem(other) <= range); <br />
}); <br />
}<br />
<br />
=== <code>setInterstellarProperty</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''setInterstellarProperty'''(galaxy : Number, fromsystem : Number, tosystem : Number, layer: Number, key : String, value: String, [, manifest: String])<br />
<br />
This is similar to [[#setProperty|setProperty]] but for setting properties of interstellar space regions. Changes made to the current interstellar space region will only take effect if the player leaves and returns. <br />
<br />
Note that the order of fromsystem (the last real system visited) and tosystem (the target of the latest jump) is significant - 0,7,55 is Lave to Leesti; 0,55,7 is Leesti to Lave. In many cases setting the same change for both directions may be necessary.<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=OXP_standards&diff=48172OXP standards2015-07-04T15:57:34Z<p>Cim: /* Version 1.82 */</p>
<hr />
<div>==Purpose==<br />
<br />
The purpose of this document is to outline ways in which OXPs should be written and packaged to best make use of modern features and to avoid obsolete features, as the "best" way to implement many OXP features has changed since the 1.65 release. While the intent is that almost all obsolete features for OXP development will continue to exist in future 1.xx releases of Oolite, they will not receive further development and may have other disadvantages such as inefficiency, lack of features, or a tendency to encourage incompatibility between OXPs.<br />
<br />
New OXPs should be written to the latest published standards version, or to the anticipated standards version if they are written using unreleased features from the next Oolite version. Existing OXPs should be brought closer to the latest published standards as maintainer time permits.<br />
<br />
The standards document will be updated with each Oolite release. Anticipated standards for future releases will also be documented when known.<br />
<br />
==Keywords==<br />
<br />
* '''discouraged''': while the OXP features for this way of doing things are not themselves obsolete, using them is this manner is not recommended as a better alternative exists.<br />
* '''obsolete''': this feature is considered obsolete. No further developments will be made to it, existing bugs might not be fixed, depending on severity, and testing that it continues to work as expected will be limited. OXP authors should avoid this feature in new code, and try to replace it in existing OXPs.<br />
* '''recommended''': this way of doing things is strongly recommended for all OXPs, especially new ones, and may replace a previously recommended method in a previous version.<br />
<br />
==Standards==<br />
<br />
The initial standards version is 1.77.1. A few general points which do not depend on Oolite version are mentioned first.<br />
<br />
===General===<br />
<br />
====Versioning====<br />
Every public release of the OXP is '''recommended''' to have a unique version number, such that the later versions have higher numbers than earlier versions. Even the smallest update to the OXP should give a new version number, to avoid confusion about exactly which code is being run. The version number is '''recommended''' to be placed in:<br />
<br />
* the name of the .oxp folder<br />
* the documentation files<br />
<br />
====Licensing====<br />
It is '''recommended''' that the documentation of the OXP includes a statement of licensing to make clear if other people may redistribute the OXP or release modifications to it. If no license is included or stated elsewhere, this is legally equivalent to a ban on redistributing or modifying the OXP, and even were this not the case the community prefers to respect authors wishes for how their OXP is used, erring on the side of caution. The "Creative Commons" licenses are often used by authors wanting a relatively permissive and generally understood license.<br />
<br />
====Prefixing to avoid conflicts====<br />
All entries in the OXP are '''recommended''' to be prefixed with a string intended to be unique to the OXP, unless the entry is intended to override a core entry or one provided by another OXP. Entries in this context includes:<br />
<br />
* filenames of files in the <code>AIs</code>, <code>Images</code>, <code>Models</code>, <code>Music</code>, <code>Scripts</code>, <code>Shaders</code>, <code>Sounds</code> and <code>Textures</code> folders.<br />
* the <code>this.name</code> value of any script file.<br />
* the name of any key in <code>descriptions.plist</code>, <code>missiontext.plist</code>, <code>shipdata.plist</code> or <code>shipyard.plist</code><br />
* the equipment key (e.g. "<code>EQ_MYOXP_SCANNER</code>") in <code>equipment.plist</code><br />
* various script-accessible global properties such as mission variables, marker names, <code>script_info</code> keys, and so on.<br />
<br />
====Javascript====<br />
The use of strict mode, activated by placing <code>"use strict";</code> at the top of the file, is '''recommended''' for all JS files to avoid bugs.<br />
<br />
All properties and methods of the <code>this</code> object within Javascript files are '''recommended''' to have a name beginning with the _ or $ character unless they are intended to be an event handler (e.g. <code>this.shipWillEnterWitchspace</code>) or are a standard property such as <code>this.name</code>. This will ensure that future versions of Oolite do not provide an event handler with the name of a non-handler property.<br />
<br />
====requires.plist====<br />
The version entry of the <code>requires.plist</code> file, unless the OXP specifically requires a bug fix present in a minor release of Oolite is '''recommended''' to refer to a major release - 1.76, 1.77, etc. to avoid unnecessarily preventing use of the OXP.<br />
<br />
===Version 1.77.1===<br />
<br />
====OXP packaging====<br />
There are two common methods of packaging OXPs currently in use: in the first, a ZIP file contains the .oxp folder and other loose files, and in the second, the ZIP file contains a folder, containing the .oxp folder and other loose files. These methods are recommended. All packaging arrangements other than those two are '''discouraged''', including the use of compression algorithims other than ZIP. OXPers if possible should try to ensure that OS-specific files and folders (<code>Thumbs.db</code>, <code>__MACOSX</code>, etc.) are not included. It is '''recommended''' that the ZIP file has a name including both the OXP's name and the version number.<br />
<br />
It is '''recommended''' that important documentation for the OXP be placed both within the .oxp folder and in the loose files next to it when packaging the OXP, for best compatibility with the range of operating systems Oolite runs on.<br />
<br />
====Versioning====<br />
Worldscripts - and other Javascript files if practical - are '''recommended''' to have a <code>this.version</code> property with the OXP version as its value, to aid debugging using <code>Latest.log</code>.<br />
<br />
====Legacy scripting and other obsolete keys====<br />
The old "legacy scripting" methods are all considered '''obsolete'''. This includes:<br />
<br />
* any use of the <code>script.plist</code> file or worldscripts with a .plist extension<br />
* any use of the <code>script_actions</code> key in any plist<br />
* the use of the conditions key in <code>equipment.plist</code><br />
* the use of the <code>conditions</code>, <code>death_actions</code>, <code>launch_actions</code>, <code>setup_actions</code> or <code>spawn</code> keys in <code>shipdata.plist</code><br />
* the use of a conditions array as the value of <code>has_shipyard</code> in <code>shipdata.plist</code>.<br />
<br />
This functionality is all possible to replicate in Javascript.<br />
<br />
The following <code>shipdata.plist</code> keys are considered '''obsolete'''.<br />
<br />
* <code>port_dimensions</code><br />
* <code>port_radius</code><br />
* old-style subentity definitions<br />
<br />
All Javascript properties and methods beginning with the word legacy are considered '''obsolete'''.<br />
<br />
====Scripting equipment availability====<br />
The TL:99 hack for making equipment temporarily unavailable is '''obsolete'''. A condition script is now the '''recommended''' approach.<br />
<br />
====No in-flight mission screens====<br />
The use of mission screens in flight is considered '''obsolete''' due to a number of bugs.<br />
<br />
====Random name string expansion====<br />
The use of the %R description expansion for purposes other than generating planet descriptions is '''discouraged'''. %N is '''recommended''' instead as it has better randomness.<br />
<br />
====Accessing custom interfaces====<br />
The use of GUI screen switching combinations to access functionality is '''discouraged'''. Instead, when docked at a station, the interfaces screen is '''recommended''' for player-initiated access to functionality. In flight, primable equipment is '''recommended''' for the same purpose.<br />
<br />
====No zero-polygon models====<br />
The use of zero-polygon models (including those with non-zero vertices and lines) is considered '''obsolete'''. Visual Effects are '''recommended''' if a non-colliding entity is required.<br />
<br />
====Planet textures====<br />
The use of lat-long maps for planet textures is '''discouraged'''. Cube maps are '''recommended'''.<br />
<br />
====Mission map markers====<br />
The use of the new object syntax for <code>mission.markSystem</code> is '''recommended''' to avoid conflicts. The numeric syntax is considered '''obsolete'''.<br />
<br />
====Weapon facings specification====<br />
The <code>weapon_facings</code> key in <code>shipdata.plist</code> is '''recommended''' for all NPC ships.<br />
<br />
====Missile explosions====<br />
The AI command <code>dealEnergyDamageWithinDesiredRange</code> is '''obsolete''' as it has bugs especially apparent at low frame rates. The JS method <code>dealEnergyDamage</code> is '''recommended'''.<br />
<br />
====Shaders====<br />
The <code>OO_TANGENT_ATTR</code> preprocessor definition should never be used in shaders (using it is '''incorrect''', not merely '''discouraged''').<br />
<br />
===Version 1.80 ===<br />
<br />
====OXP Packaging====<br />
It is '''recommended''' that the compressed OXZ format be used for distribution of expansion packs. A ZIP file containing an OXP folder as in the previous standards may also be provided. If practical, the OXZ file should be placed at a location where direct HTTP download is possible, as this allows it to be added to Oolite's OXZ index for automatic download and installation. Dependencies and conflicts between OXZs should be specified in the <code>manifest.plist</code> file. While it is not required, it is '''recommended''' that expansion packs distributed in OXP folder format also include a <code>manifest.plist</code> file.<br />
<br />
====Versioning====<br />
The <code>manifest.plist</code> file now contains the version number, and the <code>this.version</code> property of Javascript files will be automatically set from this. The recommendation in the 1.77.1 standards to include an explicit <code>this.version</code> property now no longer applies.<br />
<br />
====HUD Capabilities====<br />
All HUDs are '''recommended''' to include the new HUD selectors <code>drawWaypoints:</code>, <code>drawPrimedEquipment:</code> and <code>drawASCTarget:</code> as soon as possible. All HUDs are '''recommended''' to include at least one multi-function display.<br />
<br />
The use of multi-function displays (usually together with primable equipment) is '''recommended''' for displaying persistent in-flight information to the player. Previous methods involving repeated printing of console messages are strongly '''discouraged'''.<br />
<br />
====AI language====<br />
The use of plist-based AIs for non-trivial AIs is '''discouraged'''. Javascript AIs are '''recommended'''. Use of the Priority AI library to write AIs, especially the standard conditions and behaviours it provides, is useful to make ships fit in with the core ships and to have future improvements to AI incorporated easily. Alternative AI controller libraries released as OXPs may also be used.<br />
<br />
====Ship roles====<br />
The roles used in ship OXPs should consider the documented advice especially for the roles with light, medium and heavy variants, to ensure that appropriately powerful ships are added at each level. The use of the '<code>escort</code>', '<code>hunter</code>' and '<code>pirate</code>' roles will generally require adjustment.<br />
<br />
For ships intended to fit in to standard Oolite roles, the use of the <code>auto_weapons</code> key is '''recommended'''. <br />
<br />
The use of <code>pirate_victim_roles.plist</code> to specify ships as "trader-like" is '''obsolete'''. <code>role_categories.plist</code> provides the same functionality in a more flexible way and is '''recommended'''.<br />
<br />
====System population====<br />
The use of any method other than the system populator functions to add entities to a system is '''discouraged''' (for example, calling <code>system.addShips</code> during the witchspace exit world event handlers). Repopulation of the system is '''recommended''' to use the system repopulator functions, though other event handlers may still be used when appropriate. It is '''recommended''' that the <code>deterministic</code> flag is used for stations intended to be (semi-)permanent to allow the player to save the game at those places.<br />
<br />
====Shipset OXP structure====<br />
Shipset OXPs are '''recommended''' to use <code>like_ships</code> of the template entries, entering only those keys which have changed from the core details. The specification of the role key by shipset OXPs is '''discouraged'''.<br />
<br />
====Station allegiance specification====<br />
OXPs adding stations are '''recommended''' to set the new <code>allegiance</code> property to assist the AI. If this is not set a value will be calculated algorithmically.<br />
<br />
====Sound file format====<br />
Sound files are '''recommended''' to be encoded as single-channel (mono) audio at 44KHz, as this allows the positional sound features to be used most effectively. Music and potentially other non-positional sounds might remain as stereo files. Sound packs should consistently use either mono or stereo encodings, not a mixture of both.<br />
<br />
====Shaders====<br />
The use of the <code>OO_REDUCED_COMPLEXITY</code> macro in shaders is '''obsolete''' as the Reduced Detail setting is now only applied in non-shader modes.<br />
<br />
=== Version 1.82 ===<br />
<br />
====Manifests====<br />
<br />
The manifest description can now contain multiple lines, with the second and subsequent lines being visible by pressing 'i' within the manager. It is '''recommended''' that manifests be updated to add extra information here.<br />
<br />
====HUD Capabilities====<br />
<br />
All HUDs are '''recommended''' to use <code>drawSurround:</code> with a <code>color</code> attribute, rather than the hard-coded colours of <code>drawYellowSurround:</code> and <code>drawGreenSurround:</code><br />
<br />
====Market settings====<br />
<br />
Market definitions have changed considerably in Oolite 1.82. OXPs wishing to be compatible with both 1.80 and 1.82 may specify both the old and new keys and plists without conflicts. OXPs are '''recommended''' to use the new keys. See [[Trade-goods.plist]] and the pages linked from it for more information.<br />
<br />
====Injectors and torus====<br />
<br />
Injector and torus speeds are no longer a fixed multiple of normal flight speed. <code>player.ship.injectorsEngaged</code> and <code>player.ship.torusEngaged</code> are '''recommended''' to detect enabling of these flight modes.<br />
<br />
<br />
<br />
<br />
[[Category:Oolite]]<br />
[[Category:Oolite scripting]]</div>Cimhttps://wiki.alioth.net/index.php?title=Equipment.plist&diff=48167Equipment.plist2015-07-04T09:00:10Z<p>Cim: /* Equipment Structure */ note removed properties</p>
<hr />
<div>== Using Equipment ==<br />
<br />
Player buyable equipment is stored in a file named '''equipment.plist''' that resides in the Config folder of a OXP. You can add equipment by adding arrays to this plist file. Every equipment array is build of an array of entries.<br />
<br />
== Equipment Structure ==<br />
<br />
The following equipment data are read in by Oolite.<br />
<br />
(<br />
(<br />
1,<br />
300,<br />
Missile,<br />
"EQ_MISSILE",<br />
"Faulcon de Lacy HM3 homing missile, fast and accurate when used in conjunction with standard targetting scanners.",<br />
{<br />
"available_to_all" = YES;<br />
}<br />
)<br />
)<br />
<br />
1) The first entry is an integer that determines the technical level from which the equipment can be bought. A level of 99 has a special meaning. Only this value can be changed by script. ''Please note that the number displayed on the system data screen is one higher than the system's tech level, so to make equipment available at a displayed TL:10 and above in game, enter 9 here''.<br />
<br />
Repairs can take place at tech levels one lower than the purchase level, and occasionally equipment will be offered at systems of a slightly lower tech level than the number given here.<br />
<br />
2) The second entry is the costs of the equipment in tenths of a credit.<br />
<br />
3) This is a string that shows the name of the equipment as seen by the player.<br />
<br />
4) This is a string that shows the name of the equipment that is used by scripting. Must start with EQ_ and endings like _MISSILE or _MINE give it a special handling. <br />
<br />
5) This string gives a short description of the item.<br />
<br />
6) This is a dictionary that can contain several special features like:<br />
<br />
{<br />
"available_to_all" = yes;<br />
"available_to_NPCs" = yes;<br />
"available_to_player" = no;<br />
conditions = (<br />
"systemGovernment_number morethan 3" // note: deprecated and should not be used in new code<br />
);<br />
"condition_script" = "myoxp_conditions.js";<br />
"damage_probability" = 1.0;<br />
"fast_affinity_defensive" = no;<br />
"fast_affinity_offensive" = no;<br />
"incompatible_with_equipment" = "EQ_FUEL_SCOOPS";<br />
"installation_time" = 86400;<br />
"is_external_store" = no; // is missile or mine and added to pylon.<br />
"portable_between_ships" = yes;<br />
"provides" = ("EQ_CARGO_SCOOPS");<br />
"repair_time" = 3600;<br />
"requires_any_equipment" = (<br />
"EQ_FUEL_SCOOPS",<br />
"EQ_ECM<br />
);<br />
"requires_cargo_space" = 5;<br />
"requires_clean" = yes;<br />
"requires_empty_pylon" = yes;<br />
"requires_equipment" = "EQ_FUEL_SCOOPS";<br />
"requires_free_passenger_berth" = no;<br />
"requires_full_fuel" = no;<br />
"requires_mounted_pylon" = yes;<br />
"requires_not_clean" = yes;<br />
"requires_non_full_fuel" = no;<br />
"script" = "myCustomScript.js";<br />
"script_info" = {<br />
myCustomProperty = 0;<br />
};<br />
"strict_mode_only" = no; // version 1.77 or earlier only<br />
"strict_mode_compatible" = yes; // version 1.77 or earlier only<br />
"visible" = yes; // listed on the F5 screen.<br />
"weapon_info" = {<br />
range = 15000;<br />
energy = 0.5;<br />
damage = 6.0;<br />
recharge_rate = 0.1;<br />
shot_temperature = 3.2;<br />
color = "yellowColor";<br />
threat_assessment = 0.5;<br />
is_mining_laser = 0;<br />
is_turret_laser = 0;<br />
};<br />
}<br />
<br />
Most names will explain themselves. For detailed explanation look at the corresponding values in [[Oolite_JavaScript_Reference:_EquipmentInfo|EquipmentInfo.scriptInfo]]. In this list the empty/mounted pylons are not necessary when the equipment ends on MINE or MISSILE.<br />
<br />
===Notes===<br />
<br />
* Conditions can contain a single string with one condition or an array of condition strings. Conditions are only checked when the equipment would be available by the other criteria. The condition_script option, available from Oolite 1.77 onwards, specifies a Javascript file which controls the conditions for this equipment. The <code>allowAwardEquipment</code> function in that [[Oolite_JavaScript_Reference:_Condition_scripts|condition script]] will then be tested before the equipment is allowed.<br />
<br />
* <code>available_to_all</code> means all ships can buy the item. When not set it is only buyable when the equipment is defined in the [[shipyard.plist]] under optional_equipment. <br />
<br />
* <code>requires_cargo_space</code> is only used to determine a condition to show an item on the list. Until Oolite 1.76 it uses no cargo space when bought, and except for the core game's passenger cabins has a bug which will sometimes cause equipment to mysteriously vanish when reloading a saved game. Starting with Oolite 1.77, this key will use cargo space for user defined equipment. <br />
<br />
* "<code>script_info</code>" is added with test release 1.74. It contains a directory of custom entries that become properties of [[Oolite_JavaScript_Reference:_EquipmentInfo|EquipmentInfo.scriptInfo]]<br />
<br />
* "<code>script</code>" is added with test release 1.75. It contains a name of a script file used by the equipment. Equipment that contains a script is put on a special list. The player than can cycle through that list by pressing "shift-N". (similar as selecting a missile). The primed script is than the active script. Whenever a player now presses "n", the "this.activated()" event handler of the primed equipment is executed.<br />
this.activated = function ()<br />
{<br />
// your code<br />
}<br />
<br />
In testrelease 1.77 the 'b' key is added to primable equipment. Whenever the 'b' is pressed, the "this.mode()" event handler of the currently primed equipment is executed.<br />
this.mode = function ()<br />
{<br />
// your code<br />
}<br />
<br />
* <code>requires_equipment</code>, <code>requires_any_equipment</code>, <code>incompatible_with_equipment</code> can be a single string or an array of strings.<br />
<br />
* "<code>damage_probability</code>" is added in test release 1.77. It is the relative probability that this equipment will be damaged. It is ignored (and always zero) for missiles and mines, and defaults to 1.0 for all other equipment.<br />
<br />
* "<code>fast_affinity_defensive</code>" and "<code>fast_affinity_offensive</code>" are added in 1.79. These keys are ignored unless the equipment has a "script" file. If the equipment has a script file, then if set these keys make the equipment preferentially assigned to the "fast activation" keys ('0' and 'tab' in the default keys). This automatic assignment only happens if the equipment is bought while the current fast equipment assignment is blank (or is for equipment not currently installed). Generally these keys should only be set for equipment which might need to be activated quickly in an emergency.<br />
<br />
* "<code>installation_time</code>" and "<code>repair_time</code>" are added in 1.81. These override the standard 10 minutes plus one second per decicredit time to purchase an equipment item from the F3 screen. If only <code>installation_time</code> is specified the repair time will be half of that. If only <code>repair_time</code> is specified the installation time will be the default from the cost.<br />
<br />
* "<code>provides</code>" is added in 1.81, and is an array of equipment keys. This allows OXP equipment to provide some functionality from core equipment (or in theory other OXP equipment though this would need to be managed carefully between the OXPs). For example, a "navigation computer" might have <code>"provides" = ("EQ_DOCK_COMP","EQ_ADVANCED_COMPASS");</code>, and while this equipment was installed the player would get the benefits of those items even if they were not currently fitted. The default value is an empty array, though equipment is always considered to provide its own equipment key. While any string may be added here, only the following items have any in-game effect in the core game:<br />
** "EQ_ECM": 'e' key can be used to trigger an ECM blast<br />
** "EQ_FUEL_SCOOPS": may scoop fuel from a star<br />
** "EQ_CARGO_SCOOPS": may scoop cargo. Note: there is no such core game item, but the core fuel scoops have this in their 'provides' list.<br />
** "EQ_ESCAPE_POD": may eject with 'escape' key. The item providing this feature will be removed on use.<br />
** "EQ_DOCK_COMP": 'c' key may be used to initiate autopilot. If multiple items provide this, all must be damaged or removed for autopiloting to cease.<br />
** "EQ_GAL_DRIVE": may make a galactic jump with 'j' key. The item providing this feature will be removed on use.<br />
** "EQ_CLOAKING_DEVICE": may remain cloaked. Activation of the cloak via the primable equipment mechanism will not be duplicated simply by providing this item.<br />
** "EQ_FUEL_INJECTION": allows the 'i' key to be used for speed boost<br />
** "EQ_SCANNER_SHOW_MISSILE_TARGET": displays the [[Scanner Targeting Enhancement]] features<br />
** "EQ_MULTI_TARGET": allows independent locking of missiles<br />
** "EQ_ADVANCED_COMPASS": allows tracking of beacons and other objects on the compass<br />
** "EQ_ADVANCED_NAVIGATIONAL_ARRAY": allows route planning on the chart screen<br />
** "EQ_TARGET_MEMORY": allows storing and remembering of previous targets<br />
** "EQ_INTEGRATED_TARGETING_SYSTEM": visual tracking of remembered targets. Note that the core [[Integrated Targeting System]] item requires the Scanner Targeting Enhancement and Target Memory items to be installed before it can be bought, and this must be those specific items, not items providing those functions. ''However'', once installed it is sufficient for items providing those functions to be on board for the item to work.<br />
** "EQ_WORMHOLE_SCANNER": allows targeting and scanning of witchspace wormholes<br />
<br />
=== Creating laser weapons ===<br />
'''Note: this is a 1.81 prototype feature and may change significantly before release.'''<br />
<br />
Laser weapons must have a name beginning <code>"EQ_WEAPON_"</code>, and then should have a <code>weapon_info</code> dictionary describing them. This dictionary has the following keys, all of which can be omitted to keep the default value:<br />
* '''range''': The maximum range in metres, default 12500.<br />
* '''energy''': The energy used per shot, default 0.8.<br />
* '''damage''': The damage done to the target per shot, default 15.0.<br />
* '''recharge_rate''': The time to recharge between shots in seconds, default 0.5. A value of 0.1 will appear to be a continuous beam. Values lower than 0.1 are not recommended as they may cause the weapon's power to vary significantly depending on the frame rate.<br />
* '''shot_temperature''': The amount of heat generated per shot, default 7.0. Lasers will not fire at heat of 217.6 or over.<br />
* '''color''': The default colour of the laser, if the ship it is mounted on has not specified a laser colour. Any valid colour specifier can be used. The colour will be made "bright".<br />
* '''threat_assessment''': The effect having this weapon fitted has on the threat assessment level of the ship, default 0.0. The beam laser is 0.5, and the military and thargoid lasers are 1.0 in the core game. Values significantly outside this range may cause unusual AI behaviour.<br />
* '''is_mining_laser''': If true, the weapon will break up asteroids and boulders into smaller fragments. Default false.<br />
* '''is_turret_laser''': If true, the weapon will automatically aim independently of the ship facing like the thargoid laser. Default false. This is likely to give buggy behaviour if put on a player ship.<br />
<br />
<br />
<br />
[[Category:Oolite]]<br />
[[Category:Oolite scripting]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_PlayerShip&diff=47249Oolite JavaScript Reference: PlayerShip2015-04-28T15:48:06Z<p>Cim: /* routeMode */ document</p>
<hr />
<div><small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Ship|Ship]]</code></small><br /><br />
<small>'''Subtypes:''' none</small><br />
<br />
The '''<code>PlayerShip</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing the player’s ship. The <code>PlayerShip</code> has all the properties and methods of a <code> [[Oolite JavaScript Reference: Ship|Ship]]</code>, and several others. There is always exactly one PlayerShip object in existence, which can be accessed through <code>[[Oolite JavaScript Reference: Global#player|player]].ship</code>.<br />
<br />
Like any entity, the player ship can become [[Oolite JavaScript Reference: Entity#Stale References|invalid]] – specifically, when the player dies or ejects. Unlike other entities, the player ship can become valid again (after ejecting and being rescued). This is a technicality and it’s not guaranteed to work this way in future.<br />
<br />
== Properties ==<br />
=== <code>aftShield</code> ===<br />
'''aftShield''' : Number (read/write, nonnegative)<br />
The current aft shield level, ranging from 0 to <code>[[#maxAftShield|maxAftShield]]</code>.<br />
<br />
'''See also''': <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#forwardShield|forwardShield]]</code>, <code>[[#maxAftShield|maxAftShield]]</code><br />
<br />
=== <code>aftShieldRechargeRate</code> ===<br />
'''aftShieldRechargeRate''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)<br />
The rate at which the aft shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, but this is not the case from 1.81.<br />
<br />
'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code><br />
<br />
=== <code>cargoSpaceAvailable</code> ===<br />
'''cargoSpaceAvailable''' : Number (read-only integer)<br />
The ship’s available cargo space, in tons.<br />
<br />
=== <code>cargoSpaceUsed</code> ===<br />
'''cargoSpaceUsed''' : Number (read-only integer)<br />
The ship’s current cargo, in tons.<br />
<br />
=== <code>compassMode</code> ===<br />
'''compassMode''' : String (read-only)<br />
Returns the current compass mode, which can be any one of the following:<br />
* COMPASS_MODE_BASIC<br />
* COMPASS_MODE_PLANET<br />
* COMPASS_MODE_STATION<br />
* COMPASS_MODE_SUN<br />
* COMPASS_MODE_TARGET<br />
* COMPASS_MODE_BEACONS<br />
<br />
=== <code>compassTarget</code> ===<br />
'''compassTarget''' : Entity(read-only)<br />
Points at the entity currently targeted by the compass.<br />
<br />
=== <code>crosshairs</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''crosshairs''' : String (read/write)<br />
The name of the [[Crosshairs.plist|crosshairs.plist]] defining the ship’s weapon crosshairs. HUDs can define crosshairs separately. This value will be <code>null</code> if the HUD built-in crosshairs are in use, and setting it to <code>null</code> will revert to the default HUD crosshairs.<br />
<br />
If the HUD is changed, the old value of this property will be discarded, and the HUD's default crosshairs will be used.<br />
<br />
=== <code>currentWeapon</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''currentWeapon''' : EquipmentInfo (read/write)<br />
A shortcut property to whichever of [[Oolite_JavaScript_Reference:_Ship#aftWeapon|aftWeapon]], [[Oolite_JavaScript_Reference:_Ship#forwardWeapon|forwardWeapon]], [[Oolite_JavaScript_Reference:_Ship#portWeapon|portWeapon]] or [[Oolite_JavaScript_Reference:_Ship#starboardWeapon|starboardWeapon]] is the currently active player weapon.<br />
<br />
If the player is on a screen with no active weapon (e.g. docked, or viewing the status screens) then this will always be null, and attempting to write to it will give an error.<br />
<br />
=== <code>cursorCoordinates</code> ===<br />
'''cursorCoordinates''' : Vector3D (read-only)<br />
'''Discouraged in favour of <code>[[#cursorCoordinatesInLY|cursorCoordinatesInLY]]</code>.'''<br /><br />
The current x and y cursor coordinates on the long range screen in the internal coordinate system. The <code>z</code> coordinate is always 0.<br />
<br />
=== <code>cursorCoordinatesInLY</code> ===<br />
'''cursorCoordinatesInLY''' : Vector3D (read-only)<br />
The current x and y cursor coordinates on the long range screen, in light years. The <code>z</code> coordinate is always 0.<br />
<br />
=== <code>docked</code> ===<br />
'''docked''' : Boolean (read-only)<br />
True if the player is docked with a station or carrier.<br />
<br />
=== <code>dockedStation</code> ===<br />
'''dockedStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only)<br />
The station with which the player is currently docked.<br />
<br />
=== <code>forwardShield</code> ===<br />
'''forwardShield''' : Number (read/write, nonnegative)<br />
The current forward shield level, ranging from 0 to <code>[[#maxForwardShield|maxForwardShield]]</code>.<br />
<br />
'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code><br />
<br />
=== <code>forwardShieldRechargeRate</code> ===<br />
'''forwardShieldRechargeRate''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)<br />
The rate at which the forward shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, but this is no longer the case in 1.81<br />
<br />
'''See also''': <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#forwardShield|forwardShield]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code><br />
<br />
=== <code>fuelLeakRate</code> ===<br />
'''fuelLeakRate''' : Number (read/write)<br />
The rate at which the player is losing fuel, in tenths of a LY per second. May not be negative. Reset to 0 when fuel is empty.<br />
<br />
=== <code>galacticHyperspaceBehaviour</code> ===<br />
'''galacticHyperspaceBehaviour''' : String (read/write)<br />
A string indicating what the effect of a galactic hyperspace jump will be. The available options are:<br />
* <code>"BEHAVIOUR_STANDARD"</code>: the player arrives in the closest system to the starting point that is part of the main group of stars. Small groups (as seen in [[Oolite planet list/Galaxy 6|galaxy 6]], among others) can’t be reached.<br />
* <code>"BEHAVIOUR_ALL_SYSTEMS_REACHABLE"</code>: The player arrives at the closest system to the starting point, even if it is in a small group. '''Important:''' this can leave the player stranded, unless there are missions providing the possibility of escape!<br />
* <code>"BEHAVIOUR_FIXED_COORDINATES"</code>: The player arrives at the system closest to <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>.<br />
<br />
'''See also:''' <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code><br />
<br />
=== <code>galacticHyperspaceFixedCoords</code> ===<br />
'''galacticHyperspaceFixedCoords''' : [[Oolite JavaScript Reference: Vector3D|Vector3D]] (read/write)<br />
'''Discouraged in favour of <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>.'''<br /><br />
Like <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>, but in the internal coordinate system.<br />
<br />
=== <code>galacticHyperspaceFixedCoordsInLY</code> ===<br />
'''galacticHyperspaceFixedCoordsInLY''' : [[Oolite JavaScript Reference: Vector3D|Vector3D]] (read/write)<br />
The destination coordinates when <code>[[#galacticHyperspaceBehaviour|galacticHyperspaceBehaviour]]</code> mode is <code>"GALACTIC_HYPERSPACE_BEHAVIOUR_FIXED_COORDINATES"</code>. The coordinate system corresponds to <code>[[#galaxyCoordinatesInLY|galaxyCoordinatesInLY]]</code>. Currently, when assigning a value its <code>x</code> and <code>y</code> coordinates will be rounded to integer internal coordinates, and the <code>z</code> coordinate will be rejected.<br />
<br />
'''See also:''' <code>[[#galacticHyperspaceBehaviour|galacticHyperspaceBehaviour]]</code><br />
<br />
=== <code>galaxyCoordinates</code> ===<br />
'''galaxyCoordinates''' : Vector3D (read-only)<br />
'''Discouraged in favour of <code>[[#galaxyCoordinatesInLY|galaxyCoordinatesInLY]]</code>.'''<br /><br />
The player’s location in galactic space, in the internal coordinate system. The <code>z</code> coordinate is always 0.<br />
<br />
=== <code>galaxyCoordinatesInLY</code> ===<br />
'''galaxyCoordinatesInLY''' : Vector3D (read-only)<br />
The player’s location in galactic space, in light years (measured from the top left of the map). The <code>z</code> coordinate is always 0.<br />
<br />
=== <code>hud</code> ===<br />
'''hud''' : String (read/write)<br />
The name of the [[hud.plist|HUD plists]] defining the ship’s head up display.<br />
<br />
=== <code>hudHidden</code> ===<br />
'''hudHidden''' : Boolean (read/write)<br />
Whether the HUD should be visible.<br />
<br />
=== <code>hyperspaceSpinTime</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''hyperspaceSpinTime''' : Number (read-only, read/write in 1.81)<br />
The length of the ship's hyperspace countdown.<br />
<br />
Setting this to a negative value disables the drive entirely.<br />
<br />
=== <code>injectorsEngaged</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorsEngaged''' : Boolean(read-only)<br />
Is the player ship currently using fuel injection.<br />
<br />
=== <code>manifest</code> ===<br />
'''manifest''' : [[Oolite JavaScript Reference: Manifest|Manifest]] (read/write)<br />
The manifest contains all the cargo the player carries. It can be addressed as a property of playerShip as well as a class [[Oolite JavaScript Reference: Manifest|Manifest]] of its own.<br />
<br />
=== <code>maxAftShield</code> ===<br />
'''maxAftShield''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)<br />
The highest possible value of <code>[[#aftShield|aftShield]]</code>. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#maxForwardShield|maxForwardShield]]</code>, but this is not necessarily true from 1.81.<br />
<br />
'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code><br />
<br />
=== <code>maxForwardShield</code> ===<br />
'''maxAftShield''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)<br />
The highest possible value of <code>[[#forwardShield|forwardShield]]</code>. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#maxAftShield|maxAftShield]]</code>, but this is not necessarily true from 1.81.<br />
<br />
'''See also''': <code>[[#forwardShield|forwardShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code><br />
<br />
=== <code>missilesOnline</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''missilesOnline''' : Boolean (read-only)<br />
True if the ship's targeting system is currently in missile targeting mode, false if it is currently in identification mode.<br />
<br />
=== <code>multiFunctionDisplayList</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''multiFunctionDisplayList''' : Array (read-only, strings)<br />
The IDs of the currently active multi-function displays<br />
<br />
e.g.<br />
[null, "myoxp_mfd1"] // My OXP MFD1 in the second display, first display blank<br />
<br />
=== <code>multiFunctionDisplays</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''multiFunctionDisplays''' : Number (read-only, integer)<br />
The number of multi-function displays available on the current HUD.<br />
<br />
=== <code>price</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''price''' : Number (read-only, positive integer in decicredits)<br />
The value the player's ship would have, including equipment, if in a perfect servicing state. The ship can be exchanged at a shipyard for 75% of this value if it really is in perfect servicing state.<br />
<br />
=== <code>renovationCost</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''renovationCost''' : Number (read-only, positive integer in decicredits)<br />
The current price in decicredits to service the ship. Depending on the [[#serviceLevel|serviceLevel]] it may not be possible to actually purchase renovation at this time.<br />
<br />
=== <code>renovationMultiplier</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''renovationMultiplier''' : Number (read-only, positive)<br />
The multiplier applied to the base cost of renovation (<code>renovationCost</code> already includes this multiplier) to allow for some ships being more difficult to maintain than others. The default is 1.0 - other values are set in [[Shipyard.plist#renovation_multiplier|shipyard.plist]]<br />
<br />
=== <code>reticleTargetSensitive</code> ===<br />
'''reticleTargetSensitive''' : Boolean (read/write)<br />
If true, and Scanner Targeting Enhancement is installed, the selected target reticle will light up in red when the target is in the player’s sights. This is equivalent to the <code>reticle_target_sensitive</code> key in [[hud.plist|HUD plists]].<br />
<br />
=== <code>routeMode</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''routeMode''' : String (read-only)<br />
Gives the current mode of the [[Advanced Navigational Array]]. Three possible values<br />
* "OPTIMIZED_BY_NONE": off, or not fitted<br />
* "OPTIMIZED_BY_JUMPS": shortest route<br />
* "OPTIMIZED_BY_TIME": quickest route<br />
<br />
=== <code>scannerNonLinear</code> ===<br />
'''scannerNonLinear''' : Boolean (read/write)<br />
If <code>true</code>, the scanner is operating in non-linear mode. This property will be reset to the HUD default if the HUD is changed.<br />
<br />
=== <code>scannerUltraZoom</code> ===<br />
'''scannerUltraZoom''' : Boolean (read/write)<br />
If <code>true</code>, the scanner has 1x, 2x, 4x, 8x and 16x zoom modes, rather than the conventional 1x, 2x, 3x, 4x and 5x. This property will be reset to the HUD default if the HUD is changed.<br />
<br />
=== <code>scoopOverride</code> ===<br />
'''scoopOverride''' : Boolean (read/write)<br />
If <code>true</code>, and the player has a fuel scoop, the fuel scoop effect will run even if not close to a sun or scooping cargo.<br />
<br />
=== <code>serviceLevel</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''serviceLevel''' : Number (read/write, positive integer in range 75-100)<br />
The level of servicing the player's ship has. Renovation will be offered in shipyards at 85 or below, and malfunctions are more likely at lower values. This affects the sales price of the ship.<br />
<br />
=== <code>specialCargo</code> ===<br />
'''specialCargo''' : String (read-only)<br />
The special cargo the player is carrying, if any; otherwise <code>null</code>.<br />
<br />
'''See also''': <code>[[#useSpecialCargo|useSpecialCargo]]()</code><br />
<br />
=== <code>targetSystem</code> ===<br />
'''targetSystem''' : Integer (read-only, sometimes read/write in 1.77)<br />
The ID of the selected hyperspace target system. In 1.77, it can be written to if the player's ship is docked.<br />
<br />
=== <code>torusEngaged</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''torusEngaged''' : Boolean(read-only)<br />
Is the player ship currently using torus drive<br />
<br />
=== <code>viewDirection</code> ===<br />
'''viewDirection''' : String (read-only)<br />
Returns the view direction as string: <code>"VIEW_FORWARD"</code>, <code>"VIEW_AFT"</code>, <code>"VIEW_PORT"</code>, <code>"VIEW_STARBOARD"</code>, <code>"VIEW_CUSTOM"</code> or <code>"VIEW_GUI_DISPLAY"</code>.<br />
<br />
=== <code>viewPosition*</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''viewPositionAft''' : Vector (read-only)<br />
'''viewPositionForward''' : Vector (read-only)<br />
'''viewPositionPort''' : Vector (read-only)<br />
'''viewPositionStarboard''' : Vector (read-only)<br />
The ship's 4 point-of-view positions in XYZ relative to the model. The corresponding ''[[shipdata.plist]]'' keys start with <code>view_position_</code>.<br />
<br />
=== <code>weaponsOnline</code> ===<br />
'''weaponsOnline''' : Boolean (read-only)<br />
Returns the weapon safety status. Player can toggle the status with the underscore-key.<br />
<br />
== Methods ==<br />
=== <code>addParcel</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''addParcel'''(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean<br />
Add a parcel contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.<br />
<br />
Returns <code>false</code> when there is already a parcel with that name or the arrival time is invalid.<br />
<br />
The <code>advance</code> and <code>risk</code> parameters were added in Oolite 1.79. <code>advance</code> is purely advisory and describes any up-front payment given for the parcel. <code>risk</code> can be 0, 1 or 2 - the higher the number, the more likely that assassins are likely to try to kill the player while they carry this parcel.<br />
<br />
=== <code>addPassenger</code> ===<br />
function '''addPassenger'''(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean<br />
Add a passenger contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.<br />
<br />
Returns <code>false</code> when there is no room for the passenger, there is already a passenger with that name or the arrival time is invalid.<br />
<br />
'''Example:'''<br />
player.ship.addPassenger("cmdr Jameson", 34, 67, clock.seconds+3*24*3600, 1500);<br />
<br />
If successful - and in galaxy chart 1 - the player will have cmdr Jameson as a passenger, his documents will show that he boarded the ship at Inus, to go to Cemave, within exactly 3 days, and the player will be given 1500 credits if he gets there on time (early or late arrival will affect the amount paid).<br />
<br />
'''N.B.''' Normally a passenger will pay the captain a small advance upon boarding. Using this method, no initial payment is made. In versions after 1.77, an optional parameter can be added to describe what the advance ''was'', without actually making it.<br />
<br />
The risk parameter was added in Oolite 1.79. <code>risk</code> can be 0, 1 or 2 - the higher the number, the more likely that assassins are likely to try to kill the player while they carry this passenger.<br />
<br />
=== <code>awardContract</code> ===<br />
function '''awardContract'''(quantity : Number, commodity : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, premium : Number]) : Boolean<br />
Add a cargo contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.<br />
<br />
Returns <code>false</code> when there is no room for the cargo, the arrival time is invalid.<br />
<br />
'''Example:'''<br />
player.ship.awardContract(12, "Food", 34, 67, clock.seconds+7*24*3600, 5000)<br />
<br />
If successful - and in galaxy chart 1 - the player will have 12 more food containers on board, the manifest will show that the cargo was picked up at Inus, to be delivered at Cemave, within exactly 7 days, and the player will be given 5000 credits if the cargo is delivered on time (early or late delivery will affect the amount paid).<br />
<br />
'''N.B.''' Normally to get a contract, the player will have to pay a deposit similar in value to the cargo. Using this method, no deposit payment is made. In versions after 1.77, an optional parameter can be added to describe what the deposit payment ''was'', without actually making it.<br />
<br />
=== <code>awardEquipmentToCurrentPylon</code> ===<br />
function '''awardEquipmentToCurrentPylon'''(item : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Replace the missile or mine currently being launched with the specified item (which must be an external store). This will only have an effect if called while a missile or mine is being launched. Effectively this means that this method must be used within the <code>shipFiredMissile()</code> handler or in the ENTER message of the GLOBAL state of an missileAI.plist.<br />
<br />
'''Bug:''' In Oolite 1.74.0, if <code>awardEquipmentToCurrentPylon()</code> fails the script will be halted without any error message. In future versions, it will simply return <code>false</code>.<br />
<br />
'''See also:''' <code>[[Oolite JavaScript Reference: Ship#awardEquipment|Ship.awardEquipment()]]</code><br />
<br />
=== <code>beginHyperspaceCountdown</code> ===<br />
{{oolite-method-added|1.77}}<br />
function beginHyperspaceCountdown( [ length : Number ] ) : Boolean<br />
This function begins the witchspace sequence for the player ship. It returns true if the sequence is started successfully, and false otherwise (no destination selected, insufficient fuel, out of range, etc.). Optionally, the length of the countdown can be varied. Values between 5 and 60 seconds are accepted. If this parameter is omitted the default sequence length for this class of ship will be used.<br />
<br />
'''See also:''' <code>[[#cancelHyperspaceCountdown|cancelHyperspaceCountdown]]</code><br />
<br />
=== <code>cancelHyperspaceCountdown</code> ===<br />
{{oolite-method-added|1.77}}<br />
function cancelHyperspaceCountdown() : Boolean<br />
This function cancels the witchspace sequence for the player ship. It returns true if there was an ongoing sequence to cancel, and false otherwise.<br />
<br />
'''See also:''' <code>[[#beginHyperspaceCountdown|beginHyperspaceCountdown]]</code><br />
<br />
=== <code>disengageAutopilot</code> ===<br />
function disengageAutopilot()<br />
Disenable autopilot.<br />
<br />
'''See also:''' <code>[[#engageAutopilotToStation|engageAutopilotToStation()]]</code><br />
<br />
=== <code>engageAutopilotToStation</code> ===<br />
function engageAutopilotToStation(station : [[Oolite JavaScript Reference: Station|Station]]) : Boolean<br />
Engage autopilot, set to dock with the specified station.<br />
<br />
'''See also:''' <code>[[#disengageAutopilot|disengageAutopilot()]]</code><br />
<br />
=== <code>hideHUDSelector</code> ===<br />
{{oolite-method-added|1.79}}<br />
function hideHUDSelector(selector : String)<br />
Hide all dials using the specified selector on the HUD display. For example<br />
<br />
player.ship.hideHUDSelector("drawScanner:");<br />
<br />
'''See also:''' <code>[[#showHUDSelector|showHUDSelector()]]</code><br />
<br />
=== <code>launch</code> ===<br />
function '''launch'''()<br />
Launches the player’s ship if it is currently docked.<br />
<br />
=== <code>removeAllCargo</code> ===<br />
function '''removeAllCargo'''()<br />
Removes all cargo from the ship’s cargo bay that are measured in tons. Does not affect Gold, Platinum or Gemstones. Can only be used while docked.<br />
<br />
=== <code>removeContract</code> ===<br />
function '''removeContract'''(commodity : String, destination : Number)<br />
Remove the cargo contract matching that commodity and destination.<br />
<br />
=== <code>removeParcel</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''removeParcel'''(name : String)<br />
Remove a named parcel.<br />
<br />
=== <code>removePassenger</code> ===<br />
function '''removePassenger'''(name : String)<br />
Remove a named passenger.<br />
<br />
=== <code>resetCustomView</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''resetCustomView'''()<br />
Resets the custom view back to the last-used setting defined in [[shipdata.plist]]<br />
<br />
This function gives an error if used when the custom view camera is not selected.<br />
<br />
=== <code>resetScannerZoom</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''resetScannerZoom'''()<br />
Resets the scanner zoom back to 1:1<br />
<br />
=== <code>setCustomView</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''setCustomView'''(Vector : position, Quaternion : orientation [,WeaponDirection weapon])<br />
Set the position and orientation of the custom view camera to those specified. As with the custom views specified through [[shipdata.plist]], these are relative to the player's ship's position, and the coordinate frame defined by the ship's forward, right and up Vectors.<br />
<br />
The optional weapon parameter can be "FORWARD", "AFT", "PORT" or "STARBOARD" and sets the active weapon accordingly. If omitted, the active weapon for the previous custom view will be preserved.<br />
<br />
This function gives an error if used when the custom view camera is not selected. Setting the custom view does not affect the custom views defined in [[shipdata.plist]], which will be switched back to the next time 'v' is pressed, or when [[#resetCustomView|resetCustomView]] is called.<br />
<br />
=== <code>setCustomHUDDial</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''setCustomHUDDial'''(key : String, value : Value)<br />
Sets the custom HUD dial [[hud.plist#data_source|data source]] 'key' to the specified value. Different types of custom HUD dial will expect different types of values; a value of an incorrect type will be converted if possible.<br />
<br />
=== <code>setMultiFunctionDisplay</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setMultiFunctionDisplay'''(index : Number, key : String) : Boolean<br />
Sets the multi-function display with the specified number to display the given multi-function display <code>key</code> set earlier with [[#setMultiFunctionText|setMultiFunctionText()]]. Multi-function displays are numbered from 0 to [[#multiFunctionDisplays|multiFunctionDisplays]]-1. If the index given is outside this range, the first unused multi-function display will be used, or the function will return <code>false</code> if all are currently in use.<br />
Example:<br />
// picks first unused one<br />
player.ship.setMultiFunctionDisplay(player.ship.multiFunctionDisplays, "myOxp_mfd");<br />
<br />
As the player can cycle the contents of their displays between the various active keys themselves using keyboard controls, it is advisable not to call this function to override a specific display except in emergencies, as this is likely to annoy the player.<br />
<br />
=== <code>setMultiFunctionText</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setMultiFunctionText'''(key : String [, contents : String [, reflow : Boolean]])<br />
Set the text for the multi-function display with the specified <code>key</code> to be <code>contents</code>. The limit on space for a multi-function display is ten lines of text, each 15 blocks wide. <br />
<br />
If you specify the optional <code>reflow</code> parameter, then the text given will automatically be fitted into the available space, with any extra discarded. Otherwise, line-breaks will not be added automatically, so you must enter them into <code>contents</code> yourself. If any individual line is more than 15 blocks long, the text will be compressed to fit it into the available space. This looks bad and is best avoided.<br />
<br />
=== <code>showHUDSelector</code> ===<br />
{{oolite-method-added|1.79}}<br />
function showHUDSelector(selector : String)<br />
Show all dials using the specified selector on the HUD display if they were previously hidden. For example<br />
<br />
player.ship.showHUDSelector("drawScanner:");<br />
<br />
'''See also:''' <code>[[#hideHUDSelector|hideHUDSelector()]]</code><br />
<br />
=== <code>takeInternalDamage</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''takeInternalDamage'''()<br />
Causes the player ship to potentially take "internal damage". Internal damage can also be caused by hits on the hull and some witchdrive malfunctions, and this function uses the same algorithm to determine the damage taken, which can be:<br />
* damage to cargo<br />
* damage to equipment (according to the damage_probability)<br />
* reduction in [[#serviceLevel|service level]]<br />
* no damage<br />
The function will return 'false' if "no damage" was selected, and 'true' otherwise. The relative probabilities of the three options vary depending on the size of the player ship, its cargo capacity, cargo carried and installed equipment.<br />
<br />
=== <code>useSpecialCargo</code> ===<br />
function '''useSpecialCargo'''(description : String)<br />
Fills the cargo bay with the cargo described, effectively disabling the use of the cargo bay until the cargo is removed.<br />
<br />
'''See also''': <code>[[#specialCargo|specialCargo]]</code><br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Ship&diff=47232Oolite JavaScript Reference: Ship2015-04-25T13:43:43Z<p>Cim: /* entityPersonality */ writable in 1.81</p>
<hr />
<div><small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Entity|Entity]]</code></small><br /><br />
<small>'''Subtypes:''' <code>[[Oolite JavaScript Reference: Station|Station]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code></small><br />
<br />
The '''<code>Ship</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing a ship, station, missile, cargo pod or other flying item – anything that can be specified in [[shipdata.plist]]. A <code>Ship</code> has all the properties and methods of a <code>Entity</code>, and several others.<br />
<br />
<code>[[Oolite JavaScript Reference: Station|Station]]</code>s and the <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code> are types of ship. Note that these more specific types have additional properties and methods.<br />
<br />
== Properties ==<br />
=== <code>accuracy</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''accuracy''' : Number (read/write, read-only and irrelevant for player ship)<br />
The accuracy of the ship's AI. Varies between -5 and +10 for ships, or 0 and +10 for missiles. Setting a value outside the allowed range will set the closest value within the allowed range.<br />
<br />
For missiles, this affects the missile tracking, with 0 being the default value.<br />
<br />
For NPC ships, this affects their combat AI in many ways. Values of +5 or higher enable various [[OXP_NPC_Combat_AI|special combat AIs]] for a tough fight.<br />
<br />
=== <code>aftWeapon</code> ===<br />
'''aftWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped aft weapon, or <code>null</code>.<br />
<br />
'''See also:''' <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>AI</code> ===<br />
'''AI''' : String (read-only)<br />
The name of the ship’s current plist-based state machine AI. If the ship is using Javascript-based AI, this will always be "<code>nullAI.plist</code>"<br />
<br />
'''See also:''' <code>[[#AIState|AIState]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AIScript|AIScript]]</code><br />
<br />
=== <code>AIFoundTarget</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''AIFoundTarget''' : Entity (read/write, read-only for player)<br />
The "found target" of the ship's AI. This is set by various AI state commands, and is often copied to the primary target with the <code>setTargetToFoundTarget</code> AI command.<br />
<br />
=== <code>AIPrimaryAggressor</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''AIPrimaryAggressor''' : Entity (read/write, read-only for player)<br />
The "primary aggressor" of the ship's AI. Often the last ship to attack this ship.<br />
<br />
=== <code>AIScript</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''AIScript''' : String (read-only)<br />
The name of the ship’s current Javascript-based AI. If the ship is using plist-based AI, this will always be "<code>oolite-nullAI.js</code>"<br />
<br />
'''See also:''' <code>[[#AIScriptWakeTime|AIScriptWakeTime]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AI|AI]]</code><br />
<br />
=== <code>AIScriptWakeTime</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''AIScriptWaketime''' : Number (read-write)<br />
The next game time at which the ship's Javascript-based AI script will receive an <code>aiAwoken</code> event.<br />
<br />
=== <code>AIState</code> ===<br />
'''AIState''' : String (read/write, read-only for player)<br />
The ship’s plist AI’s current state.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#reactToAIMessage|reactToAIMessage()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code><br />
<br />
=== <code>alertCondition</code> ===<br />
'''alertCondition''' : Number (read-only integer)<br />
The ship's current alert condition (Docked = 0, Green = 1, Yellow = 2, Red = 3). Non-Station non-Player ships are generally only found at condition Yellow or Red.<br />
<br />
'''See also:''' [[Oolite_JavaScript_Reference:_Station#alertCondition|station.alertCondition]]<br />
<br />
=== <code>autoAI</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''autoAI''' : Boolean (read-only)<br />
The value of the "<code>auto_ai</code>" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the AI of this ship to better fit into scenarios or roles. If this is false, the ship's provider would prefer you not to alter the AI of this ship but to use it as-is.<br />
<br />
=== <code>autoWeapons</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''autoWeapons''' : Boolean (read-only)<br />
The value of the "<code>auto_weapons</code>" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the properties of this ship to better fit into scenarios or roles. If this is false, the ship's provider would prefer you not to alter the properties of this ship but to use it as-is.<br />
<br />
=== <code>beaconCode</code> ===<br />
'''beaconCode''' : String (read-only in 1.76, read-write from 1.77)<br />
If the ship is a beacon, an identifying string. The first character is used for identification on the [[Advanced Space Compass]]. For non-beacons, this property is <code>null</code>. This can not be changed by script for either the player's ship or the main station.<br />
<br />
'''See also:''' <code>[[#isBeacon|isBeacon]]</code><br />
<br />
=== <code>beaconLabel</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''beaconLabel''' : String (read/write)<br />
A full label for the beacon. This is useful where the beacon code and the full beacon label do not begin with the same letter.<br />
<br />
=== <code>boundingBox</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''boundingBox''' : Vector (read-only)<br />
For ships, a vector describing the dimensions of the cuboid box containing the ship aligned to the ship axes, including all non-flasher sub-entities. For sub-entities, the dimensions of the box for the sub-entity alone.<br />
<br />
Vector components match the standard model order - <code>x</code> is width, <code>y</code> is height, <code>z</code> is length.<br />
<br />
=== <code>bounty</code> ===<br />
'''bounty''' : Number (read/write integer)<br />
The bounty on the ship.<br />
<br />
In 1.77, changes to the bounty are given a reason. If you change this directly, the reason sent to [[Oolite_JavaScript_Reference:_ship_script_event_handlers#shipBountyChanged|shipBountyChanged]] will be "scripted". To set a different reason, use [[#setBounty|setBounty]] instead.<br />
<br />
=== <code>cargoList</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''cargoList''' : Array (read-only)<br />
A list of the ship's current cargo, grouped by cargo type. For the player ship, this is equivalent to <code>player.ship.manifest.list</code><br />
<br />
=== <code>cargoSpaceCapacity</code> ===<br />
'''cargoSpaceCapacity''' : Number (read-only in 1.80, read/write in 1.81, integer)<br />
The ship’s cargo capacity, in tons.<br />
<br />
=== <code>collisionExceptions</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''collisionExceptions''' : Array (read-only)<br />
A list of ships this ship is currently prevented from colliding with. See [[#addCollisionException|addCollisionException]] and [[#removeCollisionException|removeCollisionException]].<br />
<br />
=== <code>commodity</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''commodity''' : String (read-only)<br />
The commodity for cargo containers as a lowercase string. Returns <code>null</code> for non-cargo ships. For scripted cargo that has no specific cargo defined, it returns the general description "goods".<br />
<br />
=== <code>commodityAmount</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''commodityAmount''' : Number (read-only)<br />
The amount of commodity in a cargo container. (not the number of containers in a ship)<br />
<br />
=== <code>contracts</code> ===<br />
'''contracts''' : Array (read-only NSDictionary)<br />
The ship’s contracts. (For now only available for the player). Each contract contains the entries: <code>commodity: string, quantity: integer, description: string, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
<br />
For example, the information of the first contract can be obtained by:<br />
player.ship.contracts[0].commodity<br />
player.ship.contracts[0].quantity<br />
player.ship.contracts[0].description<br />
player.ship.contracts[0].start<br />
player.ship.contracts[0].destination<br />
player.ship.contracts[0].startName<br />
player.ship.contracts[0].destinationName<br />
player.ship.contracts[0].eta // Estimated Time of Arrival.<br />
player.ship.contracts[0].etaDescription<br />
player.ship.contracts[0].fee // The profit of the contract, paid out on successful delivery.<br />
player.ship.contracts[0].premium // The sum paid to obtain the goods and paid back on successful delivery.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this contract, and premium was the amount the player had to pay to secure this contract.<br />
<br />
=== <code>cloakAutomatic</code> ===<br />
'''cloakAutomatic''' : Boolean (read/write)<br />
If <code>true</code> (the default), the ship will automatically engage its cloak while attacking. Otherwise, it must be managed by a script. The corresponding ''[[shipdata.plist]]'' key is <code>cloak_automatic</code>.<br />
<br />
=== <code>crew</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''crew''' : Array (read-only)<br />
An array containing the ship's crew. Each crew member is represented as a dictionary. Note that in current Oolite versions ships only have a single crew member defined.<br />
<br />
=== <code>cruiseSpeed</code> ===<br />
'''cruiseSpeed''' : Number (read-only nonnegative)<br />
The ship’s “normal” <code>[[#desiredSpeed|desiredSpeed]]</code>, used in normal flight. Normally this is 80 % of <code>[[#maxSpeed|maxSpeed]]</code>, but it may be lowered when accepting a slow escort.<br />
<br />
=== <code>currentWeapon</code> ===<br />
{{oolite-prop-added|1.77}} <br />
'''currentWeapon''' : EquipmentType (read/write)<br />
A shortcut property to whichever of <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code> or <code>[[#starboardWeapon|starboardWeapon]]</code> represents the ship's currently active laser mount.<br />
<br />
=== <code>dataKey</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''dataKey''' : String (read-only)<br />
The ship data key used to define this ship (e.g. <code>adder-player</code> or <code>coriolis-station</code>)<br />
<br />
=== <code>defenseTargets</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''defenseTargets''' : Array (read-only)<br />
The array of defense targets that the ship has. If the ship has point defense weapons (turrets, thargoid lasers) it may fire them at these targets if it cannot hit its primary target.<br />
<br />
'''See also:''' <code>[[#addDefenseTarget|addDefenseTarget]]</code>, <code>[[#clearDefenseTargets|clearDefenseTargets]]</code><br />
<br />
=== <code>desiredRange</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''desiredRange''' : Number (read/write nonnegative, read-only for player)<br />
The range the AI uses in various AI routines to set a distance between the ship and another object - for example, the radius of a sphere around a destination point, or the distance to flee from a hostile ship.<br />
<br />
=== <code>desiredSpeed</code> ===<br />
'''desiredSpeed''' : Number (read/write nonnegative, read-only for player)<br />
The speed the AI will attempt to maintain. The AI core and AI script may change this from time to time. The corresponding AI method is <code>setSpeedFactorTo:</code>; a speed factor of 1.0 corresponds to a <code>desiredSpeed</code> equal to <code>[[#maxSpeed|maxSpeed]]</code>.<br />
<br />
'''See also:''' <code>[[#cruiseSpeed|cruiseSpeed]]</code><br />
<br />
=== <code>destination</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''destination''' : Vector (read/write, read-only for player)<br />
The destination coordinates for the AI, used in behaviours such as <code>performFlyToRangeFromDestination</code>.<br />
<br />
=== <code>destinationSystem</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''destinationSystem''' : Number (read/write)<br />
The destination system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.<br />
<br />
=== <code>displayName</code> ===<br />
'''displayName''' : String (read/write, read-only for player)<br />
The name of the ship as seen by the player. By default in 1.78 or earlier it is the same as <code>[[#name|name]]</code>. In 1.79 or later it is a combination of [[#shipClassName|shipClassName]] and [[#shipUniqueName|shipUniqueName]]<br />
<br />
=== <code>dockingInstructions</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''dockingInstructions''' : Object (read-only)<br />
If the ship is currently attempting to dock with a station, this describes the next step on its docking procedure<br />
<br />
{<br />
station: [Station "Coriolis Station" "Coriolis Station" position: (-31043.6, -94232.3, 619036) scanClass: CLASS_STATION status: STATUS_ACTIVE],<br />
match_rotation: 0,<br />
ai_message: "APPROACH_COORDINATES",<br />
speed: 512,<br />
destination: {<br />
x: -28033.37401563089,<br />
y: -92813.76688970842,<br />
z: 622226.0625336492<br />
},<br />
range: 96<br />
}<br />
<br />
'''See also:''' <code>[[#requestDockingInstructions|requestDockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code><br />
<br />
=== <code>energyRechargeRate</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''energyRechargeRate''' : Number (read-only, read/write from 1.81)<br />
The rate at which energy is replenished in every second. The corresponding ''[[shipdata.plist]]'' key is <code>energy_recharge_rate</code>.<br />
<br />
Note for the player ship that this includes the boost from an extra or naval energy unit, and NPC (but not player) ships with military shield boosters also have an increase to this in lieu of actual shields.<br />
<br />
=== <code>entityPersonality</code> ===<br />
'''entityPersonality''' : Number (read-only integer, read/write in 1.81 onwards)<br />
A random number in the range 0..32767 which is generated when the ship is created. Equivalent to the <code>entityPersonalityInt</code> [[Shaders in Oolite: uniforms#Ship|uniform binding]].<br />
<br />
Altering this value is possible in 1.81 onwards, but requires a re-bind of the materials and shaders, and so is a relatively slow process.<br />
<br />
=== <code>equipment</code> ===<br />
'''equipment''' : Array of [[Oolite_JavaScript_Reference:_EquipmentInfo|EquipmentInfo ]] (read-only)<br />
The equipment a ship is carrying.<br />
<br />
=== <code>escortGroup</code> ===<br />
'''escortGroup''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]<br />
The ship’s deployed escorts.<br />
<br />
'''See also:''' <code>[[#maxEscorts|maxEscorts]]</code><br />
<br />
=== <code>escorts</code> ===<br />
'''escorts''' : Array (read-only array of [[Oolite JavaScript Reference: Entity|Entity]]s)<br />
The ship’s deployed escorts.<br />
<br />
=== <code>exhaustEmissiveColor</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''exhaustEmissiveColor''' : Color (read/write)<br />
The baseline colour of the ship's exhaust. Damage to the ship, and use of injectors and torus drive, apply a fixed transformation to this colour, so not all colours are effective as exhaust colours.<br />
<br />
=== <code>exhausts</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''exhausts''' : Array (read-only)<br />
An array of the ship's [[Oolite_JavaScript_Reference:_ExhaustPlume|ExhaustPlume]] subentities.<br />
<br />
=== <code>extraCargo</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''extraCargo''' : Number (read-only integer)<br />
The amount the cargo capacity increases when an extra cargobay is installed. The corresponding ''[[shipdata.plist]]'' key is <code>extra_cargo</code>.<br />
<br />
=== <code>flashers</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''flashers''' : Array (read-only)<br />
An array of the ship's [[Oolite_JavaScript_Reference:_Flasher|Flasher]] subentities.<br />
<br />
=== <code>forwardWeapon</code> ===<br />
'''forwardWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped forward weapon, or <code>null</code>.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>fuel</code> ===<br />
'''fuel''' : Number (read/write)<br />
The ship’s current fuel capacity, in LY. The game will limit this to the range 0..7, and round it off to the nearest tenth.<br />
<br />
'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#fuelLeakRate|PlayerShip.fuelLeakRate]]</code><br />
<br />
=== <code>fuelChargeRate</code> ===<br />
'''fuelChargeRate''' : Number (read-only)<br />
The cost, relative to the cost for a new Cobra III, of a unit of fuel. When buying fuel for a ship, the price in [[equipment.plist]] will be multiplied by this number.<br />
<br />
=== <code>group</code> ===<br />
'''group''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]<br />
Contains ship’s belonging to each other. Added pirate groups are an example or a station with its launched defenders.<br><br />
A group is an individual object that can be linked to several ships belonging to the same group. When a ship dies and the group object has still owners, the group stays active as object. The group is only removed from memory after the last ship that had this group as property is removed.<br><br />
Adding a group to a ship does not automatic puts that ship in the group. For that to happen you need also use the addShip() command. <br />
e.g. <br />
this.ship.group = new ShipGroup();<br />
this.ship.group.addShip(this.ship);<br />
<br />
=== <code>hasHostileTarget</code> ===<br />
'''hasHostileTarget''' : Boolean (read-only)<br />
<code>true</code> if the ship’s AI is trying to kill something, <code>false</code> otherwise. Always <code>false</code> for the player.<br />
<br />
=== <code>hasHyperspaceMotor</code> ===<br />
'''hasHyperspaceMotor''' : Boolean (read-only)<br />
True if the ship can make witchspace jumps. The corresponding ''[[shipdata.plist]]'' entry is <code>hyperspace_motor</code>.<br />
<br />
=== <code>hasSuspendedAI</code> ===<br />
'''hasSuspendedAI''' : Boolean (read-only)<br />
<code>true</code> if the ship has suspended AIs, <code>false</code> otherwise.<br />
<br />
=== <code>heatInsulation</code> ===<br />
'''heatInsulation''' : Number (read/write)<br />
The ship’s heat insulation factor. 1.0 is normal, higher values mean more resistance to heat.<br />
<br />
Note that in 1.80 and earlier writes to this property had no effect on the player ship.<br />
<br />
=== <code>homeSystem</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''homeSystem''' : Number (read/write)<br />
The home system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.<br />
<br />
=== <code>hyperspaceSpinTime</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''hyperspaceSpinTime''' : Number (read/write)<br />
The length of the ship's hyperspace countdown.<br />
<br />
Setting this to a negative value disables the drive entirely.<br />
<br />
Note that most NPC ship jumps use <code>ship.exitSystem()</code> to make the jump, which does not have a delay. Provided this value is zero or positive, the ship will jump instantly if <code>ship.exitSystem()</code> is called. The AI must use this property elsewhere if a delay before jumping is required.<br />
<br />
=== <code>injectorBurnRate</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorBurnRate''' : Number (read/write)<br />
The rate at which the ship's injectors burn fuel in deci-LY per second. The default is 0.25.<br />
<br />
=== <code>injectorSpeedFactor</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorSpeedFactor''' : Number (read/write)<br />
The multiplier to maximum speed granted to this ship when it is using injectors. The default is 7, and values must be between 1.0 and 32.0 (the torus drive's speed)<br />
<br />
=== <code>isBeacon</code> ===<br />
'''isBeacon''' : Boolean (read-only)<br />
<code>true</code> if the ship is a beacon (i.e., can show up on the [[Advanced Space Compass]] with a character indicating its identity), <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#beaconCode|beaconCode]]</code><br />
<br />
=== <code>isBoulder</code> ===<br />
'''isBoulder''' : Boolean (read/write)<br />
<code>true</code> if the ship is a boulder (i.e., has the role "boulder in its roleset)<br />
<br />
=== <code>isCargo</code> ===<br />
'''isCargo''' : Boolean (read-only)<br />
<code>true</code> if the ship is cargo (i.e., has scan_class CLASS_CARGO and contains at least one unit)<br />
<br />
=== <code>isCloaked</code> ===<br />
'''isCloaked''' : Boolean (read/write)<br />
<code>true</code> if the ship has a cloaking device which is currently active <code>false</code> otherwise. If the ship has a cloaking device and sufficient energy to use it (<code>energy > 0.75 * [[Oolite JavaScript Reference: Entity#maxEnergy|maxEnergy]]</code>), you can activate it by setting <code>isCloaked</code> to <code>true</code>.<br />
<br />
=== <code>isDerelict</code> ===<br />
'''isDerelict''' : Boolean (read-only)<br />
<code>true</code> if the ship is a derelict (i.e., the pilot has ejected from the ship, or the ship was created with the ship-key: "is_hulk")<br />
<br />
=== <code>isFleeing</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isFleeing''' : Boolean (read-only)<br />
<code>true</code> if the ship is currently fleeing combat. This may be queried for the player ship too, though the value is somewhat of a guess in that case as it's impossible to say for certain what the player is intending by their actions.<br />
<br />
=== <code>isFrangible</code> ===<br />
'''isFrangible''' : Boolean (read-only)<br />
<code>true</code> if the ship is frangible (i.e., its subentities can be destroyed separately from the main ship), <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>isJamming</code> ===<br />
'''isJamming''' : Boolean (read-only)<br />
<code>true</code> if the ship has a military scanner jammer which is currently active <code>false</code> otherwise.<br />
<br />
=== <code>isMinable</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isMinable''' : Boolean (read-only)<br />
<code>true</code> if the ship will break up usefully when hit by a mining laser, <code>false</code> otherwise. By default this is true for anything with "asteroid" or "boulder" in its role list - if you need to add anything which miners shouldn't be shooting at to those roles, give it <code>"no_boulders" = yes;</code> in its [[shipdata.plist]].<br />
<br />
=== <code>isMine</code> ===<br />
'''isMine''' : Boolean (read-only)<br />
<code>true</code> if the ship is a mine, <code>false</code> otherwise.<br />
<br />
=== <code>isMissile</code> ===<br />
'''isMissile''' : Boolean (read-only)<br />
<code>true</code> if the ship is a missile, <code>false</code> otherwise.<br />
<br />
=== <code>isPiloted</code> ===<br />
'''isPiloted''' : Boolean (read-only)<br />
<code>true</code> if the ship has a pilot on board, <code>false</code> otherwise. Generally have ships, station and escape pods pilots and have cargo, rocks, missiles or buoys no pilots.<br />
<br />
=== <code>isPirate</code> ===<br />
'''isPirate''' : Boolean (read-only)<br />
<code>true</code> if the ship is a pirate vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "pirate"</code>.<br />
<br />
=== <code>isPirateVictim</code> ===<br />
'''isPirateVictim''' : Boolean (read-only)<br />
<code>true</code> if the ship’s [[#primaryRole|primary role]] is listed in ''pirate-victim-roles.plist'', <code>false</code> otherwise. This is the same test used by the pirate AI to select victims.<br />
<br />
=== <code>isPolice</code> ===<br />
'''isPolice''' : Boolean (read-only)<br />
<code>true</code> if the ship is a police vessel, <code>false</code> otherwise. Currently equivalent to <code>[[Oolite JavaScript Reference: Entity#scanClass|scanClass]] == "CLASS_POLICE"</code>.<br />
<br />
=== <code>isRock</code> ===<br />
'''isRock''' : Boolean (read-only)<br />
<code>true</code> if the ship is a rock (i.e., has scan_class: CLASS_ROCK)<br />
<br />
=== <code>isThargoid</code> ===<br />
'''isThargoid''' : Boolean (read-only)<br />
<code>true</code> if the ship is a Thargoid vessel, <code>false</code> otherwise. Currently equivalent to <code>[[Oolite JavaScript Reference: Entity#scanClass|scanClass]] == "CLASS_THARGOID"</code>.<br />
<br />
=== <code>isTrader</code> ===<br />
'''isTrader''' : Boolean (read-only)<br />
<code>true</code> if the ship is a merchant vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "trader" || isPlayer</code>. '''Note:''' <code>[[#isPirateVictim|isPirateVictim]]</code> may be a better choice in many cases.<br />
<br />
=== <code>isTurret</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isTurret''' : Boolean (read-only)<br />
<code>true</code> if the ship is a plasma turret sub-entity, <code>false</code> otherwise.<br />
<br />
=== <code>isWeapon</code> ===<br />
'''isWeapon''' : Boolean (read-only)<br />
<code>true</code> if the ship is a weapon, <code>false</code> otherwise. Currently equivalent to <code>[[#isMissile|isMissile]] || [[#isMine|isMine]] </code>, but new categories of weapon could be added in future.<br />
<br />
=== <code>laserHeatLevel</code>* ===<br />
{{Oolite-prop-added|1.77}}<br />
'''laserHeatLevel''' : Number (read-only, 0 to 1)<br />
The temperature of the ship's currently active weapon. Thermal cut-out is active above 0.85. For non-player ships, if their forward weapon is empty, then the temperature of the forward weapon may be the temperature of a subentity forward weapon.<br />
'''laserHeatLevelAft''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelForward''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelPort''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelStarboard''' : Number (read-only, 0 to 1)<br />
The temperature of specific laser mounts can also be queried.<br />
<br />
=== <code>lightsActive</code> ===<br />
'''lightsActive''' : Boolean (read-write)<br />
Setting this property to <code>true</code> turns on all the entity’s flashers, and setting it to <code>false</code> turns them off. Setting it sets the <code>lightsActive</code> property for all subentities, but subentities’ setting can also be manipulated separately. In addition to affecting flashers, the value can be used by shaders.<br />
<br />
Note: <code>lightsActive</code> is always <code>true</code> when a ship is spawned, although individual flashers may be off because they have <code>initially_on</code> set to false in their ''shipdata.plist'' declarations.<br />
<br />
=== <code>markedForFines</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''markedForFines''' : Boolean (read-only)<br />
<code>True</code> if the ship has been marked for fines the next time it docks at this system's main station.<br />
<br />
'''See also''' : [[#markTargetForFines|markTargetForFines()]]<br />
<br />
=== <code>maxEscorts</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxEscorts''' : Number (read/write)<br />
The maximum number of escorts this ship can have. This cannot be set lower than the number of escorts it currently has, or higher than the value of the MAX_ESCORTS constant (currently 16). There may be other reasons why a ship can have fewer escorts than the value of <code>maxEscorts</code> (for instance, ships which are escorts cannot have their own escorts)<br />
<br />
'''See also:''' <code>[[#escortGroup|escortGroup]]</code><br />
<br />
=== <code>maxPitch</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxPitch''' : Number (read-only, read/write from 1.81)<br />
The maximum pitch rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#pitch|pitch]]</code><br />
<br />
=== <code>maxRoll</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxRoll''' : Number (read-only, read/write from 1.81)<br />
The maximum roll rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#roll|roll]]</code><br />
<br />
=== <code>maxSpeed</code> ===<br />
'''maxSpeed''' : Number (read-only, read/write from 1.81)<br />
The ship’s maximum speed under normal power. Note that <code>[[#speed|speed]]</code> may exceed this when [[witch fuel injectors]] or [[hyperspeed]] are in use.<br />
<br />
'''See also:''' <code>[[#speed|speed]]</code><br />
<br />
=== <code>maxThrust</code> ===<br />
'''maxThrust''' : Number (read-only, read/write from 1.81)<br />
The ship’s maximum <code>[[#thrust|thrust]]</code>. This value is the one defined as <code>thrust</code> in ''[[Shipdata.plist#thrust|shipdata.plist]]''.<br />
<br />
=== <code>maxYaw</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxYaw''' : Number (read-only, read/write from 1.81)<br />
The maximum yaw rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#yaw|yaw]]</code><br />
<br />
=== <code>missileCapacity</code> ===<br />
'''missileCapacity''' : Number (read-only integer)<br />
The maximum number of missiles the ship can carry.<br />
<br />
=== <code>missileLoadTime</code> ===<br />
'''missileLoadTime''' : Number (read-write nonnegative)<br />
The minimum amount of time between two missiles. The corresponding ''[[shipdata.plist]]'' key is <code>missile_load_time</code>.<br />
<br />
=== <code>missiles</code> ===<br />
'''missiles''' : Array (read-only array of [[Oolite JavaScript Reference: EquipmentInfo|EquipmentInfo]])<br />
The ship’s loaded missiles.<br />
<br />
=== <code>name</code> ===<br />
'''name''' : String (read/write, read-only for player)<br />
The name of the ship type (<code>name</code> key in [[shipdata.plist]]).<br />
<br />
''Note'': while <code>name</code> can be changed, this is discouraged (and will probably not be supported in Oolite 2.0). Use <code>[[#displayName|displayName]]</code> instead.<br />
<br />
=== <code>parcelCount</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''parcelCount''' : Number (read-only integer)<br />
The ship’s current number of parcels.<br />
<br />
=== <code>parcels</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''parcels''' : Array (read-only NSDictionary)<br />
The ship’s parcels. (For now only available for the player). Each parcel list contains the entries: <code>name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
For example, the information of the first contract can be obtained by:<br />
player.ship.parcels[0].name<br />
player.ship.parcels[0].start<br />
player.ship.parcels[0].destination<br />
player.ship.parcels[0].startName<br />
player.ship.parcels[0].destinationName<br />
player.ship.parcels[0].eta<br />
player.ship.parcels[0].etaDescription<br />
player.ship.parcels[0].fee // The final fee, paid out on successful delivery.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this parcel.<br />
<br />
=== <code>passengerCapacity</code> ===<br />
'''passengerCapacity''' : Number (read-only integer)<br />
The ship’s maximum passenger capacity.<br />
<br />
=== <code>passengerCount</code> ===<br />
'''passengerCount''' : Number (read-only integer)<br />
The ship’s current number of passengers.<br />
<br />
=== <code>passengers</code> ===<br />
'''passengers''' : Array (read-only NSDictionary)<br />
The ship’s passengers. (For now only available for the player). Each passengers list contains the entries: <code>name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
For example, the information of the first contract can be obtained by:<br />
player.ship.passengers[0].name<br />
player.ship.passengers[0].start<br />
player.ship.passengers[0].destination<br />
player.ship.passengers[0].startName<br />
player.ship.passengers[0].destinationName<br />
player.ship.passengers[0].eta<br />
player.ship.passengers[0].etaDescription<br />
player.ship.passengers[0].fee // The final fee, paid out on successful delivery.<br />
player.ship.passengers[0].premium // The advance fee, already paid on acceptance of the contract.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this passenger, and premium shows the amount the player received when the passenger boarded the ship.<br />
<br />
=== <code>pitch</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''pitch''' : Number (read-only)<br />
The rate of pitch of the ship in radians/second (positive for dive, negative for climb)<br />
<br />
=== <code>portWeapon</code> ===<br />
'''portWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped port weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>potentialCollider</code> ===<br />
'''potentialCollider''' : [[Oolite JavaScript Reference: Entity|Entity]] (read-only)<br />
The entity the ship is currently trying not to crash into, if any.<br />
<br />
=== <code>primaryRole</code> ===<br />
'''primaryRole''' : String (read/write, read-only for player)<br />
The main role of the ship; the role for which it was created. For instance, if a ship’s ''shipdata.plist'' entry specifies the roles “pirate trader(0.5) escort”, and a ship of that type is spawned to be a trader, its <code>primaryRole</code> is <code>"trader"</code>, its <code>roles</code> is <code>["escort", "pirate", "trader"]</code> and its <code>roleWeights</code> is <code> { "escort":1, "pirate":1, "trader":0.5}</code>.<br />
<br />
'''See also:''' <code>[[#roles|roles]]</code>, <code>[[#roleWeights|roleWeights]]</code><br />
<br />
=== <code>reportAIMessages</code> ===<br />
'''reportAIMessages''' : Boolean (read/write)<br />
Debugging facility: set to <code>true</code> to dump information about AI activity to the log. <br />
<br />
=== <code>roleWeights</code> ===<br />
'''roleWeights''' : Object (read-only)<br />
The probabilities for each role in <code>[[#roles|roles]]</code>.<br />
<br />
Example:<br />
this.pirateProb = ship.roleWeights["pirate"]<br />
<br />
'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roles|roles]]</code><br />
<br />
=== <code>roles</code> ===<br />
'''roles''' : Array (read-only array of Strings)<br />
The roles of the ship. This consists of the roles specified in the ship’s ''shipdata.plist'' entry, as well as the <code>[[#primaryRole|primaryRole]]</code> if it is not among those.<br />
<br />
'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roleWeights|roleWeights]]</code>, <code>[[#hasRole|hasRole()]]</code><br />
<br />
=== <code>roll</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''roll''' : Number (read-only, read/write for stations)<br />
The rate of roll of the ship in radians/second (positive for anti-clockwise, negative for clockwise)<br />
<br />
For stations, this can be set to any value between -2 and +2 to adjust their roll rate. The default is 0.4, or the value specified by the <code>station_roll</code> key in shipdata.plist.<br />
<br />
=== <code>savedCoordinates</code> ===<br />
'''savedCoordinates''' : [[Oolite JavaScript Reference: Vector|Vector]] (read-write)<br />
The savedCoordinates of the ship in system co-ordinates. The savedCoordinates vector is only used by AI scripting to store a coordinate that can be used by other AI commands like <code>setDestinationFromCoordinates</code>. It are the same coordinates that are set by the AI command: <code>"setCoordinates: X Y Z"</code><br />
<br />
=== <code>scanDescription</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''scanDescription''' : String (read/write)<br />
The description of the ship in the "legal status" text shown by the [[Scanner Targeting Enhancement]]. If this is null then the default text for the ship's scan class and bounty level will be shown.<br />
<br />
=== <code>scannerDisplayColor1</code> ===<br />
'''scannerDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The first of two colours used by the ship’s scanner “lollipop”. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning <code>null</code> will restore the value from [[shipdata.plist]], or the default value for the ship’s scan class.<br />
<br />
'''See also:''' <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code>, <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code><br />
<br />
=== <code>scannerDisplayColor2</code> ===<br />
'''scannerDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The second scanner colour. If both <code>scannerDisplayColor1</code> and <code>scannerDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.<br />
<br />
'''See also:''' <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code>, <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code><br />
<br />
=== <code>scannerHostileDisplayColor1</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''scannerHostileDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The first of two colours used by the ship’s scanner “lollipop” when the ship is specifically targeting the player with hostile intent. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning <code>null</code> will restore the value from [[shipdata.plist]], or the default value for the ship’s scan class.<br />
<br />
If hostile colours are set but normal colours aren't, then the normal colours will default to those for the ship's scan class. If normal colours are set but hostile colours aren't, the scanner blip will not change colour when the ship is hostile.<br />
<br />
'''See also:''' <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code>, <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code><br />
<br />
=== <code>scannerHostileDisplayColor2</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''scannerHostileDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The second scanner colour when the ship is specifically targeting the player with hostile intent.. If both <code>scannerHostileDisplayColor1</code> and <code>scannerHostileDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.<br />
<br />
'''See also:''' <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code>, <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code><br />
<br />
=== <code>scannerRange</code> ===<br />
'''scannerRange''' : Number (read-only)<br />
The range of the ship’s scanner.<br />
<br />
=== <code>script</code> ===<br />
'''script''' : [[Oolite JavaScript Reference: Script|Script]] (read-only)<br />
The ship’s script.<br />
<br />
=== <code>scriptedMisjump</code> ===<br />
'''scriptedMisjump''' : Boolean (read/write)<br />
When <code>true</code>, the next hyperspace jump will be a misjump. The <code>scriptedMisjump</code> flag will remain <code>true</code> during the <code>shipWillExitWitchspace()</code> event handler, and will be set to <code>false</code> after the <code>shipExitedWitchspace()</code> event.<br />
<br />
=== <code>scriptedMisjumpRange</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''scriptedMisjumpRange''' : Number (read/write)<br />
If this ship misjumps, this number will be consulted to determine the length of the resulting misjump relative to the normal jump range. Setting this does not in itself force a misjump - this must occur through the usual mechanisms. Values must be greater than 0.0 and less than 1.0, and the default is 0.5 for a traditional half-way misjump. This will be reset to 0.5 at the same time as <code>[[#scriptedMisjump|scriptedMisjump]]</code> is reset to <code>false</code>.<br />
<br />
=== <code>scriptInfo</code> ===<br />
'''scriptInfo''' : Object (read-only)<br />
The contents of the <code>script_info</code> key in the ship’s ''[[shipdata.plist]]'' entry, if any. This may be any [[property list]] object, but the recommended approach is to use a dictionary whose keys have a unique prefix (such as you should be using for file names, ship names etc.). A property list dictionary is converted to a JavaScript object with properties corresponding to the dictionary’s keys. All other property list types used with Oolite have directly corresponding JavaScript types.<br><br />
When using numeric values in the scriptInfo, the JS engine is not able to detect the type reliably on all systems, so you always must explicitly convert its content to a number by using parseInt(scriptInfo.myKey) or parseFloat(scriptInfo.myKey).<br />
<br />
=== <code>shipClassName</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''shipClassName''' : String (read/write)<br />
The name of the ship class (e.g. "Python")<br />
<br />
=== <code>shipUniqueName</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''shipUniqueName''' : String (read/write)<br />
The name of this specific ship (e.g. "Sunrise of Lave")<br />
<br />
=== <code>speed</code> ===<br />
'''speed''' : Number (read-only)<br />
The ship’s current speed.<br />
<br />
'''See also:''' <code>[[#maxSpeed|maxSpeed]]</code><br />
<br />
=== <code>starboardWeapon</code> ===<br />
'''starboardWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped forward weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code><br />
<br />
=== <code>subEntities</code> ===<br />
'''subEntities''' : Array (read-only array of Ships)<br />
The ships subentities, or <code>null</code> if it has none. Special subentities such as flashers and exhaust plumes are not included.<br />
<br />
'''See also:''' <code>[[#isFrangible|isFrangible]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>subEntityCapacity</code> ===<br />
'''subEntityCapacity''' : Number (read-only integer)<br />
The original number of subentities on the ship. <br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>subEntityRotation</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''subEntityRotation''' : Quaternion (read/write)<br />
The subentity rotational velocity, expressed as a quaternion. This much rotation will be applied per second. Exact 180 degree rotations should not be specified, as it is not possible to determine what route to use to make that rotation. This property is ignored when set on non-subentities.<br />
<br />
=== <code>sunGlareFilter</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''sunGlareFilter''' : Number (read/write)<br />
The strength of the sun glare filter on this ship. It must be in the range 0 to 1 (0 is no filter).<br />
<br />
=== <code>target</code> ===<br />
'''target''' : Ship (read-write)<br />
The ship’s primary target, i.e. the entity it will attempt to shoot at. This value is automatically co-ordinated between a ship and its subentities.<br />
<br />
=== <code>temperature</code> ===<br />
'''temperature''' : Number (read/write)<br />
The ship’s temperature, normalized such that a temperature of 1.0 is the level at which a ship starts taking heat damage.<br />
<br />
=== <code>thrust</code> ===<br />
'''thrust''' : Number (read/write for NPCs, read-only for player before 1.81)<br />
The ship’s thrust, ranging from 0 to <code>maxThrust</code>. This value determines how fast the ship accelerates or decelerates, specified in m/s².<br />
<br />
'''See also:''' <code>[[#thrustVector|thrustVector]]</code><br />
<br />
=== <code>thrustVector</code> ===<br />
'''thrustVector''' : Vector3D (read-only)<br />
The inertialess velocity generated by the engines.<br />
<br />
'''See also:''' <code>[[#thrust|thrust]]</code>, <code>[[#velocity|velocity]]</code><br />
<br />
=== <code>trackCloseContacts</code> ===<br />
'''trackCloseContacts''' : Boolean (read/write)<br />
If true, AI events are generated for near collisions.<br />
<br />
=== <code>vectorForward</code> ===<br />
'''vectorForward''' : Vector3D (read-only)<br />
The vector pointing forwards from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorForward|vectorForward]]</code>.<br />
<br />
=== <code>vectorRight</code> ===<br />
'''vectorRight''' : Vector3D (read-only)<br />
The vector pointing right from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorRight|vectorRight]]</code>.<br />
<br />
=== <code>vectorUp</code> ===<br />
'''vectorUp''' : Vector3D (read-only)<br />
The vector pointing up from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorUp|vectorUp]]</code>.<br />
<br />
=== <code>velocity</code> ===<br />
'''velocity''' : Vector3D (read/write)<br />
The ship’s velocity.<br />
<br />
'''Note:''' A ship’s velocity consists of two components, inertial velocity and inertialess thrust. Generally, inertial velocity is zero (so <code>velocity</code> is equal to <code>[[#thrustVector|thrustVector]]</code>), but inertial impulses may be applied if a ship collides or is caught in an explosion. If inertial velocity is non-zero, the ship’s engines will work to counteract it. Changing the ship’s velocity will always apply inertial velocity, so for ships with non-zero <code>[[#maxThrust|maxThrust]]</code> the effect will be temporary.<br />
<br />
'''See also:''' <code>[[#thrustVector|thrustVector]]</code><br />
<br />
=== <code>weaponFacings</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''weaponFacings''' : Number (read-only, integer in range 0-15)<br />
The weapon facings available for the ship. The format is the same as the equivalent property in [[shipyard.plist]] or [[shipdata.plist]] - a bitmask with the following bits:<br><br />
1 - fore<br><br />
2 - aft<br><br />
4 - port<br><br />
8 - starboard<br />
<br />
=== <code>weaponPosition*</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''weaponPositionAft''' : Vector (read-only)<br />
'''weaponPositionForward''' : Vector (read-only)<br />
'''weaponPositionPort''' : Vector (read-only)<br />
'''weaponPositionStarboard''' : Vector (read-only)<br />
The position relative to the ship at which the appropriate laser beam will start. These properties do not imply that the ship has or can have any such weapon.<br />
<br />
=== <code>weaponRange</code> ===<br />
'''weaponRange''' : Number (read-only)<br />
The maximum range of the ship’s primary weapon. For the player it is the range of the weapon that fired as last, even when the view direction changed.<br><br />
Range values are: WEAPON_PLASMA_CANNON: 5000, WEAPON_PULSE_LASER: 12500, WEAPON_BEAM_LASER: 15000, WEAPON_MINING_LASER: 12500, WEAPON_THARGOID_LASER: 17500, WEAPON_MILITARY_LASER: 30000, WEAPON_NONE: 32000.<br><br />
(Turrets are secondary weapons with a maximum range of 6000)<br />
<br />
=== <code>withinStationAegis</code> ===<br />
'''withinStationAegis''' : Boolean (read-only)<br />
<code>true</code> if the ship is within the aegis of the system’s main station (i.e., no more than 51 200 game metres from the station, or twice scanner range).<br />
<br />
=== <code>yaw</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''yaw''' : Number (read-only)<br />
The rate of yaw of the ship in radians/second (positive for right, negative for left)<br />
<br />
== Methods ==<br />
=== <code>abandonShip</code> ===<br />
function '''abandonShip'''() : Boolean<br />
Returns <code>true</code> when the ship has an escapepod. It will launch all escapeposd on board leaving the ship behind as a empty hulk. (scanClass = CLASS_CARGO). This command does nothing when no escape-pod is present.<br><br />
Pressence of an escapepod can be tested with: <code>equipmentStatus("EQ_ESCAPE_POD") == "EQUIPMENT_OK"</code><br />
<br />
=== <code>addCollisionException</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''addCollisionException'''(exception : Ship)<br />
Prevented this ship and the selected ship from colliding. See [[#collisionExceptions|collisionExceptions]] and [[#removeCollisionException|removeCollisionException]].<br />
<br />
Prevention from collision will specifically prevent the following:<br />
<br />
* the ships colliding with each other and suffering collision damage and/or momentum change<br />
* the ships receiving collision warning events if they come close to each other<br />
* if one of the ships is a station, the other ship will not be able to dock with it even if it enters a dock<br />
<br />
This has no useful effect when applied to a subentity.<br />
<br />
Adding a collision exception which already exists has no effect but will not cause an error.<br />
<br />
=== <code>addDefenseTarget</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''addDefenseTarget'''(target : Ship)<br />
Adds the target ship to this ship's list of point [[#defenseTargets|defense targets]], if it isn't already.<br />
<br />
=== <code>adjustCargo</code>===<br />
{{oolite-method-added|1.81}}<br />
function '''adjustCargo'''(commodity : String, amount : Number) : Boolean<br />
Adjust the quantity of the specified commodity carried by the ship. Amount may be negative to remove cargo. The method will return false if the operation would fail due to insufficient free space or carried cargo, and will not make a partial adjustment in this case.<br />
<br />
=== <code>awardEquipment</code> ===<br />
function '''awardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Adds the given piece of equipment to the ship, if possible, returning <code>true</code> if successful and <code>false</code> otherwise.<br />
<br />
Example:<br />
ship.awardEquipment("EQ_ECM");<br />
<br />
'''See also:''' <code>[[#canAwardEquipment|canAwardEquipment()]]</code>, <code>[[#removeEquipment|removeEquipment()]]</code><br />
<br />
=== <code>canAwardEquipment</code> ===<br />
function '''canAwardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Tests whether it is possible to add a given equipment type. This command takes the conditions for offering inside equipment.plist into account. Returns <code>true</code> if <code>[[#awardEquipment|awardEquipment()]]</code> is expected to succeed, <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#awardEquipment|awardEquipment()]]</code><br />
<br />
=== <code>becomeCascadeExplosion</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''becomeCascadeExplosion'''()<br />
This method causes the ship to explode as if it were hit by a quirium cascade.<br />
<br />
=== <code>broadcastCascadeImminent</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''broadcastCascadeImminent'''()<br />
This method causes the ship to broadcast a message to the AIs of all nearby ships warning them of an imminent cascade explosion. It is polite to call this a few seconds before calling <code>becomeCascadeExplosion</code><br />
<br />
=== <code>broadcastDistressMessage</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''broadcastDistressMessage'''()<br />
This method causes the ship to broadcast a distress message to the AIs of all nearby ships (received also by the player as a comms message). Ships receiving a distress message will often intervene in the fight, depending on their own AI and the roles of the ships already involved.<br />
<br />
=== <code>checkCourseToDestination</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''checkCourseToDestination'''()<br />
Checks the line between the ship's current position and its destination, and returns either null or an Entity (usually a planet, sun or other ship) that this ship would risk collision with if it travelled along that course.<br />
<br />
'''See also''': [[#getSafeCourseToDestination|getSafeCourseToDestination()]]<br />
<br />
=== <code>checkScanner</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''checkScanner'''([poweredOnly : Boolean]) : Array<br />
Runs a fast scanner check and returns the results. At most 32 objects within scanner range will be returned. If the <code>poweredOnly</code> parameter is present and set to true, then only powered objects will be returned (i.e. ships with a scan class other than CLASS_CARGO or CLASS_ROCK).<br />
<br />
This method is usually considerably quicker than [[Oolite_JavaScript_Reference:_System#filteredEntities|system.filteredEntities()]] and similar methods, with little loss of accuracy, though it is still advisable to cache the result for a while before re-scanning.<br />
<br />
=== <code>clearDefenseTargets</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''clearDefenseTargets'''()<br />
Clears the ship's list of point [[#defenseTargets|defense targets]].<br />
<br />
=== <code>commsMessage</code> ===<br />
function '''commsMessage'''(message : String [,target : Ship])<br />
Make the ship broadcast the specified message. Works on buoys and subentities as well as normal ships and stations. Messages are send to a maximum of 16 ships in range and always to the player when in range. When the optional target is used, the message goes only to that ship.<br />
<br />
=== <code>damageAssessment</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''damageAssessment'''() : Number<br />
Returns a number indicating the amount of damage or supply usage by this ship. Zero means that the ship is in excellent fighting condition, while higher numbers indicate increasing amounts of damage or supply shortages.<br />
<br />
=== <code>dealEnergyDamage</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''dealEnergyDamage'''(damage : Number, idealRange : Number [, velocityBias : Number])<br />
Deals damage to all ships within a sphere centred on this ship. If this ship has an owner (e.g. it is a missile or a subentity) the damage will be credited to its owner. Damage is dealt according to the following formula:<br />
* Further away than MAX_SCANNER_RANGE (25.6km): deal no damage<br />
* At or closer than <code>idealRange</code>: deal <code>damage</code> plus (or minus, for receding objects) <code>velocityBias</code> damage for every 0.001LM of relative closing speed, up to a maximum of 1.0LM<br />
* Between <code>idealRange</code> and a derived maximum range: calculate the damage that would have been done at <code>idealRange</code>, and then divide it by the square of the ratio of <code>idealRange</code> and the real range (i.e inverse-square). The derived maximum range is the distance where a target with no relative closing speed would take 1 point of damage.<br />
<br />
As an example, the standard Oolite missile uses <code>dealEnergyDamage(170, 32.5, 0.25)</code>, has a maximum speed of 0.75LM, and its AI tries to detonate it 25m from its target. Some worked examples (for comparision, one energy bank can absorb 64 points of damage, and a standard shield generator can absorb 128 points of damage):<br />
* The missile is fired at a stationary asteroid. It detonates at 25m, within the ideal range, and the relative closing speed is 0.75LM. The asteroid takes 170 + (0.25 * 750) = 357.5 points of damage<br />
* The missile is fired at a Cobra Mk III, which tries to flee from and evade the missile at its top speed of 0.35LM. The missile detonates at 25m, and the evasive manoeuvres mean that it is not heading directly at the Cobra when it detonates. The relative closing speed is 0.38LM. The Cobra takes 170 + (0.25 * 380) = 265 points of damage.<br />
* An Anaconda freighter travelling at 0.2LM fires a missile at a distant Fer-de-lance. After the missile has travelled 150m away from the Anaconda, it is hit by an ECM pulse from the FDL, and detonates. The relative velocity is -0.55LM (the missile is travelling away from the Anaconda), so the damage at the ideal range would be 170 - (0.25 * 550) = 32.5. The damage is then divided by (150 / 32.5)<sup>2</sup>, so the Anaconda takes about 1.5 points of damage.<br />
* A missile fired at something else detonates 500m away from a Sidewinder. The inverse-square rule divides the damage by (500 / 32.5)<sup>2</sup>, so the base damage at this range (ignoring velocityBias) is only 0.7. The Sidewinder is therefore safely outside the blast radius, and is not considered for damage. <br />
<br />
=== <code>deployEscorts</code> ===<br />
function '''deployEscorts'''()<br />
Cause a random number (at least 1 if possible) of the ship's escorts which are not already attacking a target to attack this ship's primary target, unless this function has already been called for the current target without meanwhile being called for a different target.<br />
<br />
=== <code>dockEscorts</code> ===<br />
function '''dockEscorts'''()<br />
Dock the ship’s deployed escorts, if any.<br />
<br />
=== <code>dumpCargo</code> ===<br />
function '''dumpCargo'''([amount : Number, commodity: String]) : Ship<br />
Ejects one item of cargo from the ship, and returns the cargo item. Returns <code>null</code> if the ship has no cargo, anything has been ejected in the last 0.5 seconds, or if sent to the player while docked.<br />
<br />
In 1.79 or later, multiple items may be scheduled for dumping by passing the number as a parameter.<br />
<br />
In 1.81 or later, a preferred commodity may be specified (if this is not present, a random item will be dumped as usual). This preference only applies to the first item dropped, not subsequent ones.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code><br />
<br />
=== <code>ejectItem</code> ===<br />
function '''ejectItem'''(role : String) : Ship<br />
Spawns a ship of role <code>role</code> immediately behind the ship, with a slight backwards velocity. (Note: an equal and opposite reaction is applied to the parent ship, so doing this with large ships is rarely useful. <code>player.ejectItem("station")</code> may seem funny, but don’t come running to me if you have someone’s eye out.) Returns the generated ship, or <code>null</code> if no ship is generated. The scanClass of the ejected item will always be CLASS_CARGO.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code><br />
<br />
=== <code>ejectSpecificItem</code> ===<br />
function '''ejectSpecificItem'''(itemKey : String) : Ship<br />
Spawns a ship with the ''shipdata.plist'' key <code>itemKey</code> immediately behind the ship, with a slight backwards velocity. The scanClass of the ejected item will always be CLASS_CARGO.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectItem|ejectItem]]</code><br />
<br />
=== <code>enterWormhole</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''enterWormhole'''([wormhole : Wormhole])<br />
If the player has entered witchspace, but before the old system is removed from memory, this method may be used to add this ship to the contents of the specified outbound wormhole. If no parameter is given, add them to the player's wormhole.<br />
<br />
If the player is not entering witchspace, this method does nothing: the ship must fly to the wormhole in the normal way to enter it.<br />
<br />
=== <code>equipmentStatus</code> ===<br />
function '''equipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : String<br />
Tests whether the specified type of equipment is installed, and whether it is functioning. Returns one of the following strings: <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>, <code>"EQUIPMENT_UNAVAILABLE"</code> or <code>"EQUIPMENT_UNKNOWN"</code>.<br />
<br />
'''See also:''' <code>[[#setEquipmentStatus|setEquipmentStatus()]]</code><br />
<br />
=== <code>exitAI</code> ===<br />
function '''exitAI'''()<br />
Exit the current AI, restoring the previous one. Equivalent to the <code>[[AI_methods|exitAI]]:</code> AI method. May not be used on player. Will generate a warning if there are no suspended AI states.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code><br />
<br />
=== <code>exitSystem</code> ===<br />
function '''exitSystem'''([targetSystem : Number]) : Boolean<br />
Cause the ship to jump out of the system, if possible. If <code>targetSystem</code> is specified, it will attempt to jump to the specified system, otherwise a random system within range is chosen.<br />
<br />
This method can fail for various reasons, in which case it returns <code>false</code>. It always fails for the player ship.<br />
<br />
=== <code>explode</code> ===<br />
function '''explode'''()<br />
Causes the ship to explode. Works on all ships, including the main station and the player except when docked.<br />
<br />
'''See also:''' <code>[[#remove|remove()]]</code><br />
<br />
=== <code>fireECM</code> ===<br />
function '''fireECM'''()<br />
activates an ecm burst, identical as the AI command.<br />
<br />
=== <code>findNearestStation</code> ===<br />
function '''findNearestStation'''()<br />
Returns the nearest Station entity to this ship. This is quicker than manually searching <code>system.stations</code> and much quicker than using <code>system.filteredEntities()</code>.<br />
<br />
=== <code>fireMissile</code> ===<br />
function '''fireMissile'''([missile]) : Ship<br />
fireMissile() will try to fire the first available missile and will return the missile fired, or <code>null</code> if no missiles can be fired at this time. It can take the optional missile identifier parameter, to allow for a specific missile to be fired. Missiles cannot be fired if the ship hasn’t got a valid target, or if the previous missile was launched less than <code>missile_load_time</code> seconds before. If a missile type was specified, and not found on the ship, no missile will be fired.<br />
<br />
=== <code>getSafeCourseToDestination</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''getSafeCourseToDestination'''()<br />
Returns some coordinates which can be flown to as an intermediate destination to allow travel between the ship's current position and its destination without colliding with any objects on the way. Use this if <code>checkCourseToDestination</code> returns an object you are unable or unwilling to destroy to calculate a new route.<br />
<br />
'''See also''': [[#checkCourseToDestination|checkCourseToDestination()]]<br />
<br />
=== <code>getMaterials</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''getMaterials'''() : Object<br />
getMaterials() returns the ship's current materials dictionary, or if none present an empty dictionary.<br />
<br />
'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code><br />
<br />
=== <code>getShaders</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''getShaders'''() : Object<br />
getShaders() returns the ship's current shaders dictionary, or if none present an empty dictionary.<br />
<br />
'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code><br />
<br />
=== <code>hasEquipmentProviding</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''hasEquipmentProviding'''(key : String)<br />
This method returns <code>true</code> if the ship has any equipment providing the <code>key</code> equipment type, and <code>false</code> otherwise.<br />
<br />
=== <code>hasRole</code> ===<br />
function '''hasRole'''(role : String)<br />
Returns <code>true</code> if the ship has <code>role</code> among its roles, <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#roles|roles]]</code><br />
<br />
=== <code>markTargetForFines</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''markTargetForFines()'''<br />
If this ship is eligible to give out fines and the primary target has a bounty, mark the current primary target for fines, which will need to be paid when the ship docks. If used on a ship other than the player, of course, the fines are not particularly meaningful.<br />
<br />
=== <code>notifyGroupOfWormhole</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''notifyGroupOfWormhole()'''<br />
Tells the ship's group about a wormhole (usually the one this ship has just entered). Causes a <code>wormholeSuggested</code> event to occur in the scripts of other group members.<br />
<br />
=== <code>offerToEscort</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''offerToEscort(mother : Ship)'''<br />
Offer to escort the specified ship. The ship making the offer must have the same scan class as the mothership and must have one of the designated escort roles. After the mothership has made a decision this ship will receive either an <code>escortAccepted</code> or <code>escortRejected</code> ship script event.<br />
<br />
=== <code>perform*</code> ===<br />
Each of these functions switches the frame-by-frame behaviour of the ship to a different mode. It may not necessarily remain in that mode, however - for example, those modes which require a target will usually fall back to idle mode if the target is lost.<br />
<br />
==== <code>performAttack</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performAttack()'''<br />
Attack the current target with available weapons.<br />
<br />
==== <code>performCollect</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performCollect()'''<br />
Attempt to scoop up the current target. If the current target is not scoopable, it will be lost.<br />
<br />
==== <code>performEscort</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performEscort()'''<br />
Escort the group leader. If this ship is not an escort of the group leader, it will not receive escort position updates from that ship.<br />
<br />
==== <code>performFaceDestination</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFaceDestination()'''<br />
Come to a stop, and turn to face the current destination coordinates.<br />
<br />
==== <code>performFlee</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFlee()'''<br />
Flee from the current target, using injectors if possible, until it is out of scanner range.<br />
<br />
==== <code>performFlyToRangeFromDestination</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFlyToRangeFromDestination()'''<br />
Fly to the current [[#destination|destination]] coordinates, stopping when the distance between the ship and those coordinates is the [[#desiredRange|desiredRange]]. If the ship is already closer to the destination coordinates than the desired range, it will move away from the coordinates.<br />
<br />
==== <code>performHold</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performHold()'''<br />
Come to a stop, and continually turn to face the current target<br />
<br />
==== <code>performIdle</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performIdle()'''<br />
Cancel any current turns to return to level flight, then move forward at current speed.<br />
<br />
==== <code>performIntercept</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performIntercept()'''<br />
Fly to intercept (i.e. ram) the current target.<br />
<br />
==== <code>performLandOnPlanet</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performLandOnPlanet()'''<br />
Land on rather than crash into the planet. This is a slow flight, so it is recommended to get close to the planet surface before activating this behaviour.<br />
<br />
==== <code>performMining</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performMining()'''<br />
Attack the current target with a mining laser. This does not count as hostile behaviour, so cannot be used except on rocks.<br />
<br />
==== <code>performScriptedAI</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performScriptedAI()'''<br />
Request flight instructions from a [[OXP_Scripted_AI|scripted AI]] callback each frame.<br />
<br />
==== <code>performScriptedAttackAI</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performScriptedAttackAI()'''<br />
Request flight instructions, including weapons fire, from a [[OXP_Scripted_AI|scripted AI]] callback each frame.<br />
<br />
==== <code>performStop</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performStop()'''<br />
Come to a complete halt<br />
<br />
==== <code>performTumble</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performTumble()'''<br />
Come to a complete halt and rotate randomly.<br />
<br />
=== <code>reactToAIMessage</code> ===<br />
function '''reactToAIMessage'''(message : String)<br />
Immediately perform the specified handler in the ship’s current AI state.<br />
<br />
'''See also:''' <code>[[#sendAIMessage|sendAIMessage()]]</code><br />
<br />
=== <code>recallDockingInstructions</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''recallDockingInstructions'''() : Object<br />
Returns the current docking instructions as an object, and sets the destination, desired range and desired speed to match the instructions. Use this if the ship may have been interrupted while docking to ensure its flight parameters are set correctly.<br />
<br />
'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#requestDockingInstructions|requestDockingInstructions]]</code><br />
<br />
=== <code>remove</code> ===<br />
function '''remove'''([suppressDeathEvent : Boolean])<br />
Immediately removes the ship from the universe. Works on all ships except the player, including the main station.<br>It generates a [[Oolite JavaScript Reference: ship script event handlers#shipRemoved|this.shipRemoved(suppressDeathEvent)]] event. By default it will also trigger a [[Oolite JavaScript Reference: ship script event handlers#shipDied|this.shipDied()]] event, unless <code>suppressDeathEvent</code> is true.<br />
<br />
'''See also:''' <code>[[#explode|explode()]]</code><br />
<br />
=== <code>removeCollisionException</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''removeCollisionException'''(exception : Ship)<br />
Allow this ship and the selected ship to collide again. See [[#collisionExceptions|collisionExceptions]] and [[#addCollisionException|addCollisionException]].<br />
<br />
Removing a collision exception which does not exist has no effect but will not cause an error.<br />
<br />
=== <code>removeDefenseTarget</code>===<br />
{{oolite-method-added|1.79}}<br />
function '''removeDefenseTarget'''(target : Ship)<br />
Ensures that the target ship is not on this ship's list of point [[#defenseTargets|defense targets]].<br />
<br />
=== <code>removeEquipment</code> ===<br />
function '''removeEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]])<br />
Removes the given piece of equipment from the ship.<br />
This function can also be used to remove missiles (and mines). If more than one missile of the same type is found on board, only one of them will be removed.<br />
<br />
Note that in Oolite prior to 1.76.1 there was a bug which could sometimes cause the game to crash if this function was used on pylon-mounted equipment. Therefore, if you do this in your OXP, you should set (at least) 1.76.1 as the version in requires.plist<br />
<br />
Example:<br />
ship.removeEquipment("EQ_ECM");<br />
<br />
=== <code>requestDockingInstructions</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''requestDockingInstructions'''() : Object<br />
Requests the next docking instructions from the station, and returns them as an object, setting the destination, desired range and desired speed to match the instructions. Use this to get the next step in the docking sequence after completing the previous one.<br />
<br />
'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code><br />
<br />
<br />
=== <code>requestHelpFromGroup</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''requestHelpFromGroup'''()<br />
This function sends the <code>helpRequestReceived</code> event to the other ships in this ship's group and escort group, sending the name of this ship's current target as the aggressor.<br />
<br />
=== <code>restoreSubEntities</code> ===<br />
function '''restoreSubEntities'''() : Boolean<br />
Recreate all destroyed or removed subentities of the ship. Returns <code>true</code> if any subentities were added. Whether or not any subentities were added, this will also reset all subentities to their original configuration of position, orientation and other properties.<br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#isFrangible|isFrangible]]</code><br />
<br />
=== <code>selectNewMissile</code> ===<br />
function '''selectNewMissile'''() : equipmentKey<br />
selectNewMissile() will automatically select a missile for a specific ship. It uses the missile_role shipdata.plist key to find out which missiles to select. As with the system populator, there's a small chance that missiles other than the missile_role specified in shipdata will be selected.<br />
e.g.<br />
this.ship.awardEquipment(this.ship.selectNewMissile())<br />
will automatically add the 'right type' of missile to a ship, i.e. one that its captain would normally choose.<br />
<br />
=== <code>sendAIMessage</code> ===<br />
function '''sendAIMessage'''(message : String)<br />
Add a message to the ship’s AI deferred message queue. Messages in the queue are handled immediately after the next periodic <code>UPDATE</code> message. Identical messages are coalesced.<br />
<br />
'''See also:''' <code>[[#reactToAIMessage|reactToAIMessage()]]</code><br />
<br />
=== <code>setAI</code> ===<br />
function '''setAI'''(AIName : String)<br />
Set the current AI, leaving the old one suspended. Equivalent to the <code>[[AI_methods|setAITo]]:</code> AI method. May not be used on player. From 1.79 onwards AI files may either be plist-based (with a .plist extension) or Javascript-based (with a .js extension).<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code><br />
<br />
=== <code>setBounty</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''setBounty'''(bounty : Number, reason : String)<br />
Sets the ship's bounty to the new value. <code>reason</code> will be sent to [[Oolite_JavaScript_Reference:_ship_script_event_handlers#shipBountyChanged|shipBountyChanged()]].<br />
<br />
'''See also:''' <code>[[#bounty|bounty]]</code><br />
<br />
=== <code>setCargo</code> ===<br />
function '''setCargo'''(commodity : String [, count : Number]) : Boolean<br />
Attempts to create <code>count</code> weight units of the commodity <code>commodity</code> for a cargo barrel. (Can not be used to set cargo for ships) When more units are defined than 1 ton, the count is reduced to one ton. It returns false when the selected commodity is unknown. If <code>count</code> is not specified, one will be assumed.<br />
<br />
=== <code>setCargoType</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setCargoType'''(commodityType : String) : Boolean<br />
Attempts to set the ship's cargo hold to contain cargo of the specified type, discarding any cargo already present. This should generally only be used immediately after a ship is spawned. Valid cargo types are:<br />
* '''SCARCE_GOODS''': goods which are likely to be rare in the current system, usually legal.<br />
* '''PLENTIFUL_GOODS''': goods which are likely to be plentiful in the current system, usually legal.<br />
* '''MEDICAL_GOODS''': narcotics (used for the Moray Medical Boat)<br />
* '''ILLEGAL_GOODS''': various goods likely to be rare in the current system, with a strong bias towards contraband<br />
* '''PIRATE_GOODS''': as ILLEGAL_GOODS, but the total amount carried will be lower<br />
This will return false if an unrecognised commodity type is used, and will throw an exception if used on a cargo pod rather than a cargo carrier. Using it on a ship like an Asp without a cargo hold is valid but pointless.<br />
<br />
=== <code>setCrew</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setCrew'''(Object) : Boolean<br />
Sets the ship's crew to one represented by the given object (or sets the ship to uncrewed if null is given as a parameter). Returns true if this succeeds, false otherwise (if the ship is ''always'' unpiloted). The object has the same keys as [[characters.plist]], all of which are optional and will be replaced with default values if unset. They are applied in the following order:<br />
* origin system<br />
* random seed<br />
* role<br />
* the rest<br />
You can therefore set a random seed or role to get particular behaviour, and use the other keys to override it.<br />
<br />
At the moment this function only sets the first crew member (the pilot of the ship)<br />
<br />
=== <code>setEquipmentStatus</code> ===<br />
function '''setEquipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]], statusKey : String)<br />
Changes the status of the given piece of equipment from the ship. The two only valid status keys are <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>.<br />
<br />
'''Note:''' by design, this method will throw an exception if called with an equipment type that does not exist. To test whether an equipment type exists, use <code>[[Oolite JavaScript Reference: EquipmentInfo#infoForKey|EquipmentInfo.infoForKey()]]</code>, which will return <code>null</code> for undefined equipment.<br />
<br />
'''See also:''' <code>[[#equipmentStatus|equipmentStatus()]]</code><br />
<br />
=== <code>setMaterials</code> ===<br />
function '''setMaterials'''(materialDictionary : Object [, shaderDictionary : Object]) : Boolean<br />
Set the materials of the ship’s model. This works exactly like the <code>materials</code> dictionary in [[shipdata.plist]]. The optional <code>shaderDictionary</code> argument overrides <code>materialDictionary</code> if shaders are active.<br />
<br />
'''Example:'''<br />
this.ship.setMaterials({"my_ship_diffuse.png": { diffuse_map: "my_ship_damaged_diffuse.png" }});<br />
<br />
'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code><br />
<br />
=== <code>setScript</code> ===<br />
function '''setScript'''(scriptName : String)<br />
Set, or completely replace, the javascript code associated to a ship entity.<br />
<br />
=== <code>setShaders</code> ===<br />
function '''setShaders'''(shaderDictionary : Object) : Boolean<br />
Set the shader materials of the ship’s model. Equivalent to <code>[[#setMaterials|setMaterials()]]</code> with the <code>materialDictionary</code> value set to the ship’s current material dictionary.<br />
<br />
'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code><br />
<br />
=== <code>spawn</code> ===<br />
function '''spawn'''(role : String [, count : Number]) : Array<br />
Attempts to create <code>count</code> (maximum: 64) ships of role <code>role</code> close to the ship – specifically, inside the ship’s collision radius. (Since creating ships may fail, the number created may be less than <code>count</code>). The created ships are returned in an array. If <code>count</code> is not specified, one will be assumed.<br />
<br />
<code>spawn()</code> is intended for cases when a ship splits into multiple parts or drops parts. In particular, it has the following special behaviour:<br />
* The spawned ships inherit most of the temperature of the parent.<br />
* If the parent is a missile and a child has the <code>[[shipdata.plist#is_submunition|is_submunition]]</code> property, the child will be considered a missile, its target will be set to that of the parent and the child’s owner will be set to the parent.<br />
* <code>spawn()</code> does not set up escorts for the new ships, or generate witchspace effects, or do any special AI handling.<br />
<br />
=== <code>spawnOne</code> ===<br />
function '''spawnOne'''(role : String) : Ship<br />
Convenience method which calls <code>[[#spawn|spawn]](role)</code> and returns the first element of the resulting array, or <code>null</code> if <code>spawn()</code> fails.<br />
<br />
=== <code>switchAI</code> ===<br />
function '''switchAI'''(AIName : String)<br />
Set the current AI, exiting the old one. Equivalent to the <code>[[AI_methods|switchAITo]]:</code> AI method. May not be used on player.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#exitAI|exitAI()]]</code><br />
<br />
=== <code>threatAssessment</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''threatAssessment'''(full : Boolean) : Number<br />
Returns a number indicating the relative strength of the ship. If the 'full' parameter is true, additional information will be considered as part of the assessment which would generally only be known by ships which know this ship or have seen it in combat. Otherwise, only data which could reasonably be expected to be common knowledge based on the class of the ship will be included.<br />
<br />
For example, which weapon facings are available is part of the basic assessment, but what forward laser the ship has is part of the full assessment.<br />
<br />
=== <code>throwSpark</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''throwSpark'''()<br />
Sets the ship to throw a spark as if it was seriously damaged. If this ship is already scheduled to throw a spark, this does nothing.<br />
<br />
=== <code>updateEscortFormation</code> ===<br />
function '''updateEscortFormation'''()<br />
Request that the game updates the target positions for the ship’s escorts by calling the ship’s script’s <code>coordinatesForEscortPosition()</code> method.<br />
<br />
== Static Methods ==<br />
=== <code>keys</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''keys'''() : Array<br />
Returns all dataKeys of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.<br />
var dataKeysArray = Ship.keys();<br />
<br />
=== <code>keysForRole</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''keysForRole'''(role : String) : Array<br />
Returns all dataKeys of ships defined in all [[shipdata.plist]] which contains the given role.<br />
<br />
var role = "trader";<br />
var roleKeys = Ship.keysForRole( role );<br />
log("keysForRole", role + ": " + roleKeys );<br />
<br />
=== <code>roleIsInCategory</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''roles'''(role : String, category : String) : Boolean<br />
Returns whether the role given is in a particular category as defined in [[role-categories.plist]]<br />
<br />
Ship.roleIsInCategory("trader","oolite-pirate-victims"); // true<br />
<br />
=== <code>roles</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''roles'''() : Array<br />
Returns all roles of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.<br />
<br />
var roles = Ship.roles();<br />
for( var i = 0; i < roles.length; i++ ) {<br />
var roleKeys = Ship.keysForRole( roles[i] );<br />
log("roles", i + ". "+roles[i] + ": " + roleKeys );<br />
}<br />
<br />
=== <code>shipDataForKey</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''shipDataForKey'''(datakey : String) : Object<br />
Returns an object containing a representation of the raw [[shipdata.plist]] entry for a given data key, or null if the data key does not exist. Keys not defined in the shipdata.plist entry will not be defined in the object - they won't get their default values.<br />
<br />
Using the ship object properties is generally a better way to get this information, but this is useful if you want to find out what a ship might be like if you did add it.<br />
<br />
var shipdata = Ship.shipDataForKey("cobra3-trader");<br />
log("test",shipdata["name"]); // "Cobra Mark III"<br />
log("test",shipdata["ship_class_name"]); // undefined<br />
log("test",shipdata["ship_unique_name"]); // undefined<br />
log("test",shipdata["display_name"]); // undefined<br />
<br />
==See also==<br />
*[[Shipdata.plist]]<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Role-categories.plist&diff=47231Role-categories.plist2015-04-25T07:49:33Z<p>Cim: Link to Roles page</p>
<hr />
<div>This file supersedes [[Misc_plists#pirate-victim-roles.plist|pirate-victim-roles.plist]] from Oolite 1.79 onwards. It does nothing in previous versions.<br />
<br />
This file sets up various categories into which [[Oolite_Ship_Roles|roles]] can be placed. These categories can then be used by the AI, using the <code>[[Oolite_JavaScript_Reference:_Ship#roleIsInCategory|Ship.roleIsInCategory()]]</code> Javascript function, to determine its reaction to a particular ship.<br />
<br />
Its format is a dictionary, with the key being the category name, and the value being a list of ship roles (or player roles) in that category. For example:<br />
{<br />
/* Roles used by bounty hunters */<br />
"oolite-bounty-hunter" = (<br />
"hunter",<br />
"hunter-medium",<br />
"hunter-heavy"<br />
);<br />
}<br />
<br />
This file has slightly different merging rules to most other Oolite plists. If two role-categories.plist files define the same key, the result will be the union of the values of those files, not simply one or the other. This allows OXPs to easily add extra roles to existing categories.<br />
<br />
Oolite currently defines the following categories, but you are free to add more in OXPs.<br />
* '''oolite-assassin''': roles used by ships which hunt couriers to destroy their packages and passengers<br />
* '''oolite-bounty-hunter''': roles used by bounty hunters (i.e. ships that destroy offenders for their bounty)<br />
* '''oolite-courier''': roles used by ships that make money specifically carrying packages or parcels from system to system<br />
* '''oolite-escort''': roles used by ships which escort other ships. A ship with a primary role not in this list will never be accepted as an escort<br />
* '''oolite-pirate''': roles used by pirate ships<br />
* '''oolite-pirate-enemy''': roles used by ships which routinely attack pirates (e.g. bounty hunters, police)<br />
* '''oolite-pirate-leader''': roles used by the leaders of large pirate packs.<br />
* '''oolite-pirate-victim''': ships likely to be carrying cargo suitable for pirate attack. Any roles in an old <code>pirate-victim-roles.plist</code> file will also be added to this category.<br />
* '''oolite-police-like''': roles the police are more likely to side with in a fight<br />
* '''oolite-police-dislike''': roles the police are less likely to side with in a fight<br />
* '''oolite-scavenger''': roles used by scavenger and miner ships<br />
* '''oolite-shuttle''': roles used by ships which travel between stations and planets in one system, and are usually unarmed<br />
* '''oolite-trader''': roles used by ships that make money carrying items (including trade goods) from system to system<br />
<br />
<br />
[[Category:Oolite]]<br />
[[Category:Oolite scripting]]<br />
<br />
=See also=<br />
* [[OXP howto]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Mission&diff=47221Oolite JavaScript Reference: Mission2015-04-18T12:34:41Z<p>Cim: /* runScreen */ style fix</p>
<hr />
<div><small>'''Prototype:''' <code>Object</code></small><br /><br />
<small>'''Subtypes:''' none</small><br />
<br />
The '''mission''' global object is used to run mission screens, and perform other actions related to mission scripting.<br />
<br />
== Properties ==<br />
<br />
=== <code>displayModel</code> ===<br />
'''displayModel''' : {{oojsclass|Ship}}<br />
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.<br />
<br />
=== <code>exitScreen</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''exitScreen''' : [[Oolite JavaScript Reference: Global#guiScreen|guiScreen]] (read/write)<br />
<br />
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.<br />
<br />
=== <code>markedSystems</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''markedSystems''' : Array (read-only)<br />
<br />
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>.<br />
<br />
=== <code>screenID</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''screenID''' : String (read-only)<br />
<br />
If there is currently a mission screen running, and it defined a screenID, then that screenID. Otherwise, this is null.<br />
<br />
== Methods ==<br />
<br />
=== <code>addMessageText</code> ===<br />
function '''addMessageText'''(message : String)<br />
<br />
Appends text to the currently running mission screen. Can also be used to add text to other screens like the system data (F7) screen.<br />
<br />
=== <code>addMessageTextKey</code> ===<br />
function '''addMessageTextKey'''(messageKey : String)<br />
<br />
Like <code>[[#addMessageText|addMessageText()]]</code>, but looks up the specified <code>messageKey</code> in [[missiontext.plist]].<br />
<br />
=== <code>markSystem</code> ===<br />
function '''markSystem'''(systemNumber : Number)<br />
<br />
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:<br />
mission.markSystem(7);<br />
mission.markSystem(7);<br />
mission.unmarkSystem(7);<br />
will leave the system unmarked.<br />
<br />
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:<br />
* <code>system</code> : The system ID. This is the only required parameter.<br />
* <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.<br />
* <code>markerColor</code> : A string specifying a colour. e.g. "redColor" or "1.0 0.5 0.0". If omitted, "redColor" will be used.<br />
* <code>markerScale</code> : A number between 0.5 and 2.0 specifying the relative size of the marker. Defaults to 1.0.<br />
* <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.<br />
<br />
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.<br />
<br />
mission.markSystem({<br />
system: 55,<br />
name: "my_oxp",<br />
markerColor: "cyanColor",<br />
markerScale: 1.5,<br />
markerShape: "MARKER_DIAMOND"<br />
});<br />
<br />
'''See also:''' <code>[[#unmarkSystem|unmarkSystem()]]</code><br />
<br />
=== <code>runShipLibrary</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''runShipLibrary()'''<br />
Display the ship library based on [[shiplibrary.plist]], including processing of condition scripts.<br />
<br />
This is mainly useful for scenarios which override the standard scripts.<br />
<br />
=== <code>runScreen</code> ===<br />
function '''runScreen(parameters : Object [, callback : Function [, this : Object]])''' <br />
Present a mission screen.<br />
<br />
The appearance of the mission screen is defined by the properties of the <code>parameters</code> object. The currently defined properties are:<br />
* <code>title : String</code><br />
* <code>titleKey : String</code> (Key in [[missiontext.plist]])<br />
* <code>music : String</code> (name of a music file)<br />
* <code>overlay : ''guiTextureSpecifier''</code> (name of an image used as overlay)<br />
* <code>background : ''guiTextureSpecifier''</code> (name of a picture used as background)<br />
* <code>backgroundSpecial: String</code> (1.77 or later, special background layer)<br />
* <code>model : String</code> (Role of a ship that will be shown as rotating ship)<br />
* <code>modelPersonality : Int</code> (1.77 or later, the entityPersonality assigned to the <code>model</code>. If unspecified, or in 1.76 or earlier, a random personality is used)<br />
* <code>message : String</code><br />
* <code>messageKey : String</code> (Key in [[missiontext.plist]])<br />
* <code>spinModel: Boolean</code> (If <code>false</code>, the model is shown from the top with no automatic animation.)<br />
* <code>[[Oolite JavaScript Reference: Mission#Advanced choices (1.77 or later only)|choices]]: Object</code> (1.77 or later. Object describing choices)<br />
* <code>choicesKey : String</code> (Key in [[missiontext.plist]])<br />
* <code>initialChoicesKey : String</code> (1.77 or later, the key from <code>choicesKey</code> which is initially selected)<br />
* <code>allowInterrupt : Boolean</code> (1.77 or later. 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.)<br />
* <code>exitScreen : ''guiScreen''</code> (1.77 or later, 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)<br />
* <code>screenID : String</code> (1.77 or later, an optional string which can be read later from <code>[[#screenID|mission.screenID]]</code><br />
* <code>textEntry : Boolean</code> (1.79 or later, 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.)<br />
<br />
<br />
Some of these are mutually exclusive; for instance, “title” overrides “titleKey”. See [[Oolite JavaScript Reference: Global#setScreenBackground|setScreenBackground()]] for a discussion of ''guiTextureSpecifier''. <br />
<br />
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)<br />
<br />
==== runScreen callbacks ====<br />
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.<br />
<br />
'''Example:'''<br><br />
A simple mission screen:<br />
mission.runScreen({<br />
title: "My first mission screen",<br />
message: "This am a mission screen wot is good",<br />
choicesKey: "me_firstmission_choices"<br />
},<br />
function (choice)<br />
{<br />
if (choice === "1_YES") player.commsMessage("Yay!");<br />
else if (choice === "2_NO") player.commsMessage("Boo.");<br />
else player.commsMessage("Whut?");<br />
});<br />
In [[missiontext.plist]], you’ll need the following. The numbers are used because choices are sorted by key.<br />
{<br />
"me_firstmission_choices" =<br />
{<br />
"1_YES" = "Yes.";<br />
"2_NO" = "No.";<br />
"3_MAYBE" = "Maybe.";<br />
};<br />
}<br />
<br />
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:<br />
var parameters = new Object();<br />
parameters.title = "My first mission screen";<br />
parameters.message = "This am";<br />
parameters.choicesKey = "me_firstmission_choices";<br />
parameters.message += " a mission screen wot is good";<br />
<br />
function callback(choice)<br />
{<br />
if (choice === "1_YES") player.commsMessage("Yay!");<br />
else if (choice === "2_NO") player.commsMessage("Boo.");<br />
else player.commsMessage("Whut?");<br />
}<br />
<br />
mission.runScreen(parameters, callback);<br />
<br />
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.<br />
<br />
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.<br />
<br />
==== runScreen special backgrounds (1.77 or later only) ====<br />
<br />
In 1.77 or later, 'backgroundSpecial' may be given the following special string values:<br />
* <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.<br />
* <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.<br />
* <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.<br />
* <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.<br />
With all special chart backgrounds, changes made to destination system, or to markers, will be updated immediately.<br />
These backgrounds will be displayed above the '<code>background</code>' (if any) but below everything else.<br />
<br />
==== Advanced choices (1.77 or later only) ====<br />
<br />
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)<br />
'''Example'''<br><br />
var options = {<br />
"01_AGREE" : "Take the job",<br />
"02_DECLINE" : "Politely decline"<br />
};<br />
if (player.bounty == 0) // only clean players have this option<br />
{<br />
options["03_REPORT"] = "Call the police";<br />
}<br />
<br />
mission.runScreen({<br />
// title, message, etc.<br />
choices: options<br />
},function(choice) {<br />
// choice handling<br />
});<br />
<br />
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.<br />
<br />
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: <br />
* 'text' is the displayed text for this key. <br />
* 'alignment' can be 'LEFT', 'RIGHT' or 'CENTER' (the default). <br />
* '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.<br />
* 'color' can be any color specification (e.g. "orangeColor"). The default is "yellowColor", or "darkGrayColor" for unselectable rows.<br />
For example (missiontext.plist):<br />
"my_choice_1" = {<br />
"01_AGREE" = {<br />
text = "Take the job";<br />
alignment = "LEFT";<br />
color = "greenColor";<br />
};<br />
// more options<br />
};<br />
<br />
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.<br />
<br />
==== Safe usage of runScreen ====<br />
<br />
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.<br />
<br />
==== Known issues ====<br />
<br />
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.<br />
<br />
=== <code>setInstructions</code> ===<br />
function '''setInstructions(instructions : String, [worldScriptName : String])'''<br />
<br />
Specify a message to put on the Manifest screen (usually short instructions for current mission), under the title “Missions”.<br />
<br />
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>.<br />
<br />
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.<br />
<br />
In Oolite 1.81 onwards, the following variant is available<br />
<br />
{{oolite-method-added|1.81}}<br />
function '''setInstructions(instructions : Array, [worldScriptName : String])'''<br />
<br />
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.<br />
<br />
'''See also:''' <code>[[#setInstructionsKey|setInstructionsKey()]]</code><br />
<br />
=== <code>setInstructionsKey</code> ===<br />
function '''setInstructionsKey(messageKey : String, [worldScript : String])'''<br />
<br />
Like <code>[[#setInstructions|setInstructions()]]</code>, but looks up the specified <code>messageKey</code> in [[missiontext.plist]].<br />
<br />
'''See also:''' <code>[[#setInstructions|setInstructions()]]</code><br />
<br />
=== <code>unmarkSystem</code> ===<br />
function '''unmarkSystem'''(systemNumbers : Number)<br />
<br />
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>.<br />
<br />
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. <br />
<br />
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.<br />
<br />
'''See also:''' <code>[[#markSystem|markSystem()]]</code><br />
<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Mission&diff=47220Oolite JavaScript Reference: Mission2015-04-18T12:34:29Z<p>Cim: /* runShipLibrary */ style fix</p>
<hr />
<div><small>'''Prototype:''' <code>Object</code></small><br /><br />
<small>'''Subtypes:''' none</small><br />
<br />
The '''mission''' global object is used to run mission screens, and perform other actions related to mission scripting.<br />
<br />
== Properties ==<br />
<br />
=== <code>displayModel</code> ===<br />
'''displayModel''' : {{oojsclass|Ship}}<br />
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.<br />
<br />
=== <code>exitScreen</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''exitScreen''' : [[Oolite JavaScript Reference: Global#guiScreen|guiScreen]] (read/write)<br />
<br />
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.<br />
<br />
=== <code>markedSystems</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''markedSystems''' : Array (read-only)<br />
<br />
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>.<br />
<br />
=== <code>screenID</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''screenID''' : String (read-only)<br />
<br />
If there is currently a mission screen running, and it defined a screenID, then that screenID. Otherwise, this is null.<br />
<br />
== Methods ==<br />
<br />
=== <code>addMessageText</code> ===<br />
function '''addMessageText'''(message : String)<br />
<br />
Appends text to the currently running mission screen. Can also be used to add text to other screens like the system data (F7) screen.<br />
<br />
=== <code>addMessageTextKey</code> ===<br />
function '''addMessageTextKey'''(messageKey : String)<br />
<br />
Like <code>[[#addMessageText|addMessageText()]]</code>, but looks up the specified <code>messageKey</code> in [[missiontext.plist]].<br />
<br />
=== <code>markSystem</code> ===<br />
function '''markSystem'''(systemNumber : Number)<br />
<br />
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:<br />
mission.markSystem(7);<br />
mission.markSystem(7);<br />
mission.unmarkSystem(7);<br />
will leave the system unmarked.<br />
<br />
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:<br />
* <code>system</code> : The system ID. This is the only required parameter.<br />
* <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.<br />
* <code>markerColor</code> : A string specifying a colour. e.g. "redColor" or "1.0 0.5 0.0". If omitted, "redColor" will be used.<br />
* <code>markerScale</code> : A number between 0.5 and 2.0 specifying the relative size of the marker. Defaults to 1.0.<br />
* <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.<br />
<br />
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.<br />
<br />
mission.markSystem({<br />
system: 55,<br />
name: "my_oxp",<br />
markerColor: "cyanColor",<br />
markerScale: 1.5,<br />
markerShape: "MARKER_DIAMOND"<br />
});<br />
<br />
'''See also:''' <code>[[#unmarkSystem|unmarkSystem()]]</code><br />
<br />
=== <code>runShipLibrary</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''runShipLibrary()'''<br />
Display the ship library based on [[shiplibrary.plist]], including processing of condition scripts.<br />
<br />
This is mainly useful for scenarios which override the standard scripts.<br />
<br />
=== <code>runScreen</code> ===<br />
'''runScreen(parameters : Object [, callback : Function [, this : Object]])''' <br />
Present a mission screen.<br />
<br />
The appearance of the mission screen is defined by the properties of the <code>parameters</code> object. The currently defined properties are:<br />
* <code>title : String</code><br />
* <code>titleKey : String</code> (Key in [[missiontext.plist]])<br />
* <code>music : String</code> (name of a music file)<br />
* <code>overlay : ''guiTextureSpecifier''</code> (name of an image used as overlay)<br />
* <code>background : ''guiTextureSpecifier''</code> (name of a picture used as background)<br />
* <code>backgroundSpecial: String</code> (1.77 or later, special background layer)<br />
* <code>model : String</code> (Role of a ship that will be shown as rotating ship)<br />
* <code>modelPersonality : Int</code> (1.77 or later, the entityPersonality assigned to the <code>model</code>. If unspecified, or in 1.76 or earlier, a random personality is used)<br />
* <code>message : String</code><br />
* <code>messageKey : String</code> (Key in [[missiontext.plist]])<br />
* <code>spinModel: Boolean</code> (If <code>false</code>, the model is shown from the top with no automatic animation.)<br />
* <code>[[Oolite JavaScript Reference: Mission#Advanced choices (1.77 or later only)|choices]]: Object</code> (1.77 or later. Object describing choices)<br />
* <code>choicesKey : String</code> (Key in [[missiontext.plist]])<br />
* <code>initialChoicesKey : String</code> (1.77 or later, the key from <code>choicesKey</code> which is initially selected)<br />
* <code>allowInterrupt : Boolean</code> (1.77 or later. 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.)<br />
* <code>exitScreen : ''guiScreen''</code> (1.77 or later, 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)<br />
* <code>screenID : String</code> (1.77 or later, an optional string which can be read later from <code>[[#screenID|mission.screenID]]</code><br />
* <code>textEntry : Boolean</code> (1.79 or later, 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.)<br />
<br />
<br />
Some of these are mutually exclusive; for instance, “title” overrides “titleKey”. See [[Oolite JavaScript Reference: Global#setScreenBackground|setScreenBackground()]] for a discussion of ''guiTextureSpecifier''. <br />
<br />
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)<br />
<br />
==== runScreen callbacks ====<br />
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.<br />
<br />
'''Example:'''<br><br />
A simple mission screen:<br />
mission.runScreen({<br />
title: "My first mission screen",<br />
message: "This am a mission screen wot is good",<br />
choicesKey: "me_firstmission_choices"<br />
},<br />
function (choice)<br />
{<br />
if (choice === "1_YES") player.commsMessage("Yay!");<br />
else if (choice === "2_NO") player.commsMessage("Boo.");<br />
else player.commsMessage("Whut?");<br />
});<br />
In [[missiontext.plist]], you’ll need the following. The numbers are used because choices are sorted by key.<br />
{<br />
"me_firstmission_choices" =<br />
{<br />
"1_YES" = "Yes.";<br />
"2_NO" = "No.";<br />
"3_MAYBE" = "Maybe.";<br />
};<br />
}<br />
<br />
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:<br />
var parameters = new Object();<br />
parameters.title = "My first mission screen";<br />
parameters.message = "This am";<br />
parameters.choicesKey = "me_firstmission_choices";<br />
parameters.message += " a mission screen wot is good";<br />
<br />
function callback(choice)<br />
{<br />
if (choice === "1_YES") player.commsMessage("Yay!");<br />
else if (choice === "2_NO") player.commsMessage("Boo.");<br />
else player.commsMessage("Whut?");<br />
}<br />
<br />
mission.runScreen(parameters, callback);<br />
<br />
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.<br />
<br />
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.<br />
<br />
==== runScreen special backgrounds (1.77 or later only) ====<br />
<br />
In 1.77 or later, 'backgroundSpecial' may be given the following special string values:<br />
* <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.<br />
* <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.<br />
* <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.<br />
* <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.<br />
With all special chart backgrounds, changes made to destination system, or to markers, will be updated immediately.<br />
These backgrounds will be displayed above the '<code>background</code>' (if any) but below everything else.<br />
<br />
==== Advanced choices (1.77 or later only) ====<br />
<br />
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)<br />
'''Example'''<br><br />
var options = {<br />
"01_AGREE" : "Take the job",<br />
"02_DECLINE" : "Politely decline"<br />
};<br />
if (player.bounty == 0) // only clean players have this option<br />
{<br />
options["03_REPORT"] = "Call the police";<br />
}<br />
<br />
mission.runScreen({<br />
// title, message, etc.<br />
choices: options<br />
},function(choice) {<br />
// choice handling<br />
});<br />
<br />
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.<br />
<br />
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: <br />
* 'text' is the displayed text for this key. <br />
* 'alignment' can be 'LEFT', 'RIGHT' or 'CENTER' (the default). <br />
* '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.<br />
* 'color' can be any color specification (e.g. "orangeColor"). The default is "yellowColor", or "darkGrayColor" for unselectable rows.<br />
For example (missiontext.plist):<br />
"my_choice_1" = {<br />
"01_AGREE" = {<br />
text = "Take the job";<br />
alignment = "LEFT";<br />
color = "greenColor";<br />
};<br />
// more options<br />
};<br />
<br />
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.<br />
<br />
==== Safe usage of runScreen ====<br />
<br />
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.<br />
<br />
==== Known issues ====<br />
<br />
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.<br />
<br />
=== <code>setInstructions</code> ===<br />
function '''setInstructions(instructions : String, [worldScriptName : String])'''<br />
<br />
Specify a message to put on the Manifest screen (usually short instructions for current mission), under the title “Missions”.<br />
<br />
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>.<br />
<br />
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.<br />
<br />
In Oolite 1.81 onwards, the following variant is available<br />
<br />
{{oolite-method-added|1.81}}<br />
function '''setInstructions(instructions : Array, [worldScriptName : String])'''<br />
<br />
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.<br />
<br />
'''See also:''' <code>[[#setInstructionsKey|setInstructionsKey()]]</code><br />
<br />
=== <code>setInstructionsKey</code> ===<br />
function '''setInstructionsKey(messageKey : String, [worldScript : String])'''<br />
<br />
Like <code>[[#setInstructions|setInstructions()]]</code>, but looks up the specified <code>messageKey</code> in [[missiontext.plist]].<br />
<br />
'''See also:''' <code>[[#setInstructions|setInstructions()]]</code><br />
<br />
=== <code>unmarkSystem</code> ===<br />
function '''unmarkSystem'''(systemNumbers : Number)<br />
<br />
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>.<br />
<br />
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. <br />
<br />
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.<br />
<br />
'''See also:''' <code>[[#markSystem|markSystem()]]</code><br />
<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Mission&diff=47219Oolite JavaScript Reference: Mission2015-04-18T12:34:04Z<p>Cim: /* runShipLibrary */ new method</p>
<hr />
<div><small>'''Prototype:''' <code>Object</code></small><br /><br />
<small>'''Subtypes:''' none</small><br />
<br />
The '''mission''' global object is used to run mission screens, and perform other actions related to mission scripting.<br />
<br />
== Properties ==<br />
<br />
=== <code>displayModel</code> ===<br />
'''displayModel''' : {{oojsclass|Ship}}<br />
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.<br />
<br />
=== <code>exitScreen</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''exitScreen''' : [[Oolite JavaScript Reference: Global#guiScreen|guiScreen]] (read/write)<br />
<br />
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.<br />
<br />
=== <code>markedSystems</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''markedSystems''' : Array (read-only)<br />
<br />
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>.<br />
<br />
=== <code>screenID</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''screenID''' : String (read-only)<br />
<br />
If there is currently a mission screen running, and it defined a screenID, then that screenID. Otherwise, this is null.<br />
<br />
== Methods ==<br />
<br />
=== <code>addMessageText</code> ===<br />
function '''addMessageText'''(message : String)<br />
<br />
Appends text to the currently running mission screen. Can also be used to add text to other screens like the system data (F7) screen.<br />
<br />
=== <code>addMessageTextKey</code> ===<br />
function '''addMessageTextKey'''(messageKey : String)<br />
<br />
Like <code>[[#addMessageText|addMessageText()]]</code>, but looks up the specified <code>messageKey</code> in [[missiontext.plist]].<br />
<br />
=== <code>markSystem</code> ===<br />
function '''markSystem'''(systemNumber : Number)<br />
<br />
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:<br />
mission.markSystem(7);<br />
mission.markSystem(7);<br />
mission.unmarkSystem(7);<br />
will leave the system unmarked.<br />
<br />
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:<br />
* <code>system</code> : The system ID. This is the only required parameter.<br />
* <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.<br />
* <code>markerColor</code> : A string specifying a colour. e.g. "redColor" or "1.0 0.5 0.0". If omitted, "redColor" will be used.<br />
* <code>markerScale</code> : A number between 0.5 and 2.0 specifying the relative size of the marker. Defaults to 1.0.<br />
* <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.<br />
<br />
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.<br />
<br />
mission.markSystem({<br />
system: 55,<br />
name: "my_oxp",<br />
markerColor: "cyanColor",<br />
markerScale: 1.5,<br />
markerShape: "MARKER_DIAMOND"<br />
});<br />
<br />
'''See also:''' <code>[[#unmarkSystem|unmarkSystem()]]</code><br />
<br />
=== <code>runShipLibrary</code> ===<br />
{{oolite-method-added|1.81}}<br />
'''runShipLibrary()'''<br />
Display the ship library based on [[shiplibrary.plist]], including processing of condition scripts.<br />
<br />
This is mainly useful for scenarios which override the standard scripts.<br />
<br />
=== <code>runScreen</code> ===<br />
'''runScreen(parameters : Object [, callback : Function [, this : Object]])''' <br />
Present a mission screen.<br />
<br />
The appearance of the mission screen is defined by the properties of the <code>parameters</code> object. The currently defined properties are:<br />
* <code>title : String</code><br />
* <code>titleKey : String</code> (Key in [[missiontext.plist]])<br />
* <code>music : String</code> (name of a music file)<br />
* <code>overlay : ''guiTextureSpecifier''</code> (name of an image used as overlay)<br />
* <code>background : ''guiTextureSpecifier''</code> (name of a picture used as background)<br />
* <code>backgroundSpecial: String</code> (1.77 or later, special background layer)<br />
* <code>model : String</code> (Role of a ship that will be shown as rotating ship)<br />
* <code>modelPersonality : Int</code> (1.77 or later, the entityPersonality assigned to the <code>model</code>. If unspecified, or in 1.76 or earlier, a random personality is used)<br />
* <code>message : String</code><br />
* <code>messageKey : String</code> (Key in [[missiontext.plist]])<br />
* <code>spinModel: Boolean</code> (If <code>false</code>, the model is shown from the top with no automatic animation.)<br />
* <code>[[Oolite JavaScript Reference: Mission#Advanced choices (1.77 or later only)|choices]]: Object</code> (1.77 or later. Object describing choices)<br />
* <code>choicesKey : String</code> (Key in [[missiontext.plist]])<br />
* <code>initialChoicesKey : String</code> (1.77 or later, the key from <code>choicesKey</code> which is initially selected)<br />
* <code>allowInterrupt : Boolean</code> (1.77 or later. 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.)<br />
* <code>exitScreen : ''guiScreen''</code> (1.77 or later, 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)<br />
* <code>screenID : String</code> (1.77 or later, an optional string which can be read later from <code>[[#screenID|mission.screenID]]</code><br />
* <code>textEntry : Boolean</code> (1.79 or later, 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.)<br />
<br />
<br />
Some of these are mutually exclusive; for instance, “title” overrides “titleKey”. See [[Oolite JavaScript Reference: Global#setScreenBackground|setScreenBackground()]] for a discussion of ''guiTextureSpecifier''. <br />
<br />
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)<br />
<br />
==== runScreen callbacks ====<br />
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.<br />
<br />
'''Example:'''<br><br />
A simple mission screen:<br />
mission.runScreen({<br />
title: "My first mission screen",<br />
message: "This am a mission screen wot is good",<br />
choicesKey: "me_firstmission_choices"<br />
},<br />
function (choice)<br />
{<br />
if (choice === "1_YES") player.commsMessage("Yay!");<br />
else if (choice === "2_NO") player.commsMessage("Boo.");<br />
else player.commsMessage("Whut?");<br />
});<br />
In [[missiontext.plist]], you’ll need the following. The numbers are used because choices are sorted by key.<br />
{<br />
"me_firstmission_choices" =<br />
{<br />
"1_YES" = "Yes.";<br />
"2_NO" = "No.";<br />
"3_MAYBE" = "Maybe.";<br />
};<br />
}<br />
<br />
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:<br />
var parameters = new Object();<br />
parameters.title = "My first mission screen";<br />
parameters.message = "This am";<br />
parameters.choicesKey = "me_firstmission_choices";<br />
parameters.message += " a mission screen wot is good";<br />
<br />
function callback(choice)<br />
{<br />
if (choice === "1_YES") player.commsMessage("Yay!");<br />
else if (choice === "2_NO") player.commsMessage("Boo.");<br />
else player.commsMessage("Whut?");<br />
}<br />
<br />
mission.runScreen(parameters, callback);<br />
<br />
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.<br />
<br />
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.<br />
<br />
==== runScreen special backgrounds (1.77 or later only) ====<br />
<br />
In 1.77 or later, 'backgroundSpecial' may be given the following special string values:<br />
* <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.<br />
* <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.<br />
* <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.<br />
* <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.<br />
With all special chart backgrounds, changes made to destination system, or to markers, will be updated immediately.<br />
These backgrounds will be displayed above the '<code>background</code>' (if any) but below everything else.<br />
<br />
==== Advanced choices (1.77 or later only) ====<br />
<br />
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)<br />
'''Example'''<br><br />
var options = {<br />
"01_AGREE" : "Take the job",<br />
"02_DECLINE" : "Politely decline"<br />
};<br />
if (player.bounty == 0) // only clean players have this option<br />
{<br />
options["03_REPORT"] = "Call the police";<br />
}<br />
<br />
mission.runScreen({<br />
// title, message, etc.<br />
choices: options<br />
},function(choice) {<br />
// choice handling<br />
});<br />
<br />
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.<br />
<br />
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: <br />
* 'text' is the displayed text for this key. <br />
* 'alignment' can be 'LEFT', 'RIGHT' or 'CENTER' (the default). <br />
* '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.<br />
* 'color' can be any color specification (e.g. "orangeColor"). The default is "yellowColor", or "darkGrayColor" for unselectable rows.<br />
For example (missiontext.plist):<br />
"my_choice_1" = {<br />
"01_AGREE" = {<br />
text = "Take the job";<br />
alignment = "LEFT";<br />
color = "greenColor";<br />
};<br />
// more options<br />
};<br />
<br />
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.<br />
<br />
==== Safe usage of runScreen ====<br />
<br />
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.<br />
<br />
==== Known issues ====<br />
<br />
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.<br />
<br />
=== <code>setInstructions</code> ===<br />
function '''setInstructions(instructions : String, [worldScriptName : String])'''<br />
<br />
Specify a message to put on the Manifest screen (usually short instructions for current mission), under the title “Missions”.<br />
<br />
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>.<br />
<br />
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.<br />
<br />
In Oolite 1.81 onwards, the following variant is available<br />
<br />
{{oolite-method-added|1.81}}<br />
function '''setInstructions(instructions : Array, [worldScriptName : String])'''<br />
<br />
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.<br />
<br />
'''See also:''' <code>[[#setInstructionsKey|setInstructionsKey()]]</code><br />
<br />
=== <code>setInstructionsKey</code> ===<br />
function '''setInstructionsKey(messageKey : String, [worldScript : String])'''<br />
<br />
Like <code>[[#setInstructions|setInstructions()]]</code>, but looks up the specified <code>messageKey</code> in [[missiontext.plist]].<br />
<br />
'''See also:''' <code>[[#setInstructions|setInstructions()]]</code><br />
<br />
=== <code>unmarkSystem</code> ===<br />
function '''unmarkSystem'''(systemNumbers : Number)<br />
<br />
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>.<br />
<br />
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. <br />
<br />
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.<br />
<br />
'''See also:''' <code>[[#markSystem|markSystem()]]</code><br />
<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Shiplibrary.plist&diff=47218Shiplibrary.plist2015-04-18T10:19:34Z<p>Cim: </p>
<hr />
<div>The <code>shiplibrary.plist</code> file places ship information on the View Ship Library page when Oolite starts up, in version 1.79 or later.<br />
<br />
It is a list of dictionaries, with the following keys. Strictly, only the 'ship' key is required, but setting at least the 'class' and 'summary' keys is also recommended. All keys which display text to the end user will be expanded via [[descriptions.plist]] and the usual expansion rules.<br />
<br />
In general, entries should only be included in this file if:<br />
* no other near-identical variant is included (e.g. the core file includes the cobra3-trader but not the cobra3-pirate which is essentially the same ship with different equipment and maybe different paint; the description covers both subtypes - or the core file includes one asteroid entry to cover all asteroids, boulders, splinters and cinders)<br />
* the entry is not a player ship (i.e. include cobra3-trader not cobra3-player)<br />
* the ship is public knowledge (e.g. certain secret mission ships are not included in the core game's default library view) - though in 1.81 onwards you can use condition scripts to display secret ships the player has discovered.<br />
<br />
==Keys==<br />
<br />
===class===<br />
This can currently take one of five values: 'ship' (the default, including large ships with docks), 'station' (stationary dockable objects), 'weapon' (mines and missiles), 'thargoid', and 'misc' (asteroids, navigation buoys, cargo, etc.). Other classes may be added if requested.<br />
class = "station";<br />
<br />
===condition_script===<br />
(Oolite 1.81 and later)<br />
<br />
If this is set, then:<br />
* in game, the named [[Oolite_JavaScript_Reference:_Condition_scripts|condition script]] will be loaded and used to determine whether to include this entry in the library by calling the <code>allowShowLibraryShip</code> method.<br />
* on the start screen, the ship will not be shown.<br />
<br />
This is used in the core game to hide a mission-specific ship until that mission starts.<br />
<br />
===description===<br />
A short text description of the ship summarising its purpose, strengths, weaknesses and NPC preferred uses. Descriptions longer than 200-300 characters will probably start to look too long if <code>[[#ship_data|ship_data]]</code> is true.<br />
description = "[myoxp-ship-description-myship]";<br />
<br />
===ship===<br />
The data key in [[shipdata.plist]] of this ship.<br />
ship = "cobra3-trader";<br />
<br />
===ship_data===<br />
Whether to display a mostly-automated 3 line data block assessing standard capabilities (speed, turn rate, energy, weapons, etc.) between the ship's name and its [[#description|description]] text. This defaults to <code>true</code> if the [[#class|class]] is 'ship', and <code>false</code> otherwise.<br />
ship_data = true;<br />
If it is set to or defaults to true, then additional keys listed in this section may also be specified to modify the display of each entry in the data block. Each modifier entry can be:<br />
* unspecified - the data block entry will get a default value. In most cases this will be sufficient. The default values will be consistent in scale with the core ships, so only set a value if you have something different to say.<br />
* a non-empty string - the data block entry will get this expandable string as a custom value<br />
* an empty string - the data block entry will be completely absent, not even the title.<br />
<br />
Rather than using an empty string, the [[descriptions.plist]] entries <code>oolite-ship-library-classified</code> and <code>oolite-ship-library-unknown</code> may sometimes be more appropriate.<br />
====cargo====<br />
The cargo capacity of the ship. Defaults to its real capacity in TC.<br />
cargo = "20/35 TC"; // gives "Cargo: 20/35 TC"<br />
<br />
====generator====<br />
Defaults to an approximate string description of the energy recharge rate of the ship.<br />
generator = "[oolite-ship-library-classified]"; // gives "Generator: Classified"<br />
<br />
====shields====<br />
Defaults to an approximate assessment of the ship's energy banks.<br />
shields = "Impenetrable"; // gives "Shields: Impenetrable"<br />
<br />
====size====<br />
Defaults to a description of the size of the ship's bounding box (in x, y, z order), rounded to the nearest metre.<br />
size = "Variable"; // gives "Size: Variable"<br />
<br />
====speed====<br />
Defaults to an approximate assessment of the maximum non-injector speed of the ship.<br />
speed = "[oolite-ship-library-speed-stationary]"; // gives "Speed: Stationary"<br />
<br />
====turn_rate====<br />
Defaults to an approximate assessment of the ship's combined roll and pitch rates (yaw is not considered)<br />
turn_rate = "Slow roll, fast pitch"; // gives "Turn Rate: Slow roll, fast pitch"<br />
<br />
====weapons====<br />
Defaults to a count of the ship's fixed laser mounts and pylons.<br />
weapons = "6 plasma turrets"; // gives "Weapons: 6 plasma turrets"<br />
<br />
====witchspace====<br />
Defaults to 'yes' or 'no' depending on whether a ship has a witchdrive.<br />
witchspace = "Mk 2 only"; // gives "Witchspace: Mk 2 only"<br />
<br />
===summary===<br />
A very short summary of the type of ship this is, e.g. "Heavy Fighter" or "Research Installation". Some common ship types are defined in [[descriptions.plist]] with keys beginning <code>oolite-ship-library-summary-</code> - if you wish to use one of these keys, then using the descriptions key will make it consistent with core entries if there is a translation OXP installed - e.g.<br />
summary = "[oolite-ship-library-summary-HF]";<br />
rather than<br />
summary = "Heavy Fighter";<br />
Ship summaries not used by any Oolite core ship can be requested for addition to the translatable list if they have general applicability.<br />
<br />
[[Category:Oolite]]<br />
[[Category:Oolite scripting]]</div>Cimhttps://wiki.alioth.net/index.php?title=Shiplibrary.plist&diff=47217Shiplibrary.plist2015-04-18T10:18:45Z<p>Cim: /* Keys */ condition script key</p>
<hr />
<div>The <code>shiplibrary.plist</code> file places ship information on the View Ship Library page when Oolite starts up, in version 1.79 or later.<br />
<br />
It is a list of dictionaries, with the following keys. Strictly, only the 'ship' key is required, but setting at least the 'class' and 'summary' keys is also recommended. All keys which display text to the end user will be expanded via [[descriptions.plist]] and the usual expansion rules.<br />
<br />
In general, entries should only be included in this file if:<br />
* no other near-identical variant is included (e.g. the core file includes the cobra3-trader but not the cobra3-pirate which is essentially the same ship with different equipment and maybe different paint; the description covers both subtypes - or the core file includes one asteroid entry to cover all asteroids, boulders, splinters and cinders)<br />
* the entry is not a player ship (i.e. include cobra3-trader not cobra3-player)<br />
* the ship is public knowledge (e.g. certain secret mission ships are not included in the core game)<br />
<br />
==Keys==<br />
<br />
===class===<br />
This can currently take one of five values: 'ship' (the default, including large ships with docks), 'station' (stationary dockable objects), 'weapon' (mines and missiles), 'thargoid', and 'misc' (asteroids, navigation buoys, cargo, etc.). Other classes may be added if requested.<br />
class = "station";<br />
<br />
===condition_script===<br />
(Oolite 1.81 and later)<br />
<br />
If this is set, then:<br />
* in game, the named [[Oolite_JavaScript_Reference:_Condition_scripts|condition script]] will be loaded and used to determine whether to include this entry in the library by calling the <code>allowShowLibraryShip</code> method.<br />
* on the start screen, the ship will not be shown.<br />
<br />
This is used in the core game to hide a mission-specific ship until that mission starts.<br />
<br />
===description===<br />
A short text description of the ship summarising its purpose, strengths, weaknesses and NPC preferred uses. Descriptions longer than 200-300 characters will probably start to look too long if <code>[[#ship_data|ship_data]]</code> is true.<br />
description = "[myoxp-ship-description-myship]";<br />
<br />
===ship===<br />
The data key in [[shipdata.plist]] of this ship.<br />
ship = "cobra3-trader";<br />
<br />
===ship_data===<br />
Whether to display a mostly-automated 3 line data block assessing standard capabilities (speed, turn rate, energy, weapons, etc.) between the ship's name and its [[#description|description]] text. This defaults to <code>true</code> if the [[#class|class]] is 'ship', and <code>false</code> otherwise.<br />
ship_data = true;<br />
If it is set to or defaults to true, then additional keys listed in this section may also be specified to modify the display of each entry in the data block. Each modifier entry can be:<br />
* unspecified - the data block entry will get a default value. In most cases this will be sufficient. The default values will be consistent in scale with the core ships, so only set a value if you have something different to say.<br />
* a non-empty string - the data block entry will get this expandable string as a custom value<br />
* an empty string - the data block entry will be completely absent, not even the title.<br />
<br />
Rather than using an empty string, the [[descriptions.plist]] entries <code>oolite-ship-library-classified</code> and <code>oolite-ship-library-unknown</code> may sometimes be more appropriate.<br />
====cargo====<br />
The cargo capacity of the ship. Defaults to its real capacity in TC.<br />
cargo = "20/35 TC"; // gives "Cargo: 20/35 TC"<br />
<br />
====generator====<br />
Defaults to an approximate string description of the energy recharge rate of the ship.<br />
generator = "[oolite-ship-library-classified]"; // gives "Generator: Classified"<br />
<br />
====shields====<br />
Defaults to an approximate assessment of the ship's energy banks.<br />
shields = "Impenetrable"; // gives "Shields: Impenetrable"<br />
<br />
====size====<br />
Defaults to a description of the size of the ship's bounding box (in x, y, z order), rounded to the nearest metre.<br />
size = "Variable"; // gives "Size: Variable"<br />
<br />
====speed====<br />
Defaults to an approximate assessment of the maximum non-injector speed of the ship.<br />
speed = "[oolite-ship-library-speed-stationary]"; // gives "Speed: Stationary"<br />
<br />
====turn_rate====<br />
Defaults to an approximate assessment of the ship's combined roll and pitch rates (yaw is not considered)<br />
turn_rate = "Slow roll, fast pitch"; // gives "Turn Rate: Slow roll, fast pitch"<br />
<br />
====weapons====<br />
Defaults to a count of the ship's fixed laser mounts and pylons.<br />
weapons = "6 plasma turrets"; // gives "Weapons: 6 plasma turrets"<br />
<br />
====witchspace====<br />
Defaults to 'yes' or 'no' depending on whether a ship has a witchdrive.<br />
witchspace = "Mk 2 only"; // gives "Witchspace: Mk 2 only"<br />
<br />
===summary===<br />
A very short summary of the type of ship this is, e.g. "Heavy Fighter" or "Research Installation". Some common ship types are defined in [[descriptions.plist]] with keys beginning <code>oolite-ship-library-summary-</code> - if you wish to use one of these keys, then using the descriptions key will make it consistent with core entries if there is a translation OXP installed - e.g.<br />
summary = "[oolite-ship-library-summary-HF]";<br />
rather than<br />
summary = "Heavy Fighter";<br />
Ship summaries not used by any Oolite core ship can be requested for addition to the translatable list if they have general applicability.<br />
<br />
[[Category:Oolite]]<br />
[[Category:Oolite scripting]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Condition_scripts&diff=47216Oolite JavaScript Reference: Condition scripts2015-04-18T10:18:22Z<p>Cim: 1.81 update</p>
<hr />
<div>=Condition scripts=<br />
Condition scripts are used to set conditions on the appearance of ships and equipment beyond the basics possible in [[shipdata.plist]], [[shipyard.plist]], [[shiplibrary.plist]] and [[equipment.plist]]. They have a similar purpose to the "conditions" parameters in those plists, which use the legacy scripting engine, but have the full flexibility of the Javascript scripting engine. If both "conditions" and a condition script are specified for the same item, they will both be tested (but you should never need to do this).<br />
<br />
Conditions scripts may define any or all of the following functions. There is a single instance of each condition script regardless of how many ships and equipment items use it, so variables may be shared between calls in <code>this._property</code><br />
<br />
In 1.81 the scripts are extended slightly to modify how things may appear as well as whether they may appear.<br />
<br />
==allowAwardEquipment==<br />
{{oolite-method-added|1.77}}<br />
<br />
This method is called when the game engine needs to know whether a particular ship can have equipment fitted. This may be because the player is looking at possible upgrades at a station, or from a call to [[Oolite_JavaScript_Reference:_Ship#canAwardEquipment|ship.canAwardEquipment]] or [[Oolite_JavaScript_Reference:_Ship#canAwardEquipment|ship.awardEquipment]], or for other similar reasons. The equipment key and a reference to the ship entity are passed as parameters. If the method does not exist, or returns a value other than <code>false</code>, then the equipment may be added or offered for sale (subject to other conditions, of course)<br />
<br />
<code>context</code> will be one of:<br />
* "newShip" - equipment for a ship in a station shipyard (F3 F3)<br />
* "npc" - awarding equipment to NPC on ship setup<br />
* "purchase" - equipment for purchase on the F3 screen<br />
* "scripted" - equipment added by JS or legacy scripts<br />
(Context can in theory also be "loading", "damage" or "portable", but if you see one of these, it's a bug)<br />
<br />
this.allowAwardEquipment = function(eqKey, ship, context)<br />
{<br />
// your code here<br />
return bool;<br />
}<br />
<br />
The standard condition script for the core game equipment allows equipment to be barred using the "<code>oolite-barred-equipment</code>" key in <code>script_info</code>. If this key contains an array of equipment keys, then those items of equipment will not be sold at this station. In 1.79 and later, this <code>script_info</code> key may be applied to any ship, preventing those items being installed onto the ship. For example:<br />
<br />
script_info = {<br />
"oolite-barred-equipment" = ("EQ_WEAPON_MILITARY_LASER");<br />
}<br />
<br />
On a station, this would prevent it selling military lasers. On a ship in 1.79 or later, this would also stop the ship fitting military lasers.<br />
<br />
==allowOfferShip==<br />
{{oolite-method-added|1.77}}<br />
<br />
This method is called when the game engine is considering adding a ship managed by this condition script to a shipyard. If the method does not exist, or returns a value other than <code>false</code>, then the ship may appear for sale (or it may not, for a variety of other reasons). The ship key from shipyard.plist is passed as a parameter.<br />
<br />
this.allowOfferShip = function(shipKey)<br />
{<br />
// your code here<br />
return bool;<br />
}<br />
<br />
==allowShowLibraryShip==<br />
{{oolite-method-added|1.81}}<br />
<br />
This method is called when the ship library is being shown in-game (rather than on the start screen) and determines whether the ship appears on the list for the player to view. If the method does not exist or returns a value which cannot be interpreted as a boolean it will be assumed to have returned true.<br />
<br />
this.allowShowLibraryShip = function(shipKey)<br />
{<br />
// your code here<br />
return bool;<br />
}<br />
<br />
==allowSpawnShip==<br />
{{oolite-method-added|1.77}}<br />
<br />
This method is called when the game engine is considering spawning a ship managed by this condition script. If the method does not exist, or returns a value other than <code>false</code>, then the ship may be spawned (or it may not, if another ship with the appropriate role is selected instead). The ship key from shipdata.plist is passed as a parameter.<br />
<br />
this.allowSpawnShip = function(shipKey)<br />
{<br />
// your code here<br />
return bool;<br />
}<br />
<br />
==updateEquipmentPrice==<br />
{{oolite-method-added|1.81}}<br />
<br />
This method is called when the game engine needs to know the price of fitting equipment covered by this condition script. The method takes an equipment key and the current price as parameters, and must return a non-negative number for the actual price of the equipment.<br />
<br />
this.updateEquipmentPrice = function(equipmentKey, currentPrice)<br />
{<br />
// your code here<br />
return newPrice;<br />
}<br />
<br />
This function is called before [[Shipdata.plist#equipment_price_factor|equipment_price_factor]] is considered.<br />
<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_PlayerShip&diff=47155Oolite JavaScript Reference: PlayerShip2015-04-06T12:30:21Z<p>Cim: Add two new properties for 1.81</p>
<hr />
<div><small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Ship|Ship]]</code></small><br /><br />
<small>'''Subtypes:''' none</small><br />
<br />
The '''<code>PlayerShip</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing the player’s ship. The <code>PlayerShip</code> has all the properties and methods of a <code> [[Oolite JavaScript Reference: Ship|Ship]]</code>, and several others. There is always exactly one PlayerShip object in existence, which can be accessed through <code>[[Oolite JavaScript Reference: Global#player|player]].ship</code>.<br />
<br />
Like any entity, the player ship can become [[Oolite JavaScript Reference: Entity#Stale References|invalid]] – specifically, when the player dies or ejects. Unlike other entities, the player ship can become valid again (after ejecting and being rescued). This is a technicality and it’s not guaranteed to work this way in future.<br />
<br />
== Properties ==<br />
=== <code>aftShield</code> ===<br />
'''aftShield''' : Number (read/write, nonnegative)<br />
The current aft shield level, ranging from 0 to <code>[[#maxAftShield|maxAftShield]]</code>.<br />
<br />
'''See also''': <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#forwardShield|forwardShield]]</code>, <code>[[#maxAftShield|maxAftShield]]</code><br />
<br />
=== <code>aftShieldRechargeRate</code> ===<br />
'''aftShieldRechargeRate''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)<br />
The rate at which the aft shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, but this is not the case from 1.81.<br />
<br />
'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code><br />
<br />
=== <code>cargoSpaceAvailable</code> ===<br />
'''cargoSpaceAvailable''' : Number (read-only integer)<br />
The ship’s available cargo space, in tons.<br />
<br />
=== <code>cargoSpaceUsed</code> ===<br />
'''cargoSpaceUsed''' : Number (read-only integer)<br />
The ship’s current cargo, in tons.<br />
<br />
=== <code>compassMode</code> ===<br />
'''compassMode''' : String (read-only)<br />
Returns the current compass mode, which can be any one of the following:<br />
* COMPASS_MODE_BASIC<br />
* COMPASS_MODE_PLANET<br />
* COMPASS_MODE_STATION<br />
* COMPASS_MODE_SUN<br />
* COMPASS_MODE_TARGET<br />
* COMPASS_MODE_BEACONS<br />
<br />
=== <code>compassTarget</code> ===<br />
'''compassTarget''' : Entity(read-only)<br />
Points at the entity currently targeted by the compass.<br />
<br />
=== <code>crosshairs</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''crosshairs''' : String (read/write)<br />
The name of the [[Crosshairs.plist|crosshairs.plist]] defining the ship’s weapon crosshairs. HUDs can define crosshairs separately. This value will be <code>null</code> if the HUD built-in crosshairs are in use, and setting it to <code>null</code> will revert to the default HUD crosshairs.<br />
<br />
If the HUD is changed, the old value of this property will be discarded, and the HUD's default crosshairs will be used.<br />
<br />
=== <code>currentWeapon</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''currentWeapon''' : EquipmentInfo (read/write)<br />
A shortcut property to whichever of [[Oolite_JavaScript_Reference:_Ship#aftWeapon|aftWeapon]], [[Oolite_JavaScript_Reference:_Ship#forwardWeapon|forwardWeapon]], [[Oolite_JavaScript_Reference:_Ship#portWeapon|portWeapon]] or [[Oolite_JavaScript_Reference:_Ship#starboardWeapon|starboardWeapon]] is the currently active player weapon.<br />
<br />
If the player is on a screen with no active weapon (e.g. docked, or viewing the status screens) then this will always be null, and attempting to write to it will give an error.<br />
<br />
=== <code>cursorCoordinates</code> ===<br />
'''cursorCoordinates''' : Vector3D (read-only)<br />
'''Discouraged in favour of <code>[[#cursorCoordinatesInLY|cursorCoordinatesInLY]]</code>.'''<br /><br />
The current x and y cursor coordinates on the long range screen in the internal coordinate system. The <code>z</code> coordinate is always 0.<br />
<br />
=== <code>cursorCoordinatesInLY</code> ===<br />
'''cursorCoordinatesInLY''' : Vector3D (read-only)<br />
The current x and y cursor coordinates on the long range screen, in light years. The <code>z</code> coordinate is always 0.<br />
<br />
=== <code>docked</code> ===<br />
'''docked''' : Boolean (read-only)<br />
True if the player is docked with a station or carrier.<br />
<br />
=== <code>dockedStation</code> ===<br />
'''dockedStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only)<br />
The station with which the player is currently docked.<br />
<br />
=== <code>forwardShield</code> ===<br />
'''forwardShield''' : Number (read/write, nonnegative)<br />
The current forward shield level, ranging from 0 to <code>[[#maxForwardShield|maxForwardShield]]</code>.<br />
<br />
'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code><br />
<br />
=== <code>forwardShieldRechargeRate</code> ===<br />
'''forwardShieldRechargeRate''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)<br />
The rate at which the forward shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, but this is no longer the case in 1.81<br />
<br />
'''See also''': <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#forwardShield|forwardShield]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code><br />
<br />
=== <code>fuelLeakRate</code> ===<br />
'''fuelLeakRate''' : Number (read/write)<br />
The rate at which the player is losing fuel, in tenths of a LY per second. May not be negative. Reset to 0 when fuel is empty.<br />
<br />
=== <code>galacticHyperspaceBehaviour</code> ===<br />
'''galacticHyperspaceBehaviour''' : String (read/write)<br />
A string indicating what the effect of a galactic hyperspace jump will be. The available options are:<br />
* <code>"BEHAVIOUR_STANDARD"</code>: the player arrives in the closest system to the starting point that is part of the main group of stars. Small groups (as seen in [[Oolite planet list/Galaxy 6|galaxy 6]], among others) can’t be reached.<br />
* <code>"BEHAVIOUR_ALL_SYSTEMS_REACHABLE"</code>: The player arrives at the closest system to the starting point, even if it is in a small group. '''Important:''' this can leave the player stranded, unless there are missions providing the possibility of escape!<br />
* <code>"BEHAVIOUR_FIXED_COORDINATES"</code>: The player arrives at the system closest to <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>.<br />
<br />
'''See also:''' <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code><br />
<br />
=== <code>galacticHyperspaceFixedCoords</code> ===<br />
'''galacticHyperspaceFixedCoords''' : [[Oolite JavaScript Reference: Vector3D|Vector3D]] (read/write)<br />
'''Discouraged in favour of <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>.'''<br /><br />
Like <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>, but in the internal coordinate system.<br />
<br />
=== <code>galacticHyperspaceFixedCoordsInLY</code> ===<br />
'''galacticHyperspaceFixedCoordsInLY''' : [[Oolite JavaScript Reference: Vector3D|Vector3D]] (read/write)<br />
The destination coordinates when <code>[[#galacticHyperspaceBehaviour|galacticHyperspaceBehaviour]]</code> mode is <code>"GALACTIC_HYPERSPACE_BEHAVIOUR_FIXED_COORDINATES"</code>. The coordinate system corresponds to <code>[[#galaxyCoordinatesInLY|galaxyCoordinatesInLY]]</code>. Currently, when assigning a value its <code>x</code> and <code>y</code> coordinates will be rounded to integer internal coordinates, and the <code>z</code> coordinate will be rejected.<br />
<br />
'''See also:''' <code>[[#galacticHyperspaceBehaviour|galacticHyperspaceBehaviour]]</code><br />
<br />
=== <code>galaxyCoordinates</code> ===<br />
'''galaxyCoordinates''' : Vector3D (read-only)<br />
'''Discouraged in favour of <code>[[#galaxyCoordinatesInLY|galaxyCoordinatesInLY]]</code>.'''<br /><br />
The player’s location in galactic space, in the internal coordinate system. The <code>z</code> coordinate is always 0.<br />
<br />
=== <code>galaxyCoordinatesInLY</code> ===<br />
'''galaxyCoordinatesInLY''' : Vector3D (read-only)<br />
The player’s location in galactic space, in light years (measured from the top left of the map). The <code>z</code> coordinate is always 0.<br />
<br />
=== <code>hud</code> ===<br />
'''hud''' : String (read/write)<br />
The name of the [[hud.plist|HUD plists]] defining the ship’s head up display.<br />
<br />
=== <code>hudHidden</code> ===<br />
'''hudHidden''' : Boolean (read/write)<br />
Whether the HUD should be visible.<br />
<br />
=== <code>hyperspaceSpinTime</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''hyperspaceSpinTime''' : Number (read-only, read/write in 1.81)<br />
The length of the ship's hyperspace countdown.<br />
<br />
Setting this to a negative value disables the drive entirely.<br />
<br />
=== <code>injectorsEngaged</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorsEngaged''' : Boolean(read-only)<br />
Is the player ship currently using fuel injection.<br />
<br />
=== <code>manifest</code> ===<br />
'''manifest''' : [[Oolite JavaScript Reference: Manifest|Manifest]] (read/write)<br />
The manifest contains all the cargo the player carries. It can be addressed as a property of playerShip as well as a class [[Oolite JavaScript Reference: Manifest|Manifest]] of its own.<br />
<br />
=== <code>maxAftShield</code> ===<br />
'''maxAftShield''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)<br />
The highest possible value of <code>[[#aftShield|aftShield]]</code>. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#maxForwardShield|maxForwardShield]]</code>, but this is not necessarily true from 1.81.<br />
<br />
'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code><br />
<br />
=== <code>maxForwardShield</code> ===<br />
'''maxAftShield''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)<br />
The highest possible value of <code>[[#forwardShield|forwardShield]]</code>. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#maxAftShield|maxAftShield]]</code>, but this is not necessarily true from 1.81.<br />
<br />
'''See also''': <code>[[#forwardShield|forwardShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code><br />
<br />
=== <code>missilesOnline</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''missilesOnline''' : Boolean (read-only)<br />
True if the ship's targeting system is currently in missile targeting mode, false if it is currently in identification mode.<br />
<br />
=== <code>multiFunctionDisplayList</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''multiFunctionDisplayList''' : Array (read-only, strings)<br />
The IDs of the currently active multi-function displays<br />
<br />
e.g.<br />
[null, "myoxp_mfd1"] // My OXP MFD1 in the second display, first display blank<br />
<br />
=== <code>multiFunctionDisplays</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''multiFunctionDisplays''' : Number (read-only, integer)<br />
The number of multi-function displays available on the current HUD.<br />
<br />
=== <code>price</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''price''' : Number (read-only, positive integer in decicredits)<br />
The value the player's ship would have, including equipment, if in a perfect servicing state. The ship can be exchanged at a shipyard for 75% of this value if it really is in perfect servicing state.<br />
<br />
=== <code>renovationCost</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''renovationCost''' : Number (read-only, positive integer in decicredits)<br />
The current price in decicredits to service the ship. Depending on the [[#serviceLevel|serviceLevel]] it may not be possible to actually purchase renovation at this time.<br />
<br />
=== <code>renovationMultiplier</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''renovationMultiplier''' : Number (read-only, positive)<br />
The multiplier applied to the base cost of renovation (<code>renovationCost</code> already includes this multiplier) to allow for some ships being more difficult to maintain than others. The default is 1.0 - other values are set in [[Shipyard.plist#renovation_multiplier|shipyard.plist]]<br />
<br />
=== <code>reticleTargetSensitive</code> ===<br />
'''reticleTargetSensitive''' : Boolean (read/write)<br />
If true, and Scanner Targeting Enhancement is installed, the selected target reticle will light up in red when the target is in the player’s sights. This is equivalent to the <code>reticle_target_sensitive</code> key in [[hud.plist|HUD plists]].<br />
<br />
=== <code>scannerNonLinear</code> ===<br />
'''scannerNonLinear''' : Boolean (read/write)<br />
If <code>true</code>, the scanner is operating in non-linear mode. This property will be reset to the HUD default if the HUD is changed.<br />
<br />
=== <code>scannerUltraZoom</code> ===<br />
'''scannerUltraZoom''' : Boolean (read/write)<br />
If <code>true</code>, the scanner has 1x, 2x, 4x, 8x and 16x zoom modes, rather than the conventional 1x, 2x, 3x, 4x and 5x. This property will be reset to the HUD default if the HUD is changed.<br />
<br />
=== <code>scoopOverride</code> ===<br />
'''scoopOverride''' : Boolean (read/write)<br />
If <code>true</code>, and the player has a fuel scoop, the fuel scoop effect will run even if not close to a sun or scooping cargo.<br />
<br />
=== <code>serviceLevel</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''serviceLevel''' : Number (read/write, positive integer in range 75-100)<br />
The level of servicing the player's ship has. Renovation will be offered in shipyards at 85 or below, and malfunctions are more likely at lower values. This affects the sales price of the ship.<br />
<br />
=== <code>specialCargo</code> ===<br />
'''specialCargo''' : String (read-only)<br />
The special cargo the player is carrying, if any; otherwise <code>null</code>.<br />
<br />
'''See also''': <code>[[#useSpecialCargo|useSpecialCargo]]()</code><br />
<br />
=== <code>targetSystem</code> ===<br />
'''targetSystem''' : Integer (read-only, sometimes read/write in 1.77)<br />
The ID of the selected hyperspace target system. In 1.77, it can be written to if the player's ship is docked.<br />
<br />
=== <code>torusEngaged</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''torusEngaged''' : Boolean(read-only)<br />
Is the player ship currently using torus drive<br />
<br />
=== <code>viewDirection</code> ===<br />
'''viewDirection''' : String (read-only)<br />
Returns the view direction as string: <code>"VIEW_FORWARD"</code>, <code>"VIEW_AFT"</code>, <code>"VIEW_PORT"</code>, <code>"VIEW_STARBOARD"</code>, <code>"VIEW_CUSTOM"</code> or <code>"VIEW_GUI_DISPLAY"</code>.<br />
<br />
=== <code>viewPosition*</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''viewPositionAft''' : Vector (read-only)<br />
'''viewPositionForward''' : Vector (read-only)<br />
'''viewPositionPort''' : Vector (read-only)<br />
'''viewPositionStarboard''' : Vector (read-only)<br />
The ship's 4 point-of-view positions in XYZ relative to the model. The corresponding ''[[shipdata.plist]]'' keys start with <code>view_position_</code>.<br />
<br />
=== <code>weaponsOnline</code> ===<br />
'''weaponsOnline''' : Boolean (read-only)<br />
Returns the weapon safety status. Player can toggle the status with the underscore-key.<br />
<br />
== Methods ==<br />
=== <code>addParcel</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''addParcel'''(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean<br />
Add a parcel contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.<br />
<br />
Returns <code>false</code> when there is already a parcel with that name or the arrival time is invalid.<br />
<br />
The <code>advance</code> and <code>risk</code> parameters were added in Oolite 1.79. <code>advance</code> is purely advisory and describes any up-front payment given for the parcel. <code>risk</code> can be 0, 1 or 2 - the higher the number, the more likely that assassins are likely to try to kill the player while they carry this parcel.<br />
<br />
=== <code>addPassenger</code> ===<br />
function '''addPassenger'''(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean<br />
Add a passenger contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.<br />
<br />
Returns <code>false</code> when there is no room for the passenger, there is already a passenger with that name or the arrival time is invalid.<br />
<br />
'''Example:'''<br />
player.ship.addPassenger("cmdr Jameson", 34, 67, clock.seconds+3*24*3600, 1500);<br />
<br />
If successful - and in galaxy chart 1 - the player will have cmdr Jameson as a passenger, his documents will show that he boarded the ship at Inus, to go to Cemave, within exactly 3 days, and the player will be given 1500 credits if he gets there on time (early or late arrival will affect the amount paid).<br />
<br />
'''N.B.''' Normally a passenger will pay the captain a small advance upon boarding. Using this method, no initial payment is made. In versions after 1.77, an optional parameter can be added to describe what the advance ''was'', without actually making it.<br />
<br />
The risk parameter was added in Oolite 1.79. <code>risk</code> can be 0, 1 or 2 - the higher the number, the more likely that assassins are likely to try to kill the player while they carry this passenger.<br />
<br />
=== <code>awardContract</code> ===<br />
function '''awardContract'''(quantity : Number, commodity : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, premium : Number]) : Boolean<br />
Add a cargo contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.<br />
<br />
Returns <code>false</code> when there is no room for the cargo, the arrival time is invalid.<br />
<br />
'''Example:'''<br />
player.ship.awardContract(12, "Food", 34, 67, clock.seconds+7*24*3600, 5000)<br />
<br />
If successful - and in galaxy chart 1 - the player will have 12 more food containers on board, the manifest will show that the cargo was picked up at Inus, to be delivered at Cemave, within exactly 7 days, and the player will be given 5000 credits if the cargo is delivered on time (early or late delivery will affect the amount paid).<br />
<br />
'''N.B.''' Normally to get a contract, the player will have to pay a deposit similar in value to the cargo. Using this method, no deposit payment is made. In versions after 1.77, an optional parameter can be added to describe what the deposit payment ''was'', without actually making it.<br />
<br />
=== <code>awardEquipmentToCurrentPylon</code> ===<br />
function '''awardEquipmentToCurrentPylon'''(item : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Replace the missile or mine currently being launched with the specified item (which must be an external store). This will only have an effect if called while a missile or mine is being launched. Effectively this means that this method must be used within the <code>shipFiredMissile()</code> handler or in the ENTER message of the GLOBAL state of an missileAI.plist.<br />
<br />
'''Bug:''' In Oolite 1.74.0, if <code>awardEquipmentToCurrentPylon()</code> fails the script will be halted without any error message. In future versions, it will simply return <code>false</code>.<br />
<br />
'''See also:''' <code>[[Oolite JavaScript Reference: Ship#awardEquipment|Ship.awardEquipment()]]</code><br />
<br />
=== <code>beginHyperspaceCountdown</code> ===<br />
{{oolite-method-added|1.77}}<br />
function beginHyperspaceCountdown( [ length : Number ] ) : Boolean<br />
This function begins the witchspace sequence for the player ship. It returns true if the sequence is started successfully, and false otherwise (no destination selected, insufficient fuel, out of range, etc.). Optionally, the length of the countdown can be varied. Values between 5 and 60 seconds are accepted. If this parameter is omitted the default sequence length for this class of ship will be used.<br />
<br />
'''See also:''' <code>[[#cancelHyperspaceCountdown|cancelHyperspaceCountdown]]</code><br />
<br />
=== <code>cancelHyperspaceCountdown</code> ===<br />
{{oolite-method-added|1.77}}<br />
function cancelHyperspaceCountdown() : Boolean<br />
This function cancels the witchspace sequence for the player ship. It returns true if there was an ongoing sequence to cancel, and false otherwise.<br />
<br />
'''See also:''' <code>[[#beginHyperspaceCountdown|beginHyperspaceCountdown]]</code><br />
<br />
=== <code>disengageAutopilot</code> ===<br />
function disengageAutopilot()<br />
Disenable autopilot.<br />
<br />
'''See also:''' <code>[[#engageAutopilotToStation|engageAutopilotToStation()]]</code><br />
<br />
=== <code>engageAutopilotToStation</code> ===<br />
function engageAutopilotToStation(station : [[Oolite JavaScript Reference: Station|Station]]) : Boolean<br />
Engage autopilot, set to dock with the specified station.<br />
<br />
'''See also:''' <code>[[#disengageAutopilot|disengageAutopilot()]]</code><br />
<br />
=== <code>hideHUDSelector</code> ===<br />
{{oolite-method-added|1.79}}<br />
function hideHUDSelector(selector : String)<br />
Hide all dials using the specified selector on the HUD display. For example<br />
<br />
player.ship.hideHUDSelector("drawScanner:");<br />
<br />
'''See also:''' <code>[[#showHUDSelector|showHUDSelector()]]</code><br />
<br />
=== <code>launch</code> ===<br />
function '''launch'''()<br />
Launches the player’s ship if it is currently docked.<br />
<br />
=== <code>removeAllCargo</code> ===<br />
function '''removeAllCargo'''()<br />
Removes all cargo from the ship’s cargo bay that are measured in tons. Does not affect Gold, Platinum or Gemstones. Can only be used while docked.<br />
<br />
=== <code>removeContract</code> ===<br />
function '''removeContract'''(commodity : String, destination : Number)<br />
Remove the cargo contract matching that commodity and destination.<br />
<br />
=== <code>removeParcel</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''removeParcel'''(name : String)<br />
Remove a named parcel.<br />
<br />
=== <code>removePassenger</code> ===<br />
function '''removePassenger'''(name : String)<br />
Remove a named passenger.<br />
<br />
=== <code>resetCustomView</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''resetCustomView'''()<br />
Resets the custom view back to the last-used setting defined in [[shipdata.plist]]<br />
<br />
This function gives an error if used when the custom view camera is not selected.<br />
<br />
=== <code>resetScannerZoom</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''resetScannerZoom'''()<br />
Resets the scanner zoom back to 1:1<br />
<br />
=== <code>setCustomView</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''setCustomView'''(Vector : position, Quaternion : orientation [,WeaponDirection weapon])<br />
Set the position and orientation of the custom view camera to those specified. As with the custom views specified through [[shipdata.plist]], these are relative to the player's ship's position, and the coordinate frame defined by the ship's forward, right and up Vectors.<br />
<br />
The optional weapon parameter can be "FORWARD", "AFT", "PORT" or "STARBOARD" and sets the active weapon accordingly. If omitted, the active weapon for the previous custom view will be preserved.<br />
<br />
This function gives an error if used when the custom view camera is not selected. Setting the custom view does not affect the custom views defined in [[shipdata.plist]], which will be switched back to the next time 'v' is pressed, or when [[#resetCustomView|resetCustomView]] is called.<br />
<br />
=== <code>setCustomHUDDial</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''setCustomHUDDial'''(key : String, value : Value)<br />
Sets the custom HUD dial [[hud.plist#data_source|data source]] 'key' to the specified value. Different types of custom HUD dial will expect different types of values; a value of an incorrect type will be converted if possible.<br />
<br />
=== <code>setMultiFunctionDisplay</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setMultiFunctionDisplay'''(index : Number, key : String) : Boolean<br />
Sets the multi-function display with the specified number to display the given multi-function display <code>key</code> set earlier with [[#setMultiFunctionText|setMultiFunctionText()]]. Multi-function displays are numbered from 0 to [[#multiFunctionDisplays|multiFunctionDisplays]]-1. If the index given is outside this range, the first unused multi-function display will be used, or the function will return <code>false</code> if all are currently in use.<br />
Example:<br />
// picks first unused one<br />
player.ship.setMultiFunctionDisplay(player.ship.multiFunctionDisplays, "myOxp_mfd");<br />
<br />
As the player can cycle the contents of their displays between the various active keys themselves using keyboard controls, it is advisable not to call this function to override a specific display except in emergencies, as this is likely to annoy the player.<br />
<br />
=== <code>setMultiFunctionText</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setMultiFunctionText'''(key : String [, contents : String [, reflow : Boolean]])<br />
Set the text for the multi-function display with the specified <code>key</code> to be <code>contents</code>. The limit on space for a multi-function display is ten lines of text, each 15 blocks wide. <br />
<br />
If you specify the optional <code>reflow</code> parameter, then the text given will automatically be fitted into the available space, with any extra discarded. Otherwise, line-breaks will not be added automatically, so you must enter them into <code>contents</code> yourself. If any individual line is more than 15 blocks long, the text will be compressed to fit it into the available space. This looks bad and is best avoided.<br />
<br />
=== <code>showHUDSelector</code> ===<br />
{{oolite-method-added|1.79}}<br />
function showHUDSelector(selector : String)<br />
Show all dials using the specified selector on the HUD display if they were previously hidden. For example<br />
<br />
player.ship.showHUDSelector("drawScanner:");<br />
<br />
'''See also:''' <code>[[#hideHUDSelector|hideHUDSelector()]]</code><br />
<br />
=== <code>takeInternalDamage</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''takeInternalDamage'''()<br />
Causes the player ship to potentially take "internal damage". Internal damage can also be caused by hits on the hull and some witchdrive malfunctions, and this function uses the same algorithm to determine the damage taken, which can be:<br />
* damage to cargo<br />
* damage to equipment (according to the damage_probability)<br />
* reduction in [[#serviceLevel|service level]]<br />
* no damage<br />
The function will return 'false' if "no damage" was selected, and 'true' otherwise. The relative probabilities of the three options vary depending on the size of the player ship, its cargo capacity, cargo carried and installed equipment.<br />
<br />
=== <code>useSpecialCargo</code> ===<br />
function '''useSpecialCargo'''(description : String)<br />
Fills the cargo bay with the cargo described, effectively disabling the use of the cargo bay until the cargo is removed.<br />
<br />
'''See also''': <code>[[#specialCargo|specialCargo]]</code><br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Shipdata.plist&diff=47151Shipdata.plist2015-04-03T14:26:18Z<p>Cim: /* show_damage */ new property</p>
<hr />
<div>'''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:<br />
<br />
<br />
= Ship keys=<br />
The following keys are used by all ships<br />
==accuracy==<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Example:<br />
"accuracy" = 8.3;<br />
<br />
== aft_eject_position ==<br />
Determines the XYZ point on the model from which cargo is ejected.<br />
<br />
Example:<br />
"aft_eject_position" = "0.0 -4.5 -23.0";<br />
<br />
== aft_weapon_type ==<br />
Assigns the ship's aft laser. <br />
Any weapon type from the [[equipment.plist]] can be used (and WEAPON_NONE). <br />
<br />
Example:<br />
"aft_weapon_type" = "WEAPON_BEAM_LASER";<br />
<br />
== ai_type ==<br />
Assigns an AI to the entity. This may be a previously existing AI, or one custom made for the occasion.<br />
<br />
Example:<br />
"ai_type" = "pirateAI.plist";<br />
<br />
== auto_ai ==<br />
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.<br />
Example:<br />
"auto_ai" = yes;<br />
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.<br />
<br />
== auto_weapons ==<br />
Added in 1.79<br />
<br />
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.<br />
<br />
Example:<br />
"auto_weapons" = yes;<br />
<br />
== beacon ==<br />
A special feature for beacons and navigation aids.<br />
The string can be anything - the first letter is what's displayed in the advanced space compass.<br />
<br />
Example: <br />
"beacon" = "X";<br />
<br />
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.<br />
<br />
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].<br><br />
Example in shipdata:<br />
"beacon" = "fuelStation_location";<br />
Example in descriptions.plist<br />
"fuelStation_location" = (1, 2, -3, 2, -3, -4, 3, -4, 3, 4, -3, 4, -3, 3, 2, 3, 2, -3, 1, -3 );<br />
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.<br />
<br />
== beacon_label ==<br />
(1.79 or later)<br />
<br />
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<br />
"beacon_label" = "%H Station"; // Lave Station, Diso Station, etc.<br />
<br />
== bounty ==<br />
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.<br />
<br />
Example:<br />
"bounty" = 50;<br />
<br />
== cargo_carried ==<br />
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.<br />
<br />
Example:<br />
"cargo_carried" = "Gold";<br />
<br />
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.<br><br />
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.)<br><br />
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)<br />
<br />
== [[cargo_type]] ==<br />
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.)<br><br />
<br />
Example:<br />
"cargo_type" = "CARGO_RANDOM";<br />
<br />
Will create random cargo, often based on availability in the system. When you want fixed cargo you can use:<br />
<br />
Example:<br />
"cargo_type" = "CARGO_CARRIED";<br />
"cargo_carried" = "4 Gold";<br />
<br />
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]].<br />
<br />
Example:<br />
"cargo_type" = "CARGO_NOT_CARGO";<br />
"cargo_carried" = "Computers";<br />
<br />
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.<br><br />
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.<br />
<br />
== cloak_automatic ==<br />
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) Key added with Oolite 1.75<br />
<br />
Example:<br />
"cloak_automatic" = no;<br />
<br />
== cloak_passive ==<br />
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) <br />
<br />
Example:<br />
"cloak_passive" = yes;<br />
<br />
==conditions==<br />
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.<br />
<br />
Example:<br />
"conditions" = (<br />
"systemGovernment_number equal 3",<br />
"systemEconomy_number lessthan 4"<br />
);<br />
<br />
==condition_script==<br />
''Available from Oolite 1.77 onwards''<br />
<br />
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.<br />
<br />
Example:<br />
"condition_script" = "myoxp_conditions.js";<br />
<br />
== counts_as_kill ==<br />
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. Key is added with Oolite 1.75<br />
<br />
Example:<br />
"counts_as_kill" = no;<br />
<br />
== custom_views==<br />
Will add the ability to display custom POVs of the player ship, in game toggled by pressing '''v'''. <br />
<br />
This is an array with any number of entries, one for each view, each with:<br />
*a '''view_description''' - giving a textual description of the view. <br />
*a '''view_position''' - relative to the origin of the ship model. <br />
*a '''view_orientation''' - this is a [[Quaternions|quaternion]] expressing a rotation from directly forwards. <br />
*a '''weapon_facing''' - FORWARD, AFT, PORT or STARBOARD. The weapon that will fire when that view is selected.<br />
<br />
The view_position is best chosen by selecting a facet, line or point in Wings and copying down the coordinates. <br />
<br />
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: <br />
<br />
W = the cosine of half the angle rotated about the axis xyz<br /><br />
X = the sine of half the angle rotated about xyz, multiplied by x<br /><br />
Y = the sine of half the angle rotated about xyz, multiplied by y <br /><br />
Z = the sine of half the angle rotated about xyz, multiplied by z <br /><br />
<br />
Four decimal places are probably enough accuracy for these values.<br />
<br />
Example:<br />
custom_views =<br />
(<br />
{<br />
view_description = "Front View";<br />
view_orientation = "0.0 0.0 1.0 0.0";<br />
view_position = "0.0 30.0 200.0";<br />
weapon_facing = "FORWARD";<br />
}<br />
);<br />
<br />
== death_actions ==<br />
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.<br />
<br />
Example:<br />
"death_actions" = ("spawn: explosive_shrapnel 1");<br />
<br />
== debris_role ==<br />
Specifies the kind of debris an asteroid or boulder generates. When not defined they default to generating 'ships' with role "boulder" or "splinter". (Key added with Oolite 1.74)<br />
<br />
Example:<br />
"debris_role" = "my_boulder_foo";<br />
<br />
== density ==<br />
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.<br />
<br />
Ship's mass does not affect its flight under the non-inertial engines - see [[#thrust|thrust]]. It does affect:<br />
* changes in momentum, and damage done, in a collision<br />
* 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)<br />
* the length of time a witchspace wormhole opened by this ship will remain open, and the radius of that wormhole.<br />
<br />
Example:<br />
"density" = 1.5;<br />
<br />
== display_name ==<br />
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.<br />
<br />
Example:<br />
"display_name" = "ExampleShip Mark IX";<br />
<br />
== energy_recharge_rate ==<br />
The rate at which energy is replenished. Stations are at 100, Adders at 2. (Default value: 1)<br />
<br />
Example:<br />
"energy_recharge_rate" = "3.5";<br />
<br />
== escape_pod_model ==<br />
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).<br />
<br />
Example:<br />
"escape_pod_model" = "custom_pod";<br />
<br />
== escorts ==<br />
Determines how many escorts an NPC shall have. Maximum is 16.<br />
<br />
Example:<br />
"escorts" = 4;<br />
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.<br><br />
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. <br />
<br />
== escort_role ==<br />
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.)<br />
<br />
Example:<br />
"escort_role" = "my_custom_escort_role";<br />
Escort ships will use the escortAI.plist unless "auto_ai" is set to false.<br />
<br />
<br />
==escort_roles==<br />
''Available from Oolite 1.79 onwards''<br />
<br />
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.<br />
<br />
escort_roles = (<br />
{ role = "escort"; min = -2; max = 2; },<br />
{ role = "escort-medium"; min = 0; max = 4; },<br />
{ role = "escort-heavy"; min = -4; max = 2; },<br />
{ role = ""; min = 0; max = 2; } // spare slots for wandering escorts<br />
);<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
== escort_ship ==<br />
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.)<br />
<br />
Example:<br />
"escort_ship" = "cobramk1";<br />
Escort ships will use the escortAI.plist unless "auto_ai" is set to false.<br />
<br />
In Oolite 1.77 and later it is also possible to use <code>"escort_role" = "[cobramk1]"</code><br />
<br />
== exhaust ==<br />
The XYZ position(s) of exhaust plume(s), and the XYZ of the plume shape, ergo<br />
<br />
x y z width height length<br />
<br />
'''x y z''' is the position relative to the origin of the main model. <br />
<br />
'''width''' in meters, how far a plume extends on x axis, on each side of plume position. (x radius)<br />
<br />
'''height''' in meters, how far a plume extends on y axis, above and below of plume position. (y radius)<br />
<br />
'''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)<br />
<br />
<br />
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)<br />
<br />
Example:<br />
"exhaust" = (<br />
"5 0.0 -25 3.0 2.0 10.0",<br />
"-5 0.0 -25 3.0 2.0 10.0"<br />
);<br />
<br />
== explosion_type ==<br />
In Oolite 1.81 or later, a list of [[explosions.plist]] entries describing how the ship explodes if destroyed.<br />
<br />
Example:<br />
"explosion_type" = ("oolite-default-asteroid-explosion");<br />
<br />
== extra_cargo ==<br />
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.<br />
<br />
Example:<br />
"extra_cargo" = 25;<br />
<br />
== forward_weapon_type ==<br />
Assigns the ship's forward laser. <br />
Any weapon type from the [[equipment.plist]] can be used.<br> e.g.: WEAPON_PULSE_LASER, WEAPON_BEAM_LASER, WEAPON_MILITARY_LASER, WEAPON_MINING_LASER, WEAPON_PLASMA_CANNON, WEAPON_THARGOID_LASER and WEAPON_NONE. <br />
<br />
Example:<br />
"forward_weapon_type" = "WEAPON_BEAM_LASER";<br />
<br />
== frangible ==<br />
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. <br />
If set to false, the object plus subentities will be regarded as a single object.<br />
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.<br />
<br />
Example:<br />
"frangible" = no;<br />
<br />
== fragment_chance ==<br />
Determines if a ship breaks apart into fragments and generates parts with role "wreckage". By chance factor, or true/false. Default is 90% chance.<br />
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)<br />
<br />
Example:<br />
"fragment_chance" = no;<br />
<br />
== fuel ==<br />
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)<br />
<br />
Example:<br />
"fuel" = 70;<br />
<br />
== has_cloaking_device ==<br />
Determines if a ship has a cloacking device installed. By chance factor, or true/false.<br />
<br />
Example:<br />
"has_cloaking_device" = 0.5;<br />
<br />
== has_ecm ==<br />
Determines if a ship has the E.C.M system installed. By chance factor, or true/false.<br />
<br />
Example:<br />
"has_ecm" = 0.5;<br />
or<br />
"has_ecm" = no;<br />
<br />
== has_energy_bomb ==<br />
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.<br>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.<br />
<br />
Example: <br />
"has_energy_bomb" = yes;<br />
<br />
== has_escape_pod ==<br />
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.<br />
<br />
Examples:<br />
has_escape_pod = no;<br />
has_escape_pod = 0.75;<br />
has_escape_pod = 3;<br />
<br />
== has_fuel_injection ==<br />
Determines if a ship has the witchdrive fuel injector.<br />
<br />
Example:<br />
"has_fuel_injection" = 0.99;<br />
<br />
==has_military_jammer==<br />
Determines if a ship has a military jammer. Ships equipped with this item become invisible on the radar. <br />
Example:<br />
"has_military_jammer" = 0.75;<br />
<br />
==has_military_scanner_filter==<br />
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. <br />
Example:<br />
"has_military_scanner_filter" = 0.50;<br />
<br />
== has_scoop ==<br />
Determines if a ship has a fuel/cargo scoop.<br />
<br />
Example:<br />
"has_scoop" = no;<br />
<br />
== has_scoop_message ==<br />
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)<br />
<br />
Example:<br />
"has_scoop_message" = no;<br />
<br />
== has_shield_booster==<br />
Determines if a ship has the shield booster. (enlarges max energy with 256)<br />
<br />
Example:<br />
"has_shield_booster" = 0.80;<br />
<br />
== has_shield_enhancer ==<br />
Determines if a ship has the coveted shield enhancer. (enlarges max energy with 256 and raises energy recharge rate with 50%)<br />
<br />
Example:<br />
"has_shield_enhancer" = 0.45;<br />
<br />
== heat_insulation ==<br />
This real number gives the amount of heat insulation of a ship. Default is 1.0 Only for NPC ships. Playes ships can have the equipment EQ_HEAT_SHIELDING with gives the player than a heat_insulation of 2.0<br />
<br />
Example:<br />
"heat_insulation" = "2.0";<br />
<br />
== hud ==<br />
Used for a playership, to assign another HUD than the default one.<br />
<br />
Example:<br />
"hud" = "specialhud.plist";<br />
<br />
== hyperspace_motor ==<br />
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)<br />
<br />
Examples:<br />
"hyperspace_motor" = no;<br />
<br />
hyperspace_motor=NO;<br />
<br />
== hyperspace_motor_spin_time ==<br />
Used to modify jump countdown time. Default = 15.<br />
<br />
Examples:<br />
"hyperspace_motor_spin_time" = "15";<br />
<br />
==injector_burn_rate==<br />
The default fuel burn rate of injectors on this ship, in deci-LY per second. The default is 0.25.<br />
<br />
"injector_burn_rate" = 0.25;<br />
<br />
Added in Oolite 1.81<br />
<br />
==injector_speed_factor==<br />
The multiplier applied to the ship's maximum speed when it is using injectors. The default is 7.<br />
<br />
"injector_speed_factor" = 7;<br />
<br />
Added in Oolite 1.81<br />
<br />
==is_external_dependency==<br />
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.<br>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.<br />
<br />
Example:<br />
"is_external_dependency" = yes;<br />
<br />
==is_submunition==<br />
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.<br />
<br />
Example:<br />
"is_submunition" = yes;<br />
<br />
==is_template==<br />
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.<br />
<br />
Example:<br />
"is_template" = yes;<br />
<br />
== laser_color ==<br />
Determines a ship's laser colour.<br />
<br />
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.<br />
<br />
Example:<br />
"laser_color" = "cyanColor"<br />
<br />
<br />
== launch_actions ==<br />
Triggers a script on the entity just after setup, also when called by spawn and addShip methods.<br />
Can be used to change to a custom AI, when a ship is generated by standard role. <br />
[[Shipdata.plist#script_actions|script_actions]]<br />
<br />
Example:<br />
"role = trader";<br />
"launch_actions" = (<br />
"setAITo: pirateAI.plist"<br />
);<br />
<br />
<br />
== like_ship ==<br />
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.<br />
<br />
Works well together with the [[#is_template|is_template]]-key.<br />
<br />
Example:<br />
"my_ship" = {<br />
"like_ship" = "adder";<br />
"max_flight_speed" = "700";<br />
"name" = "Freak Turbo Adder";<br />
},<br />
<br />
== likely_cargo ==<br />
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.<br />
<br />
Example:<br />
"likely_cargo" = "2";<br />
<br />
== materials ==<br />
See [[Materials in Oolite]].<br />
<br />
<br />
== max_cargo ==<br />
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.<br />
<br />
Example:<br />
"max_cargo" = "5";<br />
<br />
== max_energy ==<br />
Sets the ship's energy value. (Default value: 200)<br />
<br />
Example:<br />
"max_energy" = "300";<br />
<br />
<br />
== max_flight_pitch ==<br />
Sets pitch factor. Will usually range from a sluggish 0.6 to a very sensitive 3.0<br />
<br />
Example:<br />
"max_flight_pitch" = "2.2";<br />
<br />
<br />
== max_flight_roll ==<br />
Sets roll factor. Will usually range from 0.8 to 4.6.<br />
<br />
Example:<br />
"max_flight_roll" = "4.2";<br />
<br />
<br />
== max_flight_speed ==<br />
Sets the model's top speed. Interceptors fly at 520 (0.52 LM), Shuttles at 80.<br />
<br />
Example:<br />
"max_flight_speed" = "320";<br />
<br />
== max_flight_yaw ==<br />
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<br />
<br />
Example:<br />
"max_flight_yaw" = "2.2";<br />
<br />
== max_missiles ==<br />
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.<br />
<br />
Example:<br />
"max_missiles" = "1";<br />
<br />
== missile_launch_position ==<br />
Determines the XYZ point on the model from which a missile is launched.<br />
<br />
Example:<br />
"missile_launch_position" = "0.0 -2.25 10.0";<br />
<br />
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)<br><br />
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.<br />
<br />
== missile_load_time ==<br />
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.<br />
<br />
Example:<br />
"missile_load_time" = "2.1";<br />
<br />
<br />
== missiles ==<br />
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.<br />
<br />
Example:<br />
"missiles" = "0";<br />
<br />
== missile_role ==<br />
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.<br />
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. <br />
<br />
To assign a specific missile type to a newly bought player ship, its dependancies must be defined inside [[shipyard.plist]].<br />
<br />
Example: <br />
"missile_role" = "EQ_THARGON";<br />
<br />
== model ==<br />
Assigns the entity's corresponding '''.dat''' file that will be found with the exact same name in the ''Models'' folder.<br />
<br />
Example:<br />
"model" = "example_ship.dat";<br />
<br />
== model_scale_factor ==<br />
1.81 or later only.<br />
<br />
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.<br />
<br />
Player ships will also have their internal and external view positions multiplied by the scale factor.<br />
<br />
model_scale_factors on subentities will be ignored - the value for the main entity will be used instead.<br />
<br />
Example:<br />
"model_scale_factor" = 2.0;<br />
<br />
== name ==<br />
States the model's name as it will be known to the ID computer.<br />
<br />
Example:<br />
"name" = "ExampleShip Mark IX";<br />
<br />
== no_boulders ==<br />
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.<br />
<br />
Example:<br />
"no_boulders" = yes;<br />
<br />
== pilot ==<br />
Gives the ship a predefined pilot, defined in [[characters.plist]]. Can eject in pod, if available, and be captured.<BR><br />
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.<br />
<br />
Example:<br />
"pilot" = "constrictor-mission-thief";<br />
<br />
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)<br />
<br />
== port_weapon_type ==<br />
(Oolite 1.77 or later)<br />
Assigns the ship's port laser. <br />
Any weapon type from the [[equipment.plist]] can be used (and WEAPON_NONE). <br />
<br />
While not essential, you should generally assign the same weapon to [[#starboard_weapon_type|starboard_weapon_type]].<br />
<br />
Example:<br />
"port_weapon_type" = "WEAPON_BEAM_LASER";<br />
<br />
== roles ==<br />
Assigns which [[role]](s) the entity should have, that can correspond to one specific, exclusive use, or several.<br />
<br />
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]].<br />
<br />
'''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.<br />
<br />
Example:<br />
"roles" = "hunter(0.25) trader(2.0) pirate";<br />
<br />
or an exclusive role, simply:<br />
<br />
"roles" = "uniquely_named_role";<br />
<br />
This has the benefit of being the only ship to be selected when a [[Script.plist|script]] calls for the ''uniquely_named_role'' ship.<br />
<br />
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.<br />
<br />
Example:<br />
"roles" = "Gold";<br />
<br />
Some roles are used by the game engine to populate systems, detect and define properties. (see also the [[System Populator]])<br />
Such roles include 'thargoid', 'missile' and 'energybomb'.<br />
Externally used equipment also needs specific mention of role, for example EQ_*_MINE and EQ_*_MISSILE.<br />
<br />
== rotational_velocity ==<br />
May be applied to a sub-entity, like the following entry to the [[Shipdata.plist#subentities|subentity]] spines of the [[Weeviloid Hunter]].<br />
Takes the form of [[Quaternions|quaternions]]. The following example enables rotation around the Z-axis.<br />
<br />
Example:<br />
"rotational_velocity" = "0.707 0.0 0.0 0.707";<br />
<br />
<br />
An explaining example taken from the Oolite Bulletin board.<br />
<br />
The rotational velocity key is rotation per second. <br />
<br />
For instance, if you want to rotate once per 20 seconds around the Z axis:<br />
<br />
a = 360 ° / 20 = 18 °<br />
<br />
[x, y, z] = [0, 0, 1]<br />
<br />
sin a ˜ 0.30902<br />
<br />
cos a ˜ 0.95106<br />
<br />
Q = (0.95106, 0, 0, 0.30902)<br />
<br />
'''shipdata.plist entry:'''<br />
"rotational_velocity"="0.95106 0.0 0.0 0.30902";<br />
<br />
== scan_class ==<br />
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.<br />
* CLASS_BUOY - green/yellow on scanner, will rotate in idle state, does not masslock<br />
* CLASS_CARGO - white on scanner, can be scooped, does not masslock<br />
* CLASS_MILITARY - purple on scanner, better pilots, will not attack other military ships, flashes purple/magenta if hostile to player<br />
* CLASS_MISSILE - cyan on scanner, will not avoid collisions<br />
* 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<br />
* CLASS_ROCK - white on scanner, launched defense ships do not inherit scan class, does not masslock<br />
* CLASS_STATION - green on scanner, launched defense ships do not inherit scan class<br />
* CLASS_THARGOID - green/red on scanner, considered hostile to any non-thargoid ship<br />
* CLASS_NO_DRAW - invisible on scanner, cannot be targeted by missiles, does not masslock<br />
* CLASS_MINE - red/yellow on scanner, automatically set on mines launched by player to override existing scan class, does not masslock<br />
(This property was called "scanClass" before Oolite 1.74.)<br />
Scan classes marked as "does not masslock" will masslock the player anyway if they are hostile to the player (as condition will be Red)<br />
<br />
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.<br />
<br />
Example:<br />
"scan_class" = "CLASS_ROCK";<br />
<br />
==== Developer Note ====<br />
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!<br />
<br />
== scan_description ==<br />
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.<br />
<br />
"scan_description" = "Unclaimed rock";<br />
<br />
Added in Oolite 1.81<br />
<br />
== scanner_display_color1 ==<br />
Overrides the color that would normally be set by scanClass.<br />
<br />
Example:<br />
"scanner_display_color1" = "greenColor";<br />
<br />
== scanner_display_color2 ==<br />
Overrides the color that would normally be set by scanClass. If this is set, the ship will flash between the two colours.<br />
<br />
Example:<br />
"scanner_display_color2" = "redColor";<br />
<br />
== scanner_hostile_display_color1 ==<br />
(1.81 or later)<br />
<br />
Overrides the color that would normally be set by scanClass when the ship is hostile and targeting the player.<br />
<br />
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.<br />
<br />
Example:<br />
"scanner_hostile_display_color1" = "greenColor";<br />
<br />
== scanner_hostile_display_color2 ==<br />
(1.81 or later)<br />
<br />
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.<br />
<br />
Example:<br />
"scanner_hostile_display_color2" = "redColor";<br />
<br />
== scanner_range ==<br />
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.<br />
<br />
Example:<br />
"scanner_range" = "25600";<br />
<br />
== scoop_position ==<br />
Determines the XYZ point on the model from which cargo is scooped. (default is 0,0,0)<br />
<br />
Example:<br />
"scoop_position" = "0.0 -4.5 -23.0"<br />
<br />
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.<br />
<br />
== script ==<br />
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.<br />
<br />
== script_info ==<br />
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.<br><br />
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.<br />
<br />
A short overview about used [[OXP_scriptInfo|script_info keys in OXPs]].<br />
<br />
== script_actions ==<br />
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.<br />
<br />
Example:<br />
"script_actions" =<br />
(<br />
"testForEquipment: EQ_CLOAKING_DEVICE",<br />
{<br />
"conditions"<br />
(<br />
"foundEquipment_bool equal NO"<br />
)<br />
"do"<br />
(<br />
"awardEquipment: EQ_CLOAKING_DEVICE"<br />
)<br />
"else"<br />
(<br />
"awardCargo: 100 Gold"<br />
)<br />
}<br />
);<br />
<br />
== setup_actions ==<br />
Arranges a process that may be necessary for some objects, like ball turrets.<br />
<br />
Example:<br />
"setup_actions" =<br />
(<br />
"initialiseTurret"<br />
);<br />
<br />
<br />
== shaders ==<br />
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.<br />
<br />
== ship_name ==<br />
Added in 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.<br />
<br />
== ship_class_name ==<br />
Added in 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.<br />
<br />
== show_damage ==<br />
Added in 1.81. Whether to show sparks and other damage effects when this ship is hit.<br />
<br />
Defaults to on if energy recharge rate is greater than zero, off otherwise, for compatibility with previous hard-coded behaviour.<br />
<br />
== smooth ==<br />
Determines if the model will use glLightModel(GL_FLAT) or glLightModel(GL_SMOOTH).<br />
<br />
If true, then lighting effects will be interpolated across the polygons of the model, giving a more 'rounded' effect.<br />
<br />
Asteroids, Boulders and Splinters use this effect as do some other models.<br />
<br />
Example:<br />
"smooth" = yes;<br />
<br />
== spawn ==<br />
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.<br />
<br />
Example<br />
"spawn"<br />
{<br />
"facing_position" = "spu 0 0 0";<br />
"position" = "wpu 0 0 0.2";<br />
}<br />
<br />
<br />
== starboard_weapon_type ==<br />
(Oolite 1.77 or later)<br />
Assigns the ship's starboard laser. <br />
Any weapon type from the [[equipment.plist]] can be used (and WEAPON_NONE). <br />
<br />
While not essential, you should generally assign the same weapon to [[#port_weapon_type|port_weapon_type]].<br />
<br />
Example:<br />
"starboard_weapon_type" = "WEAPON_BEAM_LASER";<br />
<br />
== subentities ==<br />
An array of ''subentity definitions''. A ''subentity'' is an object attached to your ship. There are several types of subentity:<br />
* ''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.<br />
* ''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.<br />
* ''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'''.<br />
* ''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.<br />
<br />
=== New-style subentity definition ===<br />
Oolite 1.73 introduced a more flexible, dictionary-based way of specifying subentities. A new-style subentity is a dictionary using the following keys:<br />
{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"<br />
|+ Subentity definition properties<br />
! Name !! Type !! Description<br />
|-<br />
| '''type''' || string || One of: “'''standard'''”, “'''ball_turret'''”, “'''flasher'''”. If not specified, “standard” is assumed.<br />
|-<br />
| '''subentity_key''' || string || The key of a ''shipdata.plist'' entry. Required for '''standard''' and '''ball_turret''' subentities, ignored for flashers.<br />
|-<br />
| '''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).<br />
|-<br />
| '''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.<br />
|-<br />
| '''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.<br />
|}<br />
<br />
{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"<br />
|+ Subentity definition properties for dock subentities (1.77 or later)<br />
! Name !! Type !! Description<br />
|-<br />
| '''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.<br />
|-<br />
| '''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.<br />
|-<br />
| '''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.<br />
|-<br />
| '''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.<br />
|}<br />
See [[Multiple Docks]] for more information on dock subentities and stations with more than one dock in Oolite 1.77 or later.<br />
<br />
{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"<br />
|+ Subentity definition properties for ball turrets<br />
! Name !! Type !! Description<br />
|-<br />
| '''fire_rate''' || number || Interval between shots in seconds, for '''ball_turret''' subentities. Default: 0.5; minimum: 0.25.<br />
|-<br />
| '''weapon_range''' || number || Range for '''ball_turret''' subentities. Default: 6000; maximum 7500.<br />
|-<br />
| '''weapon_energy''' || number || Weapon energy for '''ball_turret''' subentities. Default: 25; maximum 100.<br />
|}<br />
<br />
{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"<br />
|+ Subentity definition properties for flashers<br />
! Name !! Type !! Description<br />
|-<br />
| '''color''' || [[Materials in Oolite#Colour specifiers|colour specifier]] || Single colour for a flasher. Ignored for non-flashers. Default value: '''redColor'''.<br />
|-<br />
| '''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”.<br />
|-<br />
| '''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.<br />
|-<br />
| '''initially_on''' || boolean || Specifiers whether a flasher is turned on when created. Ignored for non-flashers. Default: yes.<br />
|-<br />
| '''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.<br />
|-<br />
| '''size''' || positive number || Diameter of a flasher in metres. Ignored for non-flashers. Default: 8. (Why 8? I don’t remember.)<br />
|-<br />
| '''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.<br />
|-<br />
|}<br />
<br />
=== Old-style subentity definition ===<br />
Prior to Oolite 1.73, this was the the only way to specify a subentity.<br />
<br />
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:<br />
<br />
==== Flashers ====<br />
For a flasher, the entry takes the form:<br />
*FLASHER* x y z hue frequency phase size<br />
''*FLASHER*'' must be precisely the string “*FLASHER*”, in capitals.<br />
<br />
''x'', ''y'' and ''z'' form the '''position'''.<br />
<br />
''hue'' specifies the [http://en.wikipedia.org/wiki/HSL_and_HSV HSV] hue component (in degrees) of '''color'''. Saturation and value are always 1.<br />
<br />
'''frequency''', '''phase''' and '''size''' are the same as in the new-style format.<br />
<br />
'''initially_on''' is false.<br />
<br />
==== Other subentities ====<br />
For a non-flasher, the entry takes the form:<br />
key x y z qw qx qy qz<br />
''key'' corresponds to '''subentity_key'''.<br />
<br />
''x'', ''y'' and ''z'' form the '''position'''.<br />
<br />
''qw'', ''qx'', ''qy'' and ''qz'' form the '''orientation'''.<br />
<br />
'''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.<br />
<br />
'''is_dock''' is implied by having the string “dock” (in lowercase) in the ''key''.<br />
<br />
== sun_glare_filter ==<br />
<br />
Added in Oolite 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)<br />
<br />
"sun_glare_filter" = 0.3;<br />
<br />
== track_contacts ==<br />
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.<br />
<br />
Example:<br />
"track_contacts" = yes;<br />
<br />
== throw_sparks ==<br />
Each new ship should start in seemingly good operating condition, unless specifically told not to. (Added with oolite 1.73, false by default)<br />
<br />
Example:<br />
"throw_sparks" = yes;<br />
<br />
== thrust ==<br />
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). <br />
<br />
Example:<br />
"thrust" = "25"<br />
<br />
== unpiloted ==<br />
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.<br><br />
It will not add a pilot when set to false, but will remove any existing pilot when set to true.<br />
commsMessages can only be broadcasted by piloted ships. Ships are by default piloted. cargo , rocks, missiles etc. are not piloted by default.<br />
<br />
Example:<br />
"unpiloted" = yes;<br />
<br />
== view_position_.. ==<br />
Sets the ship's 4 point-of-view positions in XYZ relative to the model.<br />
<br />
Example:<br />
"view_position_aft" = "0.0 5.0 -20.0";<br />
"view_position_forward" = "0.0 1.9375 5.0";<br />
"view_position_port" = "-11.85 2.825 -3.5";<br />
"view_position_starboard" = "11.85 2.825 -3.5";<br />
<br />
<br />
== weapon_energy ==<br />
This setting works differently depending on the type of entity it's used for:<br><br />
<br />
<b>Missiles.</b> Changes the damage inflicted by the missile. Any value accepted.<br />
<br />
<b>NPC ships.</b> 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.<br><br />
<i><b>N.B.</b> It does not have any effect on player ships.</i><br />
<br />
<b>turrets.</b> Unused for turrets. Set the turret weapon_energy in its [[Shipdata.plist#New-style_subentity_definition|subEntity directory]].<br />
<br />
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<br />
<br />
Example:<br />
"weapon_energy" = "17";<br />
<br />
== weapon_facings ==<br />
(1.77 or later only)<br />
What weapon mounts are available on the ship. This is a bit-mask, so pick the mounts and add the numbers:<br />
<br />
1 - Forward<br /><br />
2 - Aft<br /><br />
4 - Port<br /><br />
8 - Starboard<br /><br />
<br />
Example: <br /><br />
Fore and aft weapon mounts only.<br />
<key>weapon_facings</key><br />
<integer>3</integer><br />
<br />
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.<br />
<br />
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.<br />
<br />
== weapon_offset ==<br />
Removed after version 1.65 (it was used to change the offsetpoint of a plasma cannon.)<br />
<br />
== weapon_position_.. ==<br />
Plots the 'gunmouth' points of the model's 4 potential lasers.<br />
<br />
Example:<br />
"weapon_position_aft" = "0.0 -5.0 -20.0";<br />
"weapon_position_forward" = "0.0 0.0417 16.6667";<br />
"weapon_position_port" = "-13.75 -2.0625 -1.875";<br />
"weapon_position_starboard" = "13.75 -2.0625 -1.875";<br />
<br />
= Station keys=<br />
The following keys are only used by stations or carriers.<br />
<br />
== allegiance ==<br />
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.<br />
<br />
Example:<br />
allegiance = "neutral";<br />
<br />
== allows_auto_docking ==<br />
When set false for a station, this station will not allow the use of a docking computer. Default value in "yes". (Planned for Oolite 1.75)<br />
<br />
Example:<br />
allows_auto_docking = "no";<br />
<br />
== allows_fast_docking ==<br />
When set true for a station, this station will allow fast docking with the docking computer. Default value in "no". (Planned for Oolite 1.75)<br />
<br />
Example:<br />
allows_fast_docking = "yes";<br />
<br />
== defense_ship ==<br />
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]]<br />
<br />
Example:<br />
defense_ship" = "my_defender";<br />
<br />
== defense_ship_role ==<br />
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"<br />
<br />
Example:<br />
"defense_ship_role" = " carrier_defenders";<br />
<br />
== equipment_price_factor ==<br />
Equipment price mask for dockables.<br />
<br />
Example:<br />
"equipment_price_factor" = "4.5";<br />
<br />
== equivalent_tech_level ==<br />
Sets shipyard tech level for dockables, different to the local system tech_level. Default value is the system tech_level.<br />
<br />
Example:<br />
"equivalent_tech_level" = 1;<br />
<br />
== has_npc_traffic ==<br />
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).<br />
<br />
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).<br />
<br />
Example:<br />
"has_npc_traffic" = yes;<br />
<br />
== has_patrol_ships ==<br />
Determines if a station launches periodic patrol ships. Default is "no". Main stations always have patrol ships. (Planned for Oolite 1.75)<br />
<br />
Example:<br />
"has_patrol_ships" = yes;<br />
<br />
== has_shipyard ==<br />
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".)<br />
<br />
Example:<br />
"has_shipyard" = "0.75";<br />
<br />
or<br />
<br />
"has_shipyard" = (<br />
"systemGovernment_number morethan 3",<br />
"systemEconomy_number lessthan 4"<br />
)<br />
<br />
== interstellar_undocking ==<br />
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". (Planned for Oolite 1.75)<br />
<br />
Example:<br />
interstellar_undocking = "yes";<br />
<br />
==is_carrier==<br />
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".)<br />
<br />
Example:<br />
"is_carrier" = yes;<br />
<br />
== market ==<br />
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.<br />
<br />
Example:<br />
"market" = "none";<br />
<br />
== market_broadcast ==<br />
In 1.81 or later, 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.<br />
<br />
"market_broadcast" = no;<br />
<br />
== market_capacity ==<br />
In 1.81 or later, 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.<br />
<br />
"market_capacity" = 31;<br />
<br />
== market_definition ==<br />
In 1.81 or later, 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.<br />
<br />
"market_definition" = (<br />
{<br />
// export cheap clothes<br />
"type" = "class";<br />
"name" = "oolite-wearable";<br />
"price_multiplier" = 0.8;<br />
"price_randomiser" = 0.1;<br />
"quantity_multiplier" = 3.5;<br />
"quantity_randomiser" = 3.0;<br />
}, <br />
{<br />
// not really interested in other goods<br />
"type" = "default";<br />
"price_multiplier" = 0.55;<br />
"price_randomiser" = 0.25;<br />
"quantity_multiplier" = 0.0;<br />
"capacity" = 3;<br />
}<br />
);<br />
<br />
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.<br />
<br />
A blank array<br />
"market_definition" = ();<br />
will give a market identical to the primary system market.<br />
<br />
If this key is omitted, the station will have no market. This is roughly equivalent to<br />
"market_definition = (<br />
{<br />
"type" = "default";<br />
"price_multiplier" = 0;<br />
"quantity_multiplier" = 0;<br />
"capacity" = 0;<br />
}<br />
);<br />
<br />
== market_monitored ==<br />
In Oolite 1.81 and later, 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.<br />
<br />
market_monitored = yes;<br />
<br />
== market_script ==<br />
In Oolite 1.81 and later, allows a [[Oolite_Market_Scripts|market script]] to be used to modify trade prices. This overrides market_definition, if it is present.<br />
<br />
market_script = "myoxp_marketchanges.js";<br />
<br />
== max_defense_ships ==<br />
Designates how many ships a dockable entity (station, carrier) can launch in defense. Default value is 3. See also [[Station Ships]]<br />
<br />
Example:<br />
"max_defense_ships" = "10";<br />
<br />
== max_police ==<br />
Designates how many police or patrol ships a dockable entity (station, carrier) can launch. Default value is 8. See also [[Station Ships]]<br />
<br />
Example:<br />
"max_police " = "10";<br />
<br />
== max_scavengers ==<br />
Designates how many scavengers or miners a dockable entity (station, carrier) can launch. Default value is 3. See also [[Station Ships]]<br />
<br />
Example:<br />
"max_scavengers" = "10";<br />
<br />
== port_dimensions ==<br />
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.<br />
<br />
Example:<br />
"port_dimensions" = "65x30x500";<br />
<br />
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)<br><br />
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.<br />
<br />
== port_radius ==<br />
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.<br />
<br />
Example:<br />
"port_radius" = "500";<br />
<br />
== requires_docking_clearance ==<br />
Sets the requirement for docking clearance. Default is "no". See also [[Oolite_Docking_Clearance_Protocol_%28v1.72_or_later%29|DockingClearance]]<br />
<br />
Example:<br />
"requires_docking_clearance" = yes;<br />
<br />
==rotating==<br />
Given to a station when rotation is desired. Default is "no".<br />
<br />
Example:<br />
"rotating" = yes;<br />
<br />
== station_roll ==<br />
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. (Key is added in Oolite 1.74.2)<br />
<br />
'''Note''': unlike the other turn rate properties, for historical reasons <code>station_roll</code> is measured in right-angles/second, ''not'' radians/second.<br />
<br />
Example:<br />
"station_roll" = "-1.5"<br />
<br />
==tunnel_corners==<br />
Defines the number of corners in the docking tunnel. Ranges from 4 to 128. Default is "4". (Key is added in Oolite 1.75)<br />
<br />
Example:<br />
"tunnel_corners" = 6;<br />
<br />
==tunnel_start_angle==<br />
Defines the position of the first corner of the docking tunnel in degrees. 0 means the first corner is straight up. Default is "45". (Key is added in Oolite 1.75)<br />
<br />
Example:<br />
"tunnel_start_angle" = 0;<br />
<br />
==tunnel_aspect_ratio==<br />
Defines the proportion of the tunnel’s width to its height. Default is "2.67".<br />
<br />
Example:<br />
"tunnel_aspect_ratio" = 1;<br />
<br />
--------------------------------------------------------------------------------<br />
[[Category:Oolite]]<br />
[[Category:Oolite scripting]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Ship&diff=47149Oolite JavaScript Reference: Ship2015-04-02T12:53:16Z<p>Cim: /* adjustCargo */ New for 1.81</p>
<hr />
<div><small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Entity|Entity]]</code></small><br /><br />
<small>'''Subtypes:''' <code>[[Oolite JavaScript Reference: Station|Station]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code></small><br />
<br />
The '''<code>Ship</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing a ship, station, missile, cargo pod or other flying item – anything that can be specified in [[shipdata.plist]]. A <code>Ship</code> has all the properties and methods of a <code>Entity</code>, and several others.<br />
<br />
<code>[[Oolite JavaScript Reference: Station|Station]]</code>s and the <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code> are types of ship. Note that these more specific types have additional properties and methods.<br />
<br />
== Properties ==<br />
=== <code>accuracy</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''accuracy''' : Number (read/write, read-only and irrelevant for player ship)<br />
The accuracy of the ship's AI. Varies between -5 and +10 for ships, or 0 and +10 for missiles. Setting a value outside the allowed range will set the closest value within the allowed range.<br />
<br />
For missiles, this affects the missile tracking, with 0 being the default value.<br />
<br />
For NPC ships, this affects their combat AI in many ways. Values of +5 or higher enable various [[OXP_NPC_Combat_AI|special combat AIs]] for a tough fight.<br />
<br />
=== <code>aftWeapon</code> ===<br />
'''aftWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped aft weapon, or <code>null</code>.<br />
<br />
'''See also:''' <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>AI</code> ===<br />
'''AI''' : String (read-only)<br />
The name of the ship’s current plist-based state machine AI. If the ship is using Javascript-based AI, this will always be "<code>nullAI.plist</code>"<br />
<br />
'''See also:''' <code>[[#AIState|AIState]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AIScript|AIScript]]</code><br />
<br />
=== <code>AIFoundTarget</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''AIFoundTarget''' : Entity (read/write, read-only for player)<br />
The "found target" of the ship's AI. This is set by various AI state commands, and is often copied to the primary target with the <code>setTargetToFoundTarget</code> AI command.<br />
<br />
=== <code>AIPrimaryAggressor</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''AIPrimaryAggressor''' : Entity (read/write, read-only for player)<br />
The "primary aggressor" of the ship's AI. Often the last ship to attack this ship.<br />
<br />
=== <code>AIScript</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''AIScript''' : String (read-only)<br />
The name of the ship’s current Javascript-based AI. If the ship is using plist-based AI, this will always be "<code>oolite-nullAI.js</code>"<br />
<br />
'''See also:''' <code>[[#AIScriptWakeTime|AIScriptWakeTime]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AI|AI]]</code><br />
<br />
=== <code>AIScriptWakeTime</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''AIScriptWaketime''' : Number (read-write)<br />
The next game time at which the ship's Javascript-based AI script will receive an <code>aiAwoken</code> event.<br />
<br />
=== <code>AIState</code> ===<br />
'''AIState''' : String (read/write, read-only for player)<br />
The ship’s plist AI’s current state.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#reactToAIMessage|reactToAIMessage()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code><br />
<br />
=== <code>alertCondition</code> ===<br />
'''alertCondition''' : Number (read-only integer)<br />
The ship's current alert condition (Docked = 0, Green = 1, Yellow = 2, Red = 3). Non-Station non-Player ships are generally only found at condition Yellow or Red.<br />
<br />
'''See also:''' [[Oolite_JavaScript_Reference:_Station#alertCondition|station.alertCondition]]<br />
<br />
=== <code>autoAI</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''autoAI''' : Boolean (read-only)<br />
The value of the "<code>auto_ai</code>" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the AI of this ship to better fit into scenarios or roles. If this is false, the ship's provider would prefer you not to alter the AI of this ship but to use it as-is.<br />
<br />
=== <code>autoWeapons</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''autoWeapons''' : Boolean (read-only)<br />
The value of the "<code>auto_weapons</code>" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the properties of this ship to better fit into scenarios or roles. If this is false, the ship's provider would prefer you not to alter the properties of this ship but to use it as-is.<br />
<br />
=== <code>beaconCode</code> ===<br />
'''beaconCode''' : String (read-only in 1.76, read-write from 1.77)<br />
If the ship is a beacon, an identifying string. The first character is used for identification on the [[Advanced Space Compass]]. For non-beacons, this property is <code>null</code>. This can not be changed by script for either the player's ship or the main station.<br />
<br />
'''See also:''' <code>[[#isBeacon|isBeacon]]</code><br />
<br />
=== <code>beaconLabel</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''beaconLabel''' : String (read/write)<br />
A full label for the beacon. This is useful where the beacon code and the full beacon label do not begin with the same letter.<br />
<br />
=== <code>boundingBox</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''boundingBox''' : Vector (read-only)<br />
For ships, a vector describing the dimensions of the cuboid box containing the ship aligned to the ship axes, including all non-flasher sub-entities. For sub-entities, the dimensions of the box for the sub-entity alone.<br />
<br />
Vector components match the standard model order - <code>x</code> is width, <code>y</code> is height, <code>z</code> is length.<br />
<br />
=== <code>bounty</code> ===<br />
'''bounty''' : Number (read/write integer)<br />
The bounty on the ship.<br />
<br />
In 1.77, changes to the bounty are given a reason. If you change this directly, the reason sent to [[Oolite_JavaScript_Reference:_ship_script_event_handlers#shipBountyChanged|shipBountyChanged]] will be "scripted". To set a different reason, use [[#setBounty|setBounty]] instead.<br />
<br />
=== <code>cargoList</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''cargoList''' : Array (read-only)<br />
A list of the ship's current cargo, grouped by cargo type. For the player ship, this is equivalent to <code>player.ship.manifest.list</code><br />
<br />
=== <code>cargoSpaceCapacity</code> ===<br />
'''cargoSpaceCapacity''' : Number (read-only in 1.80, read/write in 1.81, integer)<br />
The ship’s cargo capacity, in tons.<br />
<br />
=== <code>collisionExceptions</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''collisionExceptions''' : Array (read-only)<br />
A list of ships this ship is currently prevented from colliding with. See [[#addCollisionException|addCollisionException]] and [[#removeCollisionException|removeCollisionException]].<br />
<br />
=== <code>commodity</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''commodity''' : String (read-only)<br />
The commodity for cargo containers as a lowercase string. Returns <code>null</code> for non-cargo ships. For scripted cargo that has no specific cargo defined, it returns the general description "goods".<br />
<br />
=== <code>commodityAmount</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''commodityAmount''' : Number (read-only)<br />
The amount of commodity in a cargo container. (not the number of containers in a ship)<br />
<br />
=== <code>contracts</code> ===<br />
'''contracts''' : Array (read-only NSDictionary)<br />
The ship’s contracts. (For now only available for the player). Each contract contains the entries: <code>commodity: string, quantity: integer, description: string, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
<br />
For example, the information of the first contract can be obtained by:<br />
player.ship.contracts[0].commodity<br />
player.ship.contracts[0].quantity<br />
player.ship.contracts[0].description<br />
player.ship.contracts[0].start<br />
player.ship.contracts[0].destination<br />
player.ship.contracts[0].startName<br />
player.ship.contracts[0].destinationName<br />
player.ship.contracts[0].eta // Estimated Time of Arrival.<br />
player.ship.contracts[0].etaDescription<br />
player.ship.contracts[0].fee // The profit of the contract, paid out on successful delivery.<br />
player.ship.contracts[0].premium // The sum paid to obtain the goods and paid back on successful delivery.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this contract, and premium was the amount the player had to pay to secure this contract.<br />
<br />
=== <code>cloakAutomatic</code> ===<br />
'''cloakAutomatic''' : Boolean (read/write)<br />
If <code>true</code> (the default), the ship will automatically engage its cloak while attacking. Otherwise, it must be managed by a script. The corresponding ''[[shipdata.plist]]'' key is <code>cloak_automatic</code>.<br />
<br />
=== <code>crew</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''crew''' : Array (read-only)<br />
An array containing the ship's crew. Each crew member is represented as a dictionary. Note that in current Oolite versions ships only have a single crew member defined.<br />
<br />
=== <code>cruiseSpeed</code> ===<br />
'''cruiseSpeed''' : Number (read-only nonnegative)<br />
The ship’s “normal” <code>[[#desiredSpeed|desiredSpeed]]</code>, used in normal flight. Normally this is 80 % of <code>[[#maxSpeed|maxSpeed]]</code>, but it may be lowered when accepting a slow escort.<br />
<br />
=== <code>currentWeapon</code> ===<br />
{{oolite-prop-added|1.77}} <br />
'''currentWeapon''' : EquipmentType (read/write)<br />
A shortcut property to whichever of <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code> or <code>[[#starboardWeapon|starboardWeapon]]</code> represents the ship's currently active laser mount.<br />
<br />
=== <code>dataKey</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''dataKey''' : String (read-only)<br />
The ship data key used to define this ship (e.g. <code>adder-player</code> or <code>coriolis-station</code>)<br />
<br />
=== <code>defenseTargets</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''defenseTargets''' : Array (read-only)<br />
The array of defense targets that the ship has. If the ship has point defense weapons (turrets, thargoid lasers) it may fire them at these targets if it cannot hit its primary target.<br />
<br />
'''See also:''' <code>[[#addDefenseTarget|addDefenseTarget]]</code>, <code>[[#clearDefenseTargets|clearDefenseTargets]]</code><br />
<br />
=== <code>desiredRange</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''desiredRange''' : Number (read/write nonnegative, read-only for player)<br />
The range the AI uses in various AI routines to set a distance between the ship and another object - for example, the radius of a sphere around a destination point, or the distance to flee from a hostile ship.<br />
<br />
=== <code>desiredSpeed</code> ===<br />
'''desiredSpeed''' : Number (read/write nonnegative, read-only for player)<br />
The speed the AI will attempt to maintain. The AI core and AI script may change this from time to time. The corresponding AI method is <code>setSpeedFactorTo:</code>; a speed factor of 1.0 corresponds to a <code>desiredSpeed</code> equal to <code>[[#maxSpeed|maxSpeed]]</code>.<br />
<br />
'''See also:''' <code>[[#cruiseSpeed|cruiseSpeed]]</code><br />
<br />
=== <code>destination</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''destination''' : Vector (read/write, read-only for player)<br />
The destination coordinates for the AI, used in behaviours such as <code>performFlyToRangeFromDestination</code>.<br />
<br />
=== <code>destinationSystem</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''destinationSystem''' : Number (read/write)<br />
The destination system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.<br />
<br />
=== <code>displayName</code> ===<br />
'''displayName''' : String (read/write, read-only for player)<br />
The name of the ship as seen by the player. By default in 1.78 or earlier it is the same as <code>[[#name|name]]</code>. In 1.79 or later it is a combination of [[#shipClassName|shipClassName]] and [[#shipUniqueName|shipUniqueName]]<br />
<br />
=== <code>dockingInstructions</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''dockingInstructions''' : Object (read-only)<br />
If the ship is currently attempting to dock with a station, this describes the next step on its docking procedure<br />
<br />
{<br />
station: [Station "Coriolis Station" "Coriolis Station" position: (-31043.6, -94232.3, 619036) scanClass: CLASS_STATION status: STATUS_ACTIVE],<br />
match_rotation: 0,<br />
ai_message: "APPROACH_COORDINATES",<br />
speed: 512,<br />
destination: {<br />
x: -28033.37401563089,<br />
y: -92813.76688970842,<br />
z: 622226.0625336492<br />
},<br />
range: 96<br />
}<br />
<br />
'''See also:''' <code>[[#requestDockingInstructions|requestDockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code><br />
<br />
=== <code>energyRechargeRate</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''energyRechargeRate''' : Number (read-only, read/write from 1.81)<br />
The rate at which energy is replenished in every second. The corresponding ''[[shipdata.plist]]'' key is <code>energy_recharge_rate</code>.<br />
<br />
Note for the player ship that this includes the boost from an extra or naval energy unit, and NPC (but not player) ships with military shield boosters also have an increase to this in lieu of actual shields.<br />
<br />
=== <code>entityPersonality</code> ===<br />
'''entityPersonality''' : Number (read-only integer)<br />
A random number in the range 0..32767 which is generated when the ship is created. Equivalent to the <code>entityPersonalityInt</code> [[Shaders in Oolite: uniforms#Ship|uniform binding]].<br />
<br />
=== <code>equipment</code> ===<br />
'''equipment''' : Array of [[Oolite_JavaScript_Reference:_EquipmentInfo|EquipmentInfo ]] (read-only)<br />
The equipment a ship is carrying.<br />
<br />
=== <code>escortGroup</code> ===<br />
'''escortGroup''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]<br />
The ship’s deployed escorts.<br />
<br />
'''See also:''' <code>[[#maxEscorts|maxEscorts]]</code><br />
<br />
=== <code>escorts</code> ===<br />
'''escorts''' : Array (read-only array of [[Oolite JavaScript Reference: Entity|Entity]]s)<br />
The ship’s deployed escorts.<br />
<br />
=== <code>exhaustEmissiveColor</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''exhaustEmissiveColor''' : Color (read/write)<br />
The baseline colour of the ship's exhaust. Damage to the ship, and use of injectors and torus drive, apply a fixed transformation to this colour, so not all colours are effective as exhaust colours.<br />
<br />
=== <code>exhausts</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''exhausts''' : Array (read-only)<br />
An array of the ship's [[Oolite_JavaScript_Reference:_ExhaustPlume|ExhaustPlume]] subentities.<br />
<br />
=== <code>extraCargo</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''extraCargo''' : Number (read-only integer)<br />
The amount the cargo capacity increases when an extra cargobay is installed. The corresponding ''[[shipdata.plist]]'' key is <code>extra_cargo</code>.<br />
<br />
=== <code>flashers</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''flashers''' : Array (read-only)<br />
An array of the ship's [[Oolite_JavaScript_Reference:_Flasher|Flasher]] subentities.<br />
<br />
=== <code>forwardWeapon</code> ===<br />
'''forwardWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped forward weapon, or <code>null</code>.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>fuel</code> ===<br />
'''fuel''' : Number (read/write)<br />
The ship’s current fuel capacity, in LY. The game will limit this to the range 0..7, and round it off to the nearest tenth.<br />
<br />
'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#fuelLeakRate|PlayerShip.fuelLeakRate]]</code><br />
<br />
=== <code>fuelChargeRate</code> ===<br />
'''fuelChargeRate''' : Number (read-only)<br />
The cost, relative to the cost for a new Cobra III, of a unit of fuel. When buying fuel for a ship, the price in [[equipment.plist]] will be multiplied by this number.<br />
<br />
=== <code>group</code> ===<br />
'''group''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]<br />
Contains ship’s belonging to each other. Added pirate groups are an example or a station with its launched defenders.<br><br />
A group is an individual object that can be linked to several ships belonging to the same group. When a ship dies and the group object has still owners, the group stays active as object. The group is only removed from memory after the last ship that had this group as property is removed.<br><br />
Adding a group to a ship does not automatic puts that ship in the group. For that to happen you need also use the addShip() command. <br />
e.g. <br />
this.ship.group = new ShipGroup();<br />
this.ship.group.addShip(this.ship);<br />
<br />
=== <code>hasHostileTarget</code> ===<br />
'''hasHostileTarget''' : Boolean (read-only)<br />
<code>true</code> if the ship’s AI is trying to kill something, <code>false</code> otherwise. Always <code>false</code> for the player.<br />
<br />
=== <code>hasHyperspaceMotor</code> ===<br />
'''hasHyperspaceMotor''' : Boolean (read-only)<br />
True if the ship can make witchspace jumps. The corresponding ''[[shipdata.plist]]'' entry is <code>hyperspace_motor</code>.<br />
<br />
=== <code>hasSuspendedAI</code> ===<br />
'''hasSuspendedAI''' : Boolean (read-only)<br />
<code>true</code> if the ship has suspended AIs, <code>false</code> otherwise.<br />
<br />
=== <code>heatInsulation</code> ===<br />
'''heatInsulation''' : Number (read/write)<br />
The ship’s heat insulation factor. 1.0 is normal, higher values mean more resistance to heat.<br />
<br />
Note that in 1.80 and earlier writes to this property had no effect on the player ship.<br />
<br />
=== <code>homeSystem</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''homeSystem''' : Number (read/write)<br />
The home system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.<br />
<br />
=== <code>hyperspaceSpinTime</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''hyperspaceSpinTime''' : Number (read/write)<br />
The length of the ship's hyperspace countdown.<br />
<br />
Setting this to a negative value disables the drive entirely.<br />
<br />
Note that most NPC ship jumps use <code>ship.exitSystem()</code> to make the jump, which does not have a delay. Provided this value is zero or positive, the ship will jump instantly if <code>ship.exitSystem()</code> is called. The AI must use this property elsewhere if a delay before jumping is required.<br />
<br />
=== <code>injectorBurnRate</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorBurnRate''' : Number (read/write)<br />
The rate at which the ship's injectors burn fuel in deci-LY per second. The default is 0.25.<br />
<br />
=== <code>injectorSpeedFactor</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorSpeedFactor''' : Number (read/write)<br />
The multiplier to maximum speed granted to this ship when it is using injectors. The default is 7, and values must be between 1.0 and 32.0 (the torus drive's speed)<br />
<br />
=== <code>isBeacon</code> ===<br />
'''isBeacon''' : Boolean (read-only)<br />
<code>true</code> if the ship is a beacon (i.e., can show up on the [[Advanced Space Compass]] with a character indicating its identity), <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#beaconCode|beaconCode]]</code><br />
<br />
=== <code>isBoulder</code> ===<br />
'''isBoulder''' : Boolean (read/write)<br />
<code>true</code> if the ship is a boulder (i.e., has the role "boulder in its roleset)<br />
<br />
=== <code>isCargo</code> ===<br />
'''isCargo''' : Boolean (read-only)<br />
<code>true</code> if the ship is cargo (i.e., has scan_class CLASS_CARGO and contains at least one unit)<br />
<br />
=== <code>isCloaked</code> ===<br />
'''isCloaked''' : Boolean (read/write)<br />
<code>true</code> if the ship has a cloaking device which is currently active <code>false</code> otherwise. If the ship has a cloaking device and sufficient energy to use it (<code>energy > 0.75 * [[Oolite JavaScript Reference: Entity#maxEnergy|maxEnergy]]</code>), you can activate it by setting <code>isCloaked</code> to <code>true</code>.<br />
<br />
=== <code>isDerelict</code> ===<br />
'''isDerelict''' : Boolean (read-only)<br />
<code>true</code> if the ship is a derelict (i.e., the pilot has ejected from the ship, or the ship was created with the ship-key: "is_hulk")<br />
<br />
=== <code>isFleeing</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isFleeing''' : Boolean (read-only)<br />
<code>true</code> if the ship is currently fleeing combat. This may be queried for the player ship too, though the value is somewhat of a guess in that case as it's impossible to say for certain what the player is intending by their actions.<br />
<br />
=== <code>isFrangible</code> ===<br />
'''isFrangible''' : Boolean (read-only)<br />
<code>true</code> if the ship is frangible (i.e., its subentities can be destroyed separately from the main ship), <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>isJamming</code> ===<br />
'''isJamming''' : Boolean (read-only)<br />
<code>true</code> if the ship has a military scanner jammer which is currently active <code>false</code> otherwise.<br />
<br />
=== <code>isMinable</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isMinable''' : Boolean (read-only)<br />
<code>true</code> if the ship will break up usefully when hit by a mining laser, <code>false</code> otherwise. By default this is true for anything with "asteroid" or "boulder" in its role list - if you need to add anything which miners shouldn't be shooting at to those roles, give it <code>"no_boulders" = yes;</code> in its [[shipdata.plist]].<br />
<br />
=== <code>isMine</code> ===<br />
'''isMine''' : Boolean (read-only)<br />
<code>true</code> if the ship is a mine, <code>false</code> otherwise.<br />
<br />
=== <code>isMissile</code> ===<br />
'''isMissile''' : Boolean (read-only)<br />
<code>true</code> if the ship is a missile, <code>false</code> otherwise.<br />
<br />
=== <code>isPiloted</code> ===<br />
'''isPiloted''' : Boolean (read-only)<br />
<code>true</code> if the ship has a pilot on board, <code>false</code> otherwise. Generally have ships, station and escape pods pilots and have cargo, rocks, missiles or buoys no pilots.<br />
<br />
=== <code>isPirate</code> ===<br />
'''isPirate''' : Boolean (read-only)<br />
<code>true</code> if the ship is a pirate vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "pirate"</code>.<br />
<br />
=== <code>isPirateVictim</code> ===<br />
'''isPirateVictim''' : Boolean (read-only)<br />
<code>true</code> if the ship’s [[#primaryRole|primary role]] is listed in ''pirate-victim-roles.plist'', <code>false</code> otherwise. This is the same test used by the pirate AI to select victims.<br />
<br />
=== <code>isPolice</code> ===<br />
'''isPolice''' : Boolean (read-only)<br />
<code>true</code> if the ship is a police vessel, <code>false</code> otherwise. Currently equivalent to <code>[[Oolite JavaScript Reference: Entity#scanClass|scanClass]] == "CLASS_POLICE"</code>.<br />
<br />
=== <code>isRock</code> ===<br />
'''isRock''' : Boolean (read-only)<br />
<code>true</code> if the ship is a rock (i.e., has scan_class: CLASS_ROCK)<br />
<br />
=== <code>isThargoid</code> ===<br />
'''isThargoid''' : Boolean (read-only)<br />
<code>true</code> if the ship is a Thargoid vessel, <code>false</code> otherwise. Currently equivalent to <code>[[Oolite JavaScript Reference: Entity#scanClass|scanClass]] == "CLASS_THARGOID"</code>.<br />
<br />
=== <code>isTrader</code> ===<br />
'''isTrader''' : Boolean (read-only)<br />
<code>true</code> if the ship is a merchant vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "trader" || isPlayer</code>. '''Note:''' <code>[[#isPirateVictim|isPirateVictim]]</code> may be a better choice in many cases.<br />
<br />
=== <code>isTurret</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isTurret''' : Boolean (read-only)<br />
<code>true</code> if the ship is a plasma turret sub-entity, <code>false</code> otherwise.<br />
<br />
=== <code>isWeapon</code> ===<br />
'''isWeapon''' : Boolean (read-only)<br />
<code>true</code> if the ship is a weapon, <code>false</code> otherwise. Currently equivalent to <code>[[#isMissile|isMissile]] || [[#isMine|isMine]] </code>, but new categories of weapon could be added in future.<br />
<br />
=== <code>laserHeatLevel</code>* ===<br />
{{Oolite-prop-added|1.77}}<br />
'''laserHeatLevel''' : Number (read-only, 0 to 1)<br />
The temperature of the ship's currently active weapon. Thermal cut-out is active above 0.85. For non-player ships, if their forward weapon is empty, then the temperature of the forward weapon may be the temperature of a subentity forward weapon.<br />
'''laserHeatLevelAft''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelForward''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelPort''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelStarboard''' : Number (read-only, 0 to 1)<br />
The temperature of specific laser mounts can also be queried.<br />
<br />
=== <code>lightsActive</code> ===<br />
'''lightsActive''' : Boolean (read-write)<br />
Setting this property to <code>true</code> turns on all the entity’s flashers, and setting it to <code>false</code> turns them off. Setting it sets the <code>lightsActive</code> property for all subentities, but subentities’ setting can also be manipulated separately. In addition to affecting flashers, the value can be used by shaders.<br />
<br />
Note: <code>lightsActive</code> is always <code>true</code> when a ship is spawned, although individual flashers may be off because they have <code>initially_on</code> set to false in their ''shipdata.plist'' declarations.<br />
<br />
=== <code>markedForFines</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''markedForFines''' : Boolean (read-only)<br />
<code>True</code> if the ship has been marked for fines the next time it docks at this system's main station.<br />
<br />
'''See also''' : [[#markTargetForFines|markTargetForFines()]]<br />
<br />
=== <code>maxEscorts</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxEscorts''' : Number (read/write)<br />
The maximum number of escorts this ship can have. This cannot be set lower than the number of escorts it currently has, or higher than the value of the MAX_ESCORTS constant (currently 16). There may be other reasons why a ship can have fewer escorts than the value of <code>maxEscorts</code> (for instance, ships which are escorts cannot have their own escorts)<br />
<br />
'''See also:''' <code>[[#escortGroup|escortGroup]]</code><br />
<br />
=== <code>maxPitch</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxPitch''' : Number (read-only, read/write from 1.81)<br />
The maximum pitch rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#pitch|pitch]]</code><br />
<br />
=== <code>maxRoll</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxRoll''' : Number (read-only, read/write from 1.81)<br />
The maximum roll rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#roll|roll]]</code><br />
<br />
=== <code>maxSpeed</code> ===<br />
'''maxSpeed''' : Number (read-only, read/write from 1.81)<br />
The ship’s maximum speed under normal power. Note that <code>[[#speed|speed]]</code> may exceed this when [[witch fuel injectors]] or [[hyperspeed]] are in use.<br />
<br />
'''See also:''' <code>[[#speed|speed]]</code><br />
<br />
=== <code>maxThrust</code> ===<br />
'''maxThrust''' : Number (read-only, read/write from 1.81)<br />
The ship’s maximum <code>[[#thrust|thrust]]</code>. This value is the one defined as <code>thrust</code> in ''[[Shipdata.plist#thrust|shipdata.plist]]''.<br />
<br />
=== <code>maxYaw</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxYaw''' : Number (read-only, read/write from 1.81)<br />
The maximum yaw rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#yaw|yaw]]</code><br />
<br />
=== <code>missileCapacity</code> ===<br />
'''missileCapacity''' : Number (read-only integer)<br />
The maximum number of missiles the ship can carry.<br />
<br />
=== <code>missileLoadTime</code> ===<br />
'''missileLoadTime''' : Number (read-write nonnegative)<br />
The minimum amount of time between two missiles. The corresponding ''[[shipdata.plist]]'' key is <code>missile_load_time</code>.<br />
<br />
=== <code>missiles</code> ===<br />
'''missiles''' : Array (read-only array of [[Oolite JavaScript Reference: EquipmentInfo|EquipmentInfo]])<br />
The ship’s loaded missiles.<br />
<br />
=== <code>name</code> ===<br />
'''name''' : String (read/write, read-only for player)<br />
The name of the ship type (<code>name</code> key in [[shipdata.plist]]).<br />
<br />
''Note'': while <code>name</code> can be changed, this is discouraged (and will probably not be supported in Oolite 2.0). Use <code>[[#displayName|displayName]]</code> instead.<br />
<br />
=== <code>parcelCount</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''parcelCount''' : Number (read-only integer)<br />
The ship’s current number of parcels.<br />
<br />
=== <code>parcels</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''parcels''' : Array (read-only NSDictionary)<br />
The ship’s parcels. (For now only available for the player). Each parcel list contains the entries: <code>name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
For example, the information of the first contract can be obtained by:<br />
player.ship.parcels[0].name<br />
player.ship.parcels[0].start<br />
player.ship.parcels[0].destination<br />
player.ship.parcels[0].startName<br />
player.ship.parcels[0].destinationName<br />
player.ship.parcels[0].eta<br />
player.ship.parcels[0].etaDescription<br />
player.ship.parcels[0].fee // The final fee, paid out on successful delivery.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this parcel.<br />
<br />
=== <code>passengerCapacity</code> ===<br />
'''passengerCapacity''' : Number (read-only integer)<br />
The ship’s maximum passenger capacity.<br />
<br />
=== <code>passengerCount</code> ===<br />
'''passengerCount''' : Number (read-only integer)<br />
The ship’s current number of passengers.<br />
<br />
=== <code>passengers</code> ===<br />
'''passengers''' : Array (read-only NSDictionary)<br />
The ship’s passengers. (For now only available for the player). Each passengers list contains the entries: <code>name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
For example, the information of the first contract can be obtained by:<br />
player.ship.passengers[0].name<br />
player.ship.passengers[0].start<br />
player.ship.passengers[0].destination<br />
player.ship.passengers[0].startName<br />
player.ship.passengers[0].destinationName<br />
player.ship.passengers[0].eta<br />
player.ship.passengers[0].etaDescription<br />
player.ship.passengers[0].fee // The final fee, paid out on successful delivery.<br />
player.ship.passengers[0].premium // The advance fee, already paid on acceptance of the contract.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this passenger, and premium shows the amount the player received when the passenger boarded the ship.<br />
<br />
=== <code>pitch</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''pitch''' : Number (read-only)<br />
The rate of pitch of the ship in radians/second (positive for dive, negative for climb)<br />
<br />
=== <code>portWeapon</code> ===<br />
'''portWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped port weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>potentialCollider</code> ===<br />
'''potentialCollider''' : [[Oolite JavaScript Reference: Entity|Entity]] (read-only)<br />
The entity the ship is currently trying not to crash into, if any.<br />
<br />
=== <code>primaryRole</code> ===<br />
'''primaryRole''' : String (read/write, read-only for player)<br />
The main role of the ship; the role for which it was created. For instance, if a ship’s ''shipdata.plist'' entry specifies the roles “pirate trader(0.5) escort”, and a ship of that type is spawned to be a trader, its <code>primaryRole</code> is <code>"trader"</code>, its <code>roles</code> is <code>["escort", "pirate", "trader"]</code> and its <code>roleWeights</code> is <code> { "escort":1, "pirate":1, "trader":0.5}</code>.<br />
<br />
'''See also:''' <code>[[#roles|roles]]</code>, <code>[[#roleWeights|roleWeights]]</code><br />
<br />
=== <code>reportAIMessages</code> ===<br />
'''reportAIMessages''' : Boolean (read/write)<br />
Debugging facility: set to <code>true</code> to dump information about AI activity to the log. <br />
<br />
=== <code>roleWeights</code> ===<br />
'''roleWeights''' : Object (read-only)<br />
The probabilities for each role in <code>[[#roles|roles]]</code>.<br />
<br />
Example:<br />
this.pirateProb = ship.roleWeights["pirate"]<br />
<br />
'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roles|roles]]</code><br />
<br />
=== <code>roles</code> ===<br />
'''roles''' : Array (read-only array of Strings)<br />
The roles of the ship. This consists of the roles specified in the ship’s ''shipdata.plist'' entry, as well as the <code>[[#primaryRole|primaryRole]]</code> if it is not among those.<br />
<br />
'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roleWeights|roleWeights]]</code>, <code>[[#hasRole|hasRole()]]</code><br />
<br />
=== <code>roll</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''roll''' : Number (read-only, read/write for stations)<br />
The rate of roll of the ship in radians/second (positive for anti-clockwise, negative for clockwise)<br />
<br />
For stations, this can be set to any value between -2 and +2 to adjust their roll rate. The default is 0.4, or the value specified by the <code>station_roll</code> key in shipdata.plist.<br />
<br />
=== <code>savedCoordinates</code> ===<br />
'''savedCoordinates''' : [[Oolite JavaScript Reference: Vector|Vector]] (read-write)<br />
The savedCoordinates of the ship in system co-ordinates. The savedCoordinates vector is only used by AI scripting to store a coordinate that can be used by other AI commands like <code>setDestinationFromCoordinates</code>. It are the same coordinates that are set by the AI command: <code>"setCoordinates: X Y Z"</code><br />
<br />
=== <code>scanDescription</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''scanDescription''' : String (read/write)<br />
The description of the ship in the "legal status" text shown by the [[Scanner Targeting Enhancement]]. If this is null then the default text for the ship's scan class and bounty level will be shown.<br />
<br />
=== <code>scannerDisplayColor1</code> ===<br />
'''scannerDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The first of two colours used by the ship’s scanner “lollipop”. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning <code>null</code> will restore the value from [[shipdata.plist]], or the default value for the ship’s scan class.<br />
<br />
'''See also:''' <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code>, <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code><br />
<br />
=== <code>scannerDisplayColor2</code> ===<br />
'''scannerDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The second scanner colour. If both <code>scannerDisplayColor1</code> and <code>scannerDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.<br />
<br />
'''See also:''' <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code>, <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code><br />
<br />
=== <code>scannerHostileDisplayColor1</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''scannerHostileDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The first of two colours used by the ship’s scanner “lollipop” when the ship is specifically targeting the player with hostile intent. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning <code>null</code> will restore the value from [[shipdata.plist]], or the default value for the ship’s scan class.<br />
<br />
If hostile colours are set but normal colours aren't, then the normal colours will default to those for the ship's scan class. If normal colours are set but hostile colours aren't, the scanner blip will not change colour when the ship is hostile.<br />
<br />
'''See also:''' <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code>, <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code><br />
<br />
=== <code>scannerHostileDisplayColor2</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''scannerHostileDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The second scanner colour when the ship is specifically targeting the player with hostile intent.. If both <code>scannerHostileDisplayColor1</code> and <code>scannerHostileDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.<br />
<br />
'''See also:''' <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code>, <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code><br />
<br />
=== <code>scannerRange</code> ===<br />
'''scannerRange''' : Number (read-only)<br />
The range of the ship’s scanner.<br />
<br />
=== <code>script</code> ===<br />
'''script''' : [[Oolite JavaScript Reference: Script|Script]] (read-only)<br />
The ship’s script.<br />
<br />
=== <code>scriptedMisjump</code> ===<br />
'''scriptedMisjump''' : Boolean (read/write)<br />
When <code>true</code>, the next hyperspace jump will be a misjump. The <code>scriptedMisjump</code> flag will remain <code>true</code> during the <code>shipWillExitWitchspace()</code> event handler, and will be set to <code>false</code> after the <code>shipExitedWitchspace()</code> event.<br />
<br />
=== <code>scriptedMisjumpRange</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''scriptedMisjumpRange''' : Number (read/write)<br />
If this ship misjumps, this number will be consulted to determine the length of the resulting misjump relative to the normal jump range. Setting this does not in itself force a misjump - this must occur through the usual mechanisms. Values must be greater than 0.0 and less than 1.0, and the default is 0.5 for a traditional half-way misjump. This will be reset to 0.5 at the same time as <code>[[#scriptedMisjump|scriptedMisjump]]</code> is reset to <code>false</code>.<br />
<br />
=== <code>scriptInfo</code> ===<br />
'''scriptInfo''' : Object (read-only)<br />
The contents of the <code>script_info</code> key in the ship’s ''[[shipdata.plist]]'' entry, if any. This may be any [[property list]] object, but the recommended approach is to use a dictionary whose keys have a unique prefix (such as you should be using for file names, ship names etc.). A property list dictionary is converted to a JavaScript object with properties corresponding to the dictionary’s keys. All other property list types used with Oolite have directly corresponding JavaScript types.<br><br />
When using numeric values in the scriptInfo, the JS engine is not able to detect the type reliably on all systems, so you always must explicitly convert its content to a number by using parseInt(scriptInfo.myKey) or parseFloat(scriptInfo.myKey).<br />
<br />
=== <code>shipClassName</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''shipClassName''' : String (read/write)<br />
The name of the ship class (e.g. "Python")<br />
<br />
=== <code>shipUniqueName</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''shipUniqueName''' : String (read/write)<br />
The name of this specific ship (e.g. "Sunrise of Lave")<br />
<br />
=== <code>speed</code> ===<br />
'''speed''' : Number (read-only)<br />
The ship’s current speed.<br />
<br />
'''See also:''' <code>[[#maxSpeed|maxSpeed]]</code><br />
<br />
=== <code>starboardWeapon</code> ===<br />
'''starboardWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped forward weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code><br />
<br />
=== <code>subEntities</code> ===<br />
'''subEntities''' : Array (read-only array of Ships)<br />
The ships subentities, or <code>null</code> if it has none. Special subentities such as flashers and exhaust plumes are not included.<br />
<br />
'''See also:''' <code>[[#isFrangible|isFrangible]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>subEntityCapacity</code> ===<br />
'''subEntityCapacity''' : Number (read-only integer)<br />
The original number of subentities on the ship. <br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>subEntityRotation</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''subEntityRotation''' : Quaternion (read/write)<br />
The subentity rotational velocity, expressed as a quaternion. This much rotation will be applied per second. Exact 180 degree rotations should not be specified, as it is not possible to determine what route to use to make that rotation. This property is ignored when set on non-subentities.<br />
<br />
=== <code>sunGlareFilter</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''sunGlareFilter''' : Number (read/write)<br />
The strength of the sun glare filter on this ship. It must be in the range 0 to 1 (0 is no filter).<br />
<br />
=== <code>target</code> ===<br />
'''target''' : Ship (read-write)<br />
The ship’s primary target, i.e. the entity it will attempt to shoot at. This value is automatically co-ordinated between a ship and its subentities.<br />
<br />
=== <code>temperature</code> ===<br />
'''temperature''' : Number (read/write)<br />
The ship’s temperature, normalized such that a temperature of 1.0 is the level at which a ship starts taking heat damage.<br />
<br />
=== <code>thrust</code> ===<br />
'''thrust''' : Number (read/write for NPCs, read-only for player before 1.81)<br />
The ship’s thrust, ranging from 0 to <code>maxThrust</code>. This value determines how fast the ship accelerates or decelerates, specified in m/s².<br />
<br />
'''See also:''' <code>[[#thrustVector|thrustVector]]</code><br />
<br />
=== <code>thrustVector</code> ===<br />
'''thrustVector''' : Vector3D (read-only)<br />
The inertialess velocity generated by the engines.<br />
<br />
'''See also:''' <code>[[#thrust|thrust]]</code>, <code>[[#velocity|velocity]]</code><br />
<br />
=== <code>trackCloseContacts</code> ===<br />
'''trackCloseContacts''' : Boolean (read/write)<br />
If true, AI events are generated for near collisions.<br />
<br />
=== <code>vectorForward</code> ===<br />
'''vectorForward''' : Vector3D (read-only)<br />
The vector pointing forwards from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorForward|vectorForward]]</code>.<br />
<br />
=== <code>vectorRight</code> ===<br />
'''vectorRight''' : Vector3D (read-only)<br />
The vector pointing right from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorRight|vectorRight]]</code>.<br />
<br />
=== <code>vectorUp</code> ===<br />
'''vectorUp''' : Vector3D (read-only)<br />
The vector pointing up from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorUp|vectorUp]]</code>.<br />
<br />
=== <code>velocity</code> ===<br />
'''velocity''' : Vector3D (read/write)<br />
The ship’s velocity.<br />
<br />
'''Note:''' A ship’s velocity consists of two components, inertial velocity and inertialess thrust. Generally, inertial velocity is zero (so <code>velocity</code> is equal to <code>[[#thrustVector|thrustVector]]</code>), but inertial impulses may be applied if a ship collides or is caught in an explosion. If inertial velocity is non-zero, the ship’s engines will work to counteract it. Changing the ship’s velocity will always apply inertial velocity, so for ships with non-zero <code>[[#maxThrust|maxThrust]]</code> the effect will be temporary.<br />
<br />
'''See also:''' <code>[[#thrustVector|thrustVector]]</code><br />
<br />
=== <code>weaponFacings</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''weaponFacings''' : Number (read-only, integer in range 0-15)<br />
The weapon facings available for the ship. The format is the same as the equivalent property in [[shipyard.plist]] or [[shipdata.plist]] - a bitmask with the following bits:<br><br />
1 - fore<br><br />
2 - aft<br><br />
4 - port<br><br />
8 - starboard<br />
<br />
=== <code>weaponPosition*</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''weaponPositionAft''' : Vector (read-only)<br />
'''weaponPositionForward''' : Vector (read-only)<br />
'''weaponPositionPort''' : Vector (read-only)<br />
'''weaponPositionStarboard''' : Vector (read-only)<br />
The position relative to the ship at which the appropriate laser beam will start. These properties do not imply that the ship has or can have any such weapon.<br />
<br />
=== <code>weaponRange</code> ===<br />
'''weaponRange''' : Number (read-only)<br />
The maximum range of the ship’s primary weapon. For the player it is the range of the weapon that fired as last, even when the view direction changed.<br><br />
Range values are: WEAPON_PLASMA_CANNON: 5000, WEAPON_PULSE_LASER: 12500, WEAPON_BEAM_LASER: 15000, WEAPON_MINING_LASER: 12500, WEAPON_THARGOID_LASER: 17500, WEAPON_MILITARY_LASER: 30000, WEAPON_NONE: 32000.<br><br />
(Turrets are secondary weapons with a maximum range of 6000)<br />
<br />
=== <code>withinStationAegis</code> ===<br />
'''withinStationAegis''' : Boolean (read-only)<br />
<code>true</code> if the ship is within the aegis of the system’s main station (i.e., no more than 51 200 game metres from the station, or twice scanner range).<br />
<br />
=== <code>yaw</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''yaw''' : Number (read-only)<br />
The rate of yaw of the ship in radians/second (positive for right, negative for left)<br />
<br />
== Methods ==<br />
=== <code>abandonShip</code> ===<br />
function '''abandonShip'''() : Boolean<br />
Returns <code>true</code> when the ship has an escapepod. It will launch all escapeposd on board leaving the ship behind as a empty hulk. (scanClass = CLASS_CARGO). This command does nothing when no escape-pod is present.<br><br />
Pressence of an escapepod can be tested with: <code>equipmentStatus("EQ_ESCAPE_POD") == "EQUIPMENT_OK"</code><br />
<br />
=== <code>addCollisionException</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''addCollisionException'''(exception : Ship)<br />
Prevented this ship and the selected ship from colliding. See [[#collisionExceptions|collisionExceptions]] and [[#removeCollisionException|removeCollisionException]].<br />
<br />
Prevention from collision will specifically prevent the following:<br />
<br />
* the ships colliding with each other and suffering collision damage and/or momentum change<br />
* the ships receiving collision warning events if they come close to each other<br />
* if one of the ships is a station, the other ship will not be able to dock with it even if it enters a dock<br />
<br />
This has no useful effect when applied to a subentity.<br />
<br />
Adding a collision exception which already exists has no effect but will not cause an error.<br />
<br />
=== <code>addDefenseTarget</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''addDefenseTarget'''(target : Ship)<br />
Adds the target ship to this ship's list of point [[#defenseTargets|defense targets]], if it isn't already.<br />
<br />
=== <code>adjustCargo</code>===<br />
{{oolite-method-added|1.81}}<br />
function '''adjustCargo'''(commodity : String, amount : Number) : Boolean<br />
Adjust the quantity of the specified commodity carried by the ship. Amount may be negative to remove cargo. The method will return false if the operation would fail due to insufficient free space or carried cargo, and will not make a partial adjustment in this case.<br />
<br />
=== <code>awardEquipment</code> ===<br />
function '''awardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Adds the given piece of equipment to the ship, if possible, returning <code>true</code> if successful and <code>false</code> otherwise.<br />
<br />
Example:<br />
ship.awardEquipment("EQ_ECM");<br />
<br />
'''See also:''' <code>[[#canAwardEquipment|canAwardEquipment()]]</code>, <code>[[#removeEquipment|removeEquipment()]]</code><br />
<br />
=== <code>canAwardEquipment</code> ===<br />
function '''canAwardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Tests whether it is possible to add a given equipment type. This command takes the conditions for offering inside equipment.plist into account. Returns <code>true</code> if <code>[[#awardEquipment|awardEquipment()]]</code> is expected to succeed, <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#awardEquipment|awardEquipment()]]</code><br />
<br />
=== <code>becomeCascadeExplosion</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''becomeCascadeExplosion'''()<br />
This method causes the ship to explode as if it were hit by a quirium cascade.<br />
<br />
=== <code>broadcastCascadeImminent</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''broadcastCascadeImminent'''()<br />
This method causes the ship to broadcast a message to the AIs of all nearby ships warning them of an imminent cascade explosion. It is polite to call this a few seconds before calling <code>becomeCascadeExplosion</code><br />
<br />
=== <code>broadcastDistressMessage</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''broadcastDistressMessage'''()<br />
This method causes the ship to broadcast a distress message to the AIs of all nearby ships (received also by the player as a comms message). Ships receiving a distress message will often intervene in the fight, depending on their own AI and the roles of the ships already involved.<br />
<br />
=== <code>checkCourseToDestination</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''checkCourseToDestination'''()<br />
Checks the line between the ship's current position and its destination, and returns either null or an Entity (usually a planet, sun or other ship) that this ship would risk collision with if it travelled along that course.<br />
<br />
'''See also''': [[#getSafeCourseToDestination|getSafeCourseToDestination()]]<br />
<br />
=== <code>checkScanner</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''checkScanner'''([poweredOnly : Boolean]) : Array<br />
Runs a fast scanner check and returns the results. At most 32 objects within scanner range will be returned. If the <code>poweredOnly</code> parameter is present and set to true, then only powered objects will be returned (i.e. ships with a scan class other than CLASS_CARGO or CLASS_ROCK).<br />
<br />
This method is usually considerably quicker than [[Oolite_JavaScript_Reference:_System#filteredEntities|system.filteredEntities()]] and similar methods, with little loss of accuracy, though it is still advisable to cache the result for a while before re-scanning.<br />
<br />
=== <code>clearDefenseTargets</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''clearDefenseTargets'''()<br />
Clears the ship's list of point [[#defenseTargets|defense targets]].<br />
<br />
=== <code>commsMessage</code> ===<br />
function '''commsMessage'''(message : String [,target : Ship])<br />
Make the ship broadcast the specified message. Works on buoys and subentities as well as normal ships and stations. Messages are send to a maximum of 16 ships in range and always to the player when in range. When the optional target is used, the message goes only to that ship.<br />
<br />
=== <code>damageAssessment</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''damageAssessment'''() : Number<br />
Returns a number indicating the amount of damage or supply usage by this ship. Zero means that the ship is in excellent fighting condition, while higher numbers indicate increasing amounts of damage or supply shortages.<br />
<br />
=== <code>dealEnergyDamage</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''dealEnergyDamage'''(damage : Number, idealRange : Number [, velocityBias : Number])<br />
Deals damage to all ships within a sphere centred on this ship. If this ship has an owner (e.g. it is a missile or a subentity) the damage will be credited to its owner. Damage is dealt according to the following formula:<br />
* Further away than MAX_SCANNER_RANGE (25.6km): deal no damage<br />
* At or closer than <code>idealRange</code>: deal <code>damage</code> plus (or minus, for receding objects) <code>velocityBias</code> damage for every 0.001LM of relative closing speed, up to a maximum of 1.0LM<br />
* Between <code>idealRange</code> and a derived maximum range: calculate the damage that would have been done at <code>idealRange</code>, and then divide it by the square of the ratio of <code>idealRange</code> and the real range (i.e inverse-square). The derived maximum range is the distance where a target with no relative closing speed would take 1 point of damage.<br />
<br />
As an example, the standard Oolite missile uses <code>dealEnergyDamage(170, 32.5, 0.25)</code>, has a maximum speed of 0.75LM, and its AI tries to detonate it 25m from its target. Some worked examples (for comparision, one energy bank can absorb 64 points of damage, and a standard shield generator can absorb 128 points of damage):<br />
* The missile is fired at a stationary asteroid. It detonates at 25m, within the ideal range, and the relative closing speed is 0.75LM. The asteroid takes 170 + (0.25 * 750) = 357.5 points of damage<br />
* The missile is fired at a Cobra Mk III, which tries to flee from and evade the missile at its top speed of 0.35LM. The missile detonates at 25m, and the evasive manoeuvres mean that it is not heading directly at the Cobra when it detonates. The relative closing speed is 0.38LM. The Cobra takes 170 + (0.25 * 380) = 265 points of damage.<br />
* An Anaconda freighter travelling at 0.2LM fires a missile at a distant Fer-de-lance. After the missile has travelled 150m away from the Anaconda, it is hit by an ECM pulse from the FDL, and detonates. The relative velocity is -0.55LM (the missile is travelling away from the Anaconda), so the damage at the ideal range would be 170 - (0.25 * 550) = 32.5. The damage is then divided by (150 / 32.5)<sup>2</sup>, so the Anaconda takes about 1.5 points of damage.<br />
* A missile fired at something else detonates 500m away from a Sidewinder. The inverse-square rule divides the damage by (500 / 32.5)<sup>2</sup>, so the base damage at this range (ignoring velocityBias) is only 0.7. The Sidewinder is therefore safely outside the blast radius, and is not considered for damage. <br />
<br />
=== <code>deployEscorts</code> ===<br />
function '''deployEscorts'''()<br />
Cause a random number (at least 1 if possible) of the ship's escorts which are not already attacking a target to attack this ship's primary target, unless this function has already been called for the current target without meanwhile being called for a different target.<br />
<br />
=== <code>dockEscorts</code> ===<br />
function '''dockEscorts'''()<br />
Dock the ship’s deployed escorts, if any.<br />
<br />
=== <code>dumpCargo</code> ===<br />
function '''dumpCargo'''([amount : Number, commodity: String]) : Ship<br />
Ejects one item of cargo from the ship, and returns the cargo item. Returns <code>null</code> if the ship has no cargo, anything has been ejected in the last 0.5 seconds, or if sent to the player while docked.<br />
<br />
In 1.79 or later, multiple items may be scheduled for dumping by passing the number as a parameter.<br />
<br />
In 1.81 or later, a preferred commodity may be specified (if this is not present, a random item will be dumped as usual). This preference only applies to the first item dropped, not subsequent ones.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code><br />
<br />
=== <code>ejectItem</code> ===<br />
function '''ejectItem'''(role : String) : Ship<br />
Spawns a ship of role <code>role</code> immediately behind the ship, with a slight backwards velocity. (Note: an equal and opposite reaction is applied to the parent ship, so doing this with large ships is rarely useful. <code>player.ejectItem("station")</code> may seem funny, but don’t come running to me if you have someone’s eye out.) Returns the generated ship, or <code>null</code> if no ship is generated. The scanClass of the ejected item will always be CLASS_CARGO.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code><br />
<br />
=== <code>ejectSpecificItem</code> ===<br />
function '''ejectSpecificItem'''(itemKey : String) : Ship<br />
Spawns a ship with the ''shipdata.plist'' key <code>itemKey</code> immediately behind the ship, with a slight backwards velocity. The scanClass of the ejected item will always be CLASS_CARGO.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectItem|ejectItem]]</code><br />
<br />
=== <code>enterWormhole</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''enterWormhole'''([wormhole : Wormhole])<br />
If the player has entered witchspace, but before the old system is removed from memory, this method may be used to add this ship to the contents of the specified outbound wormhole. If no parameter is given, add them to the player's wormhole.<br />
<br />
If the player is not entering witchspace, this method does nothing: the ship must fly to the wormhole in the normal way to enter it.<br />
<br />
=== <code>equipmentStatus</code> ===<br />
function '''equipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : String<br />
Tests whether the specified type of equipment is installed, and whether it is functioning. Returns one of the following strings: <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>, <code>"EQUIPMENT_UNAVAILABLE"</code> or <code>"EQUIPMENT_UNKNOWN"</code>.<br />
<br />
'''See also:''' <code>[[#setEquipmentStatus|setEquipmentStatus()]]</code><br />
<br />
=== <code>exitAI</code> ===<br />
function '''exitAI'''()<br />
Exit the current AI, restoring the previous one. Equivalent to the <code>[[AI_methods|exitAI]]:</code> AI method. May not be used on player. Will generate a warning if there are no suspended AI states.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code><br />
<br />
=== <code>exitSystem</code> ===<br />
function '''exitSystem'''([targetSystem : Number]) : Boolean<br />
Cause the ship to jump out of the system, if possible. If <code>targetSystem</code> is specified, it will attempt to jump to the specified system, otherwise a random system within range is chosen.<br />
<br />
This method can fail for various reasons, in which case it returns <code>false</code>. It always fails for the player ship.<br />
<br />
=== <code>explode</code> ===<br />
function '''explode'''()<br />
Causes the ship to explode. Works on all ships, including the main station and the player except when docked.<br />
<br />
'''See also:''' <code>[[#remove|remove()]]</code><br />
<br />
=== <code>fireECM</code> ===<br />
function '''fireECM'''()<br />
activates an ecm burst, identical as the AI command.<br />
<br />
=== <code>findNearestStation</code> ===<br />
function '''findNearestStation'''()<br />
Returns the nearest Station entity to this ship. This is quicker than manually searching <code>system.stations</code> and much quicker than using <code>system.filteredEntities()</code>.<br />
<br />
=== <code>fireMissile</code> ===<br />
function '''fireMissile'''([missile]) : Ship<br />
fireMissile() will try to fire the first available missile and will return the missile fired, or <code>null</code> if no missiles can be fired at this time. It can take the optional missile identifier parameter, to allow for a specific missile to be fired. Missiles cannot be fired if the ship hasn’t got a valid target, or if the previous missile was launched less than <code>missile_load_time</code> seconds before. If a missile type was specified, and not found on the ship, no missile will be fired.<br />
<br />
=== <code>getSafeCourseToDestination</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''getSafeCourseToDestination'''()<br />
Returns some coordinates which can be flown to as an intermediate destination to allow travel between the ship's current position and its destination without colliding with any objects on the way. Use this if <code>checkCourseToDestination</code> returns an object you are unable or unwilling to destroy to calculate a new route.<br />
<br />
'''See also''': [[#checkCourseToDestination|checkCourseToDestination()]]<br />
<br />
=== <code>getMaterials</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''getMaterials'''() : Object<br />
getMaterials() returns the ship's current materials dictionary, or if none present an empty dictionary.<br />
<br />
'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code><br />
<br />
=== <code>getShaders</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''getShaders'''() : Object<br />
getShaders() returns the ship's current shaders dictionary, or if none present an empty dictionary.<br />
<br />
'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code><br />
<br />
=== <code>hasEquipmentProviding</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''hasEquipmentProviding'''(key : String)<br />
This method returns <code>true</code> if the ship has any equipment providing the <code>key</code> equipment type, and <code>false</code> otherwise.<br />
<br />
=== <code>hasRole</code> ===<br />
function '''hasRole'''(role : String)<br />
Returns <code>true</code> if the ship has <code>role</code> among its roles, <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#roles|roles]]</code><br />
<br />
=== <code>markTargetForFines</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''markTargetForFines()'''<br />
If this ship is eligible to give out fines and the primary target has a bounty, mark the current primary target for fines, which will need to be paid when the ship docks. If used on a ship other than the player, of course, the fines are not particularly meaningful.<br />
<br />
=== <code>notifyGroupOfWormhole</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''notifyGroupOfWormhole()'''<br />
Tells the ship's group about a wormhole (usually the one this ship has just entered). Causes a <code>wormholeSuggested</code> event to occur in the scripts of other group members.<br />
<br />
=== <code>offerToEscort</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''offerToEscort(mother : Ship)'''<br />
Offer to escort the specified ship. The ship making the offer must have the same scan class as the mothership and must have one of the designated escort roles. After the mothership has made a decision this ship will receive either an <code>escortAccepted</code> or <code>escortRejected</code> ship script event.<br />
<br />
=== <code>perform*</code> ===<br />
Each of these functions switches the frame-by-frame behaviour of the ship to a different mode. It may not necessarily remain in that mode, however - for example, those modes which require a target will usually fall back to idle mode if the target is lost.<br />
<br />
==== <code>performAttack</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performAttack()'''<br />
Attack the current target with available weapons.<br />
<br />
==== <code>performCollect</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performCollect()'''<br />
Attempt to scoop up the current target. If the current target is not scoopable, it will be lost.<br />
<br />
==== <code>performEscort</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performEscort()'''<br />
Escort the group leader. If this ship is not an escort of the group leader, it will not receive escort position updates from that ship.<br />
<br />
==== <code>performFaceDestination</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFaceDestination()'''<br />
Come to a stop, and turn to face the current destination coordinates.<br />
<br />
==== <code>performFlee</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFlee()'''<br />
Flee from the current target, using injectors if possible, until it is out of scanner range.<br />
<br />
==== <code>performFlyToRangeFromDestination</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFlyToRangeFromDestination()'''<br />
Fly to the current [[#destination|destination]] coordinates, stopping when the distance between the ship and those coordinates is the [[#desiredRange|desiredRange]]. If the ship is already closer to the destination coordinates than the desired range, it will move away from the coordinates.<br />
<br />
==== <code>performHold</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performHold()'''<br />
Come to a stop, and continually turn to face the current target<br />
<br />
==== <code>performIdle</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performIdle()'''<br />
Cancel any current turns to return to level flight, then move forward at current speed.<br />
<br />
==== <code>performIntercept</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performIntercept()'''<br />
Fly to intercept (i.e. ram) the current target.<br />
<br />
==== <code>performLandOnPlanet</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performLandOnPlanet()'''<br />
Land on rather than crash into the planet. This is a slow flight, so it is recommended to get close to the planet surface before activating this behaviour.<br />
<br />
==== <code>performMining</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performMining()'''<br />
Attack the current target with a mining laser. This does not count as hostile behaviour, so cannot be used except on rocks.<br />
<br />
==== <code>performScriptedAI</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performScriptedAI()'''<br />
Request flight instructions from a [[OXP_Scripted_AI|scripted AI]] callback each frame.<br />
<br />
==== <code>performScriptedAttackAI</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performScriptedAttackAI()'''<br />
Request flight instructions, including weapons fire, from a [[OXP_Scripted_AI|scripted AI]] callback each frame.<br />
<br />
==== <code>performStop</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performStop()'''<br />
Come to a complete halt<br />
<br />
==== <code>performTumble</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performTumble()'''<br />
Come to a complete halt and rotate randomly.<br />
<br />
=== <code>reactToAIMessage</code> ===<br />
function '''reactToAIMessage'''(message : String)<br />
Immediately perform the specified handler in the ship’s current AI state.<br />
<br />
'''See also:''' <code>[[#sendAIMessage|sendAIMessage()]]</code><br />
<br />
=== <code>recallDockingInstructions</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''recallDockingInstructions'''() : Object<br />
Returns the current docking instructions as an object, and sets the destination, desired range and desired speed to match the instructions. Use this if the ship may have been interrupted while docking to ensure its flight parameters are set correctly.<br />
<br />
'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#requestDockingInstructions|requestDockingInstructions]]</code><br />
<br />
=== <code>remove</code> ===<br />
function '''remove'''([suppressDeathEvent : Boolean])<br />
Immediately removes the ship from the universe. Works on all ships except the player, including the main station.<br>It generates a [[Oolite JavaScript Reference: ship script event handlers#shipRemoved|this.shipRemoved(suppressDeathEvent)]] event. By default it will also trigger a [[Oolite JavaScript Reference: ship script event handlers#shipDied|this.shipDied()]] event, unless <code>suppressDeathEvent</code> is true.<br />
<br />
'''See also:''' <code>[[#explode|explode()]]</code><br />
<br />
=== <code>removeCollisionException</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''removeCollisionException'''(exception : Ship)<br />
Allow this ship and the selected ship to collide again. See [[#collisionExceptions|collisionExceptions]] and [[#addCollisionException|addCollisionException]].<br />
<br />
Removing a collision exception which does not exist has no effect but will not cause an error.<br />
<br />
=== <code>removeDefenseTarget</code>===<br />
{{oolite-method-added|1.79}}<br />
function '''removeDefenseTarget'''(target : Ship)<br />
Ensures that the target ship is not on this ship's list of point [[#defenseTargets|defense targets]].<br />
<br />
=== <code>removeEquipment</code> ===<br />
function '''removeEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]])<br />
Removes the given piece of equipment from the ship.<br />
This function can also be used to remove missiles (and mines). If more than one missile of the same type is found on board, only one of them will be removed.<br />
<br />
Note that in Oolite prior to 1.76.1 there was a bug which could sometimes cause the game to crash if this function was used on pylon-mounted equipment. Therefore, if you do this in your OXP, you should set (at least) 1.76.1 as the version in requires.plist<br />
<br />
Example:<br />
ship.removeEquipment("EQ_ECM");<br />
<br />
=== <code>requestDockingInstructions</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''requestDockingInstructions'''() : Object<br />
Requests the next docking instructions from the station, and returns them as an object, setting the destination, desired range and desired speed to match the instructions. Use this to get the next step in the docking sequence after completing the previous one.<br />
<br />
'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code><br />
<br />
<br />
=== <code>requestHelpFromGroup</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''requestHelpFromGroup'''()<br />
This function sends the <code>helpRequestReceived</code> event to the other ships in this ship's group and escort group, sending the name of this ship's current target as the aggressor.<br />
<br />
=== <code>restoreSubEntities</code> ===<br />
function '''restoreSubEntities'''() : Boolean<br />
Recreate all destroyed or removed subentities of the ship. Returns <code>true</code> if any subentities were added. Whether or not any subentities were added, this will also reset all subentities to their original configuration of position, orientation and other properties.<br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#isFrangible|isFrangible]]</code><br />
<br />
=== <code>selectNewMissile</code> ===<br />
function '''selectNewMissile'''() : equipmentKey<br />
selectNewMissile() will automatically select a missile for a specific ship. It uses the missile_role shipdata.plist key to find out which missiles to select. As with the system populator, there's a small chance that missiles other than the missile_role specified in shipdata will be selected.<br />
e.g.<br />
this.ship.awardEquipment(this.ship.selectNewMissile())<br />
will automatically add the 'right type' of missile to a ship, i.e. one that its captain would normally choose.<br />
<br />
=== <code>sendAIMessage</code> ===<br />
function '''sendAIMessage'''(message : String)<br />
Add a message to the ship’s AI deferred message queue. Messages in the queue are handled immediately after the next periodic <code>UPDATE</code> message. Identical messages are coalesced.<br />
<br />
'''See also:''' <code>[[#reactToAIMessage|reactToAIMessage()]]</code><br />
<br />
=== <code>setAI</code> ===<br />
function '''setAI'''(AIName : String)<br />
Set the current AI, leaving the old one suspended. Equivalent to the <code>[[AI_methods|setAITo]]:</code> AI method. May not be used on player. From 1.79 onwards AI files may either be plist-based (with a .plist extension) or Javascript-based (with a .js extension).<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code><br />
<br />
=== <code>setBounty</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''setBounty'''(bounty : Number, reason : String)<br />
Sets the ship's bounty to the new value. <code>reason</code> will be sent to [[Oolite_JavaScript_Reference:_ship_script_event_handlers#shipBountyChanged|shipBountyChanged()]].<br />
<br />
'''See also:''' <code>[[#bounty|bounty]]</code><br />
<br />
=== <code>setCargo</code> ===<br />
function '''setCargo'''(commodity : String [, count : Number]) : Boolean<br />
Attempts to create <code>count</code> weight units of the commodity <code>commodity</code> for a cargo barrel. (Can not be used to set cargo for ships) When more units are defined than 1 ton, the count is reduced to one ton. It returns false when the selected commodity is unknown. If <code>count</code> is not specified, one will be assumed.<br />
<br />
=== <code>setCargoType</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setCargoType'''(commodityType : String) : Boolean<br />
Attempts to set the ship's cargo hold to contain cargo of the specified type, discarding any cargo already present. This should generally only be used immediately after a ship is spawned. Valid cargo types are:<br />
* '''SCARCE_GOODS''': goods which are likely to be rare in the current system, usually legal.<br />
* '''PLENTIFUL_GOODS''': goods which are likely to be plentiful in the current system, usually legal.<br />
* '''MEDICAL_GOODS''': narcotics (used for the Moray Medical Boat)<br />
* '''ILLEGAL_GOODS''': various goods likely to be rare in the current system, with a strong bias towards contraband<br />
* '''PIRATE_GOODS''': as ILLEGAL_GOODS, but the total amount carried will be lower<br />
This will return false if an unrecognised commodity type is used, and will throw an exception if used on a cargo pod rather than a cargo carrier. Using it on a ship like an Asp without a cargo hold is valid but pointless.<br />
<br />
=== <code>setCrew</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setCrew'''(Object) : Boolean<br />
Sets the ship's crew to one represented by the given object (or sets the ship to uncrewed if null is given as a parameter). Returns true if this succeeds, false otherwise (if the ship is ''always'' unpiloted). The object has the same keys as [[characters.plist]], all of which are optional and will be replaced with default values if unset. They are applied in the following order:<br />
* origin system<br />
* random seed<br />
* role<br />
* the rest<br />
You can therefore set a random seed or role to get particular behaviour, and use the other keys to override it.<br />
<br />
At the moment this function only sets the first crew member (the pilot of the ship)<br />
<br />
=== <code>setEquipmentStatus</code> ===<br />
function '''setEquipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]], statusKey : String)<br />
Changes the status of the given piece of equipment from the ship. The two only valid status keys are <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>.<br />
<br />
'''Note:''' by design, this method will throw an exception if called with an equipment type that does not exist. To test whether an equipment type exists, use <code>[[Oolite JavaScript Reference: EquipmentInfo#infoForKey|EquipmentInfo.infoForKey()]]</code>, which will return <code>null</code> for undefined equipment.<br />
<br />
'''See also:''' <code>[[#equipmentStatus|equipmentStatus()]]</code><br />
<br />
=== <code>setMaterials</code> ===<br />
function '''setMaterials'''(materialDictionary : Object [, shaderDictionary : Object]) : Boolean<br />
Set the materials of the ship’s model. This works exactly like the <code>materials</code> dictionary in [[shipdata.plist]]. The optional <code>shaderDictionary</code> argument overrides <code>materialDictionary</code> if shaders are active.<br />
<br />
'''Example:'''<br />
this.ship.setMaterials({"my_ship_diffuse.png": { diffuse_map: "my_ship_damaged_diffuse.png" }});<br />
<br />
'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code><br />
<br />
=== <code>setScript</code> ===<br />
function '''setScript'''(scriptName : String)<br />
Set, or completely replace, the javascript code associated to a ship entity.<br />
<br />
=== <code>setShaders</code> ===<br />
function '''setShaders'''(shaderDictionary : Object) : Boolean<br />
Set the shader materials of the ship’s model. Equivalent to <code>[[#setMaterials|setMaterials()]]</code> with the <code>materialDictionary</code> value set to the ship’s current material dictionary.<br />
<br />
'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code><br />
<br />
=== <code>spawn</code> ===<br />
function '''spawn'''(role : String [, count : Number]) : Array<br />
Attempts to create <code>count</code> (maximum: 64) ships of role <code>role</code> close to the ship – specifically, inside the ship’s collision radius. (Since creating ships may fail, the number created may be less than <code>count</code>). The created ships are returned in an array. If <code>count</code> is not specified, one will be assumed.<br />
<br />
<code>spawn()</code> is intended for cases when a ship splits into multiple parts or drops parts. In particular, it has the following special behaviour:<br />
* The spawned ships inherit most of the temperature of the parent.<br />
* If the parent is a missile and a child has the <code>[[shipdata.plist#is_submunition|is_submunition]]</code> property, the child will be considered a missile, its target will be set to that of the parent and the child’s owner will be set to the parent.<br />
* <code>spawn()</code> does not set up escorts for the new ships, or generate witchspace effects, or do any special AI handling.<br />
<br />
=== <code>spawnOne</code> ===<br />
function '''spawnOne'''(role : String) : Ship<br />
Convenience method which calls <code>[[#spawn|spawn]](role)</code> and returns the first element of the resulting array, or <code>null</code> if <code>spawn()</code> fails.<br />
<br />
=== <code>switchAI</code> ===<br />
function '''switchAI'''(AIName : String)<br />
Set the current AI, exiting the old one. Equivalent to the <code>[[AI_methods|switchAITo]]:</code> AI method. May not be used on player.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#exitAI|exitAI()]]</code><br />
<br />
=== <code>threatAssessment</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''threatAssessment'''(full : Boolean) : Number<br />
Returns a number indicating the relative strength of the ship. If the 'full' parameter is true, additional information will be considered as part of the assessment which would generally only be known by ships which know this ship or have seen it in combat. Otherwise, only data which could reasonably be expected to be common knowledge based on the class of the ship will be included.<br />
<br />
For example, which weapon facings are available is part of the basic assessment, but what forward laser the ship has is part of the full assessment.<br />
<br />
=== <code>throwSpark</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''throwSpark'''()<br />
Sets the ship to throw a spark as if it was seriously damaged. If this ship is already scheduled to throw a spark, this does nothing.<br />
<br />
=== <code>updateEscortFormation</code> ===<br />
function '''updateEscortFormation'''()<br />
Request that the game updates the target positions for the ship’s escorts by calling the ship’s script’s <code>coordinatesForEscortPosition()</code> method.<br />
<br />
== Static Methods ==<br />
=== <code>keys</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''keys'''() : Array<br />
Returns all dataKeys of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.<br />
var dataKeysArray = Ship.keys();<br />
<br />
=== <code>keysForRole</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''keysForRole'''(role : String) : Array<br />
Returns all dataKeys of ships defined in all [[shipdata.plist]] which contains the given role.<br />
<br />
var role = "trader";<br />
var roleKeys = Ship.keysForRole( role );<br />
log("keysForRole", role + ": " + roleKeys );<br />
<br />
=== <code>roleIsInCategory</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''roles'''(role : String, category : String) : Boolean<br />
Returns whether the role given is in a particular category as defined in [[role-categories.plist]]<br />
<br />
Ship.roleIsInCategory("trader","oolite-pirate-victims"); // true<br />
<br />
=== <code>roles</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''roles'''() : Array<br />
Returns all roles of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.<br />
<br />
var roles = Ship.roles();<br />
for( var i = 0; i < roles.length; i++ ) {<br />
var roleKeys = Ship.keysForRole( roles[i] );<br />
log("roles", i + ". "+roles[i] + ": " + roleKeys );<br />
}<br />
<br />
=== <code>shipDataForKey</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''shipDataForKey'''(datakey : String) : Object<br />
Returns an object containing a representation of the raw [[shipdata.plist]] entry for a given data key, or null if the data key does not exist. Keys not defined in the shipdata.plist entry will not be defined in the object - they won't get their default values.<br />
<br />
Using the ship object properties is generally a better way to get this information, but this is useful if you want to find out what a ship might be like if you did add it.<br />
<br />
var shipdata = Ship.shipDataForKey("cobra3-trader");<br />
log("test",shipdata["name"]); // "Cobra Mark III"<br />
log("test",shipdata["ship_class_name"]); // undefined<br />
log("test",shipdata["ship_unique_name"]); // undefined<br />
log("test",shipdata["display_name"]); // undefined<br />
<br />
==See also==<br />
*[[Shipdata.plist]]<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Ship&diff=47148Oolite JavaScript Reference: Ship2015-04-02T12:51:20Z<p>Cim: /* dumpCargo */ 1.81 improvement</p>
<hr />
<div><small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Entity|Entity]]</code></small><br /><br />
<small>'''Subtypes:''' <code>[[Oolite JavaScript Reference: Station|Station]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code></small><br />
<br />
The '''<code>Ship</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing a ship, station, missile, cargo pod or other flying item – anything that can be specified in [[shipdata.plist]]. A <code>Ship</code> has all the properties and methods of a <code>Entity</code>, and several others.<br />
<br />
<code>[[Oolite JavaScript Reference: Station|Station]]</code>s and the <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code> are types of ship. Note that these more specific types have additional properties and methods.<br />
<br />
== Properties ==<br />
=== <code>accuracy</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''accuracy''' : Number (read/write, read-only and irrelevant for player ship)<br />
The accuracy of the ship's AI. Varies between -5 and +10 for ships, or 0 and +10 for missiles. Setting a value outside the allowed range will set the closest value within the allowed range.<br />
<br />
For missiles, this affects the missile tracking, with 0 being the default value.<br />
<br />
For NPC ships, this affects their combat AI in many ways. Values of +5 or higher enable various [[OXP_NPC_Combat_AI|special combat AIs]] for a tough fight.<br />
<br />
=== <code>aftWeapon</code> ===<br />
'''aftWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped aft weapon, or <code>null</code>.<br />
<br />
'''See also:''' <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>AI</code> ===<br />
'''AI''' : String (read-only)<br />
The name of the ship’s current plist-based state machine AI. If the ship is using Javascript-based AI, this will always be "<code>nullAI.plist</code>"<br />
<br />
'''See also:''' <code>[[#AIState|AIState]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AIScript|AIScript]]</code><br />
<br />
=== <code>AIFoundTarget</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''AIFoundTarget''' : Entity (read/write, read-only for player)<br />
The "found target" of the ship's AI. This is set by various AI state commands, and is often copied to the primary target with the <code>setTargetToFoundTarget</code> AI command.<br />
<br />
=== <code>AIPrimaryAggressor</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''AIPrimaryAggressor''' : Entity (read/write, read-only for player)<br />
The "primary aggressor" of the ship's AI. Often the last ship to attack this ship.<br />
<br />
=== <code>AIScript</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''AIScript''' : String (read-only)<br />
The name of the ship’s current Javascript-based AI. If the ship is using plist-based AI, this will always be "<code>oolite-nullAI.js</code>"<br />
<br />
'''See also:''' <code>[[#AIScriptWakeTime|AIScriptWakeTime]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AI|AI]]</code><br />
<br />
=== <code>AIScriptWakeTime</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''AIScriptWaketime''' : Number (read-write)<br />
The next game time at which the ship's Javascript-based AI script will receive an <code>aiAwoken</code> event.<br />
<br />
=== <code>AIState</code> ===<br />
'''AIState''' : String (read/write, read-only for player)<br />
The ship’s plist AI’s current state.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#reactToAIMessage|reactToAIMessage()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code><br />
<br />
=== <code>alertCondition</code> ===<br />
'''alertCondition''' : Number (read-only integer)<br />
The ship's current alert condition (Docked = 0, Green = 1, Yellow = 2, Red = 3). Non-Station non-Player ships are generally only found at condition Yellow or Red.<br />
<br />
'''See also:''' [[Oolite_JavaScript_Reference:_Station#alertCondition|station.alertCondition]]<br />
<br />
=== <code>autoAI</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''autoAI''' : Boolean (read-only)<br />
The value of the "<code>auto_ai</code>" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the AI of this ship to better fit into scenarios or roles. If this is false, the ship's provider would prefer you not to alter the AI of this ship but to use it as-is.<br />
<br />
=== <code>autoWeapons</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''autoWeapons''' : Boolean (read-only)<br />
The value of the "<code>auto_weapons</code>" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the properties of this ship to better fit into scenarios or roles. If this is false, the ship's provider would prefer you not to alter the properties of this ship but to use it as-is.<br />
<br />
=== <code>beaconCode</code> ===<br />
'''beaconCode''' : String (read-only in 1.76, read-write from 1.77)<br />
If the ship is a beacon, an identifying string. The first character is used for identification on the [[Advanced Space Compass]]. For non-beacons, this property is <code>null</code>. This can not be changed by script for either the player's ship or the main station.<br />
<br />
'''See also:''' <code>[[#isBeacon|isBeacon]]</code><br />
<br />
=== <code>beaconLabel</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''beaconLabel''' : String (read/write)<br />
A full label for the beacon. This is useful where the beacon code and the full beacon label do not begin with the same letter.<br />
<br />
=== <code>boundingBox</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''boundingBox''' : Vector (read-only)<br />
For ships, a vector describing the dimensions of the cuboid box containing the ship aligned to the ship axes, including all non-flasher sub-entities. For sub-entities, the dimensions of the box for the sub-entity alone.<br />
<br />
Vector components match the standard model order - <code>x</code> is width, <code>y</code> is height, <code>z</code> is length.<br />
<br />
=== <code>bounty</code> ===<br />
'''bounty''' : Number (read/write integer)<br />
The bounty on the ship.<br />
<br />
In 1.77, changes to the bounty are given a reason. If you change this directly, the reason sent to [[Oolite_JavaScript_Reference:_ship_script_event_handlers#shipBountyChanged|shipBountyChanged]] will be "scripted". To set a different reason, use [[#setBounty|setBounty]] instead.<br />
<br />
=== <code>cargoList</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''cargoList''' : Array (read-only)<br />
A list of the ship's current cargo, grouped by cargo type. For the player ship, this is equivalent to <code>player.ship.manifest.list</code><br />
<br />
=== <code>cargoSpaceCapacity</code> ===<br />
'''cargoSpaceCapacity''' : Number (read-only in 1.80, read/write in 1.81, integer)<br />
The ship’s cargo capacity, in tons.<br />
<br />
=== <code>collisionExceptions</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''collisionExceptions''' : Array (read-only)<br />
A list of ships this ship is currently prevented from colliding with. See [[#addCollisionException|addCollisionException]] and [[#removeCollisionException|removeCollisionException]].<br />
<br />
=== <code>commodity</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''commodity''' : String (read-only)<br />
The commodity for cargo containers as a lowercase string. Returns <code>null</code> for non-cargo ships. For scripted cargo that has no specific cargo defined, it returns the general description "goods".<br />
<br />
=== <code>commodityAmount</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''commodityAmount''' : Number (read-only)<br />
The amount of commodity in a cargo container. (not the number of containers in a ship)<br />
<br />
=== <code>contracts</code> ===<br />
'''contracts''' : Array (read-only NSDictionary)<br />
The ship’s contracts. (For now only available for the player). Each contract contains the entries: <code>commodity: string, quantity: integer, description: string, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
<br />
For example, the information of the first contract can be obtained by:<br />
player.ship.contracts[0].commodity<br />
player.ship.contracts[0].quantity<br />
player.ship.contracts[0].description<br />
player.ship.contracts[0].start<br />
player.ship.contracts[0].destination<br />
player.ship.contracts[0].startName<br />
player.ship.contracts[0].destinationName<br />
player.ship.contracts[0].eta // Estimated Time of Arrival.<br />
player.ship.contracts[0].etaDescription<br />
player.ship.contracts[0].fee // The profit of the contract, paid out on successful delivery.<br />
player.ship.contracts[0].premium // The sum paid to obtain the goods and paid back on successful delivery.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this contract, and premium was the amount the player had to pay to secure this contract.<br />
<br />
=== <code>cloakAutomatic</code> ===<br />
'''cloakAutomatic''' : Boolean (read/write)<br />
If <code>true</code> (the default), the ship will automatically engage its cloak while attacking. Otherwise, it must be managed by a script. The corresponding ''[[shipdata.plist]]'' key is <code>cloak_automatic</code>.<br />
<br />
=== <code>crew</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''crew''' : Array (read-only)<br />
An array containing the ship's crew. Each crew member is represented as a dictionary. Note that in current Oolite versions ships only have a single crew member defined.<br />
<br />
=== <code>cruiseSpeed</code> ===<br />
'''cruiseSpeed''' : Number (read-only nonnegative)<br />
The ship’s “normal” <code>[[#desiredSpeed|desiredSpeed]]</code>, used in normal flight. Normally this is 80 % of <code>[[#maxSpeed|maxSpeed]]</code>, but it may be lowered when accepting a slow escort.<br />
<br />
=== <code>currentWeapon</code> ===<br />
{{oolite-prop-added|1.77}} <br />
'''currentWeapon''' : EquipmentType (read/write)<br />
A shortcut property to whichever of <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code> or <code>[[#starboardWeapon|starboardWeapon]]</code> represents the ship's currently active laser mount.<br />
<br />
=== <code>dataKey</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''dataKey''' : String (read-only)<br />
The ship data key used to define this ship (e.g. <code>adder-player</code> or <code>coriolis-station</code>)<br />
<br />
=== <code>defenseTargets</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''defenseTargets''' : Array (read-only)<br />
The array of defense targets that the ship has. If the ship has point defense weapons (turrets, thargoid lasers) it may fire them at these targets if it cannot hit its primary target.<br />
<br />
'''See also:''' <code>[[#addDefenseTarget|addDefenseTarget]]</code>, <code>[[#clearDefenseTargets|clearDefenseTargets]]</code><br />
<br />
=== <code>desiredRange</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''desiredRange''' : Number (read/write nonnegative, read-only for player)<br />
The range the AI uses in various AI routines to set a distance between the ship and another object - for example, the radius of a sphere around a destination point, or the distance to flee from a hostile ship.<br />
<br />
=== <code>desiredSpeed</code> ===<br />
'''desiredSpeed''' : Number (read/write nonnegative, read-only for player)<br />
The speed the AI will attempt to maintain. The AI core and AI script may change this from time to time. The corresponding AI method is <code>setSpeedFactorTo:</code>; a speed factor of 1.0 corresponds to a <code>desiredSpeed</code> equal to <code>[[#maxSpeed|maxSpeed]]</code>.<br />
<br />
'''See also:''' <code>[[#cruiseSpeed|cruiseSpeed]]</code><br />
<br />
=== <code>destination</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''destination''' : Vector (read/write, read-only for player)<br />
The destination coordinates for the AI, used in behaviours such as <code>performFlyToRangeFromDestination</code>.<br />
<br />
=== <code>destinationSystem</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''destinationSystem''' : Number (read/write)<br />
The destination system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.<br />
<br />
=== <code>displayName</code> ===<br />
'''displayName''' : String (read/write, read-only for player)<br />
The name of the ship as seen by the player. By default in 1.78 or earlier it is the same as <code>[[#name|name]]</code>. In 1.79 or later it is a combination of [[#shipClassName|shipClassName]] and [[#shipUniqueName|shipUniqueName]]<br />
<br />
=== <code>dockingInstructions</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''dockingInstructions''' : Object (read-only)<br />
If the ship is currently attempting to dock with a station, this describes the next step on its docking procedure<br />
<br />
{<br />
station: [Station "Coriolis Station" "Coriolis Station" position: (-31043.6, -94232.3, 619036) scanClass: CLASS_STATION status: STATUS_ACTIVE],<br />
match_rotation: 0,<br />
ai_message: "APPROACH_COORDINATES",<br />
speed: 512,<br />
destination: {<br />
x: -28033.37401563089,<br />
y: -92813.76688970842,<br />
z: 622226.0625336492<br />
},<br />
range: 96<br />
}<br />
<br />
'''See also:''' <code>[[#requestDockingInstructions|requestDockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code><br />
<br />
=== <code>energyRechargeRate</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''energyRechargeRate''' : Number (read-only, read/write from 1.81)<br />
The rate at which energy is replenished in every second. The corresponding ''[[shipdata.plist]]'' key is <code>energy_recharge_rate</code>.<br />
<br />
Note for the player ship that this includes the boost from an extra or naval energy unit, and NPC (but not player) ships with military shield boosters also have an increase to this in lieu of actual shields.<br />
<br />
=== <code>entityPersonality</code> ===<br />
'''entityPersonality''' : Number (read-only integer)<br />
A random number in the range 0..32767 which is generated when the ship is created. Equivalent to the <code>entityPersonalityInt</code> [[Shaders in Oolite: uniforms#Ship|uniform binding]].<br />
<br />
=== <code>equipment</code> ===<br />
'''equipment''' : Array of [[Oolite_JavaScript_Reference:_EquipmentInfo|EquipmentInfo ]] (read-only)<br />
The equipment a ship is carrying.<br />
<br />
=== <code>escortGroup</code> ===<br />
'''escortGroup''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]<br />
The ship’s deployed escorts.<br />
<br />
'''See also:''' <code>[[#maxEscorts|maxEscorts]]</code><br />
<br />
=== <code>escorts</code> ===<br />
'''escorts''' : Array (read-only array of [[Oolite JavaScript Reference: Entity|Entity]]s)<br />
The ship’s deployed escorts.<br />
<br />
=== <code>exhaustEmissiveColor</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''exhaustEmissiveColor''' : Color (read/write)<br />
The baseline colour of the ship's exhaust. Damage to the ship, and use of injectors and torus drive, apply a fixed transformation to this colour, so not all colours are effective as exhaust colours.<br />
<br />
=== <code>exhausts</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''exhausts''' : Array (read-only)<br />
An array of the ship's [[Oolite_JavaScript_Reference:_ExhaustPlume|ExhaustPlume]] subentities.<br />
<br />
=== <code>extraCargo</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''extraCargo''' : Number (read-only integer)<br />
The amount the cargo capacity increases when an extra cargobay is installed. The corresponding ''[[shipdata.plist]]'' key is <code>extra_cargo</code>.<br />
<br />
=== <code>flashers</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''flashers''' : Array (read-only)<br />
An array of the ship's [[Oolite_JavaScript_Reference:_Flasher|Flasher]] subentities.<br />
<br />
=== <code>forwardWeapon</code> ===<br />
'''forwardWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped forward weapon, or <code>null</code>.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>fuel</code> ===<br />
'''fuel''' : Number (read/write)<br />
The ship’s current fuel capacity, in LY. The game will limit this to the range 0..7, and round it off to the nearest tenth.<br />
<br />
'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#fuelLeakRate|PlayerShip.fuelLeakRate]]</code><br />
<br />
=== <code>fuelChargeRate</code> ===<br />
'''fuelChargeRate''' : Number (read-only)<br />
The cost, relative to the cost for a new Cobra III, of a unit of fuel. When buying fuel for a ship, the price in [[equipment.plist]] will be multiplied by this number.<br />
<br />
=== <code>group</code> ===<br />
'''group''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]<br />
Contains ship’s belonging to each other. Added pirate groups are an example or a station with its launched defenders.<br><br />
A group is an individual object that can be linked to several ships belonging to the same group. When a ship dies and the group object has still owners, the group stays active as object. The group is only removed from memory after the last ship that had this group as property is removed.<br><br />
Adding a group to a ship does not automatic puts that ship in the group. For that to happen you need also use the addShip() command. <br />
e.g. <br />
this.ship.group = new ShipGroup();<br />
this.ship.group.addShip(this.ship);<br />
<br />
=== <code>hasHostileTarget</code> ===<br />
'''hasHostileTarget''' : Boolean (read-only)<br />
<code>true</code> if the ship’s AI is trying to kill something, <code>false</code> otherwise. Always <code>false</code> for the player.<br />
<br />
=== <code>hasHyperspaceMotor</code> ===<br />
'''hasHyperspaceMotor''' : Boolean (read-only)<br />
True if the ship can make witchspace jumps. The corresponding ''[[shipdata.plist]]'' entry is <code>hyperspace_motor</code>.<br />
<br />
=== <code>hasSuspendedAI</code> ===<br />
'''hasSuspendedAI''' : Boolean (read-only)<br />
<code>true</code> if the ship has suspended AIs, <code>false</code> otherwise.<br />
<br />
=== <code>heatInsulation</code> ===<br />
'''heatInsulation''' : Number (read/write)<br />
The ship’s heat insulation factor. 1.0 is normal, higher values mean more resistance to heat.<br />
<br />
Note that in 1.80 and earlier writes to this property had no effect on the player ship.<br />
<br />
=== <code>homeSystem</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''homeSystem''' : Number (read/write)<br />
The home system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.<br />
<br />
=== <code>hyperspaceSpinTime</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''hyperspaceSpinTime''' : Number (read/write)<br />
The length of the ship's hyperspace countdown.<br />
<br />
Setting this to a negative value disables the drive entirely.<br />
<br />
Note that most NPC ship jumps use <code>ship.exitSystem()</code> to make the jump, which does not have a delay. Provided this value is zero or positive, the ship will jump instantly if <code>ship.exitSystem()</code> is called. The AI must use this property elsewhere if a delay before jumping is required.<br />
<br />
=== <code>injectorBurnRate</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorBurnRate''' : Number (read/write)<br />
The rate at which the ship's injectors burn fuel in deci-LY per second. The default is 0.25.<br />
<br />
=== <code>injectorSpeedFactor</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorSpeedFactor''' : Number (read/write)<br />
The multiplier to maximum speed granted to this ship when it is using injectors. The default is 7, and values must be between 1.0 and 32.0 (the torus drive's speed)<br />
<br />
=== <code>isBeacon</code> ===<br />
'''isBeacon''' : Boolean (read-only)<br />
<code>true</code> if the ship is a beacon (i.e., can show up on the [[Advanced Space Compass]] with a character indicating its identity), <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#beaconCode|beaconCode]]</code><br />
<br />
=== <code>isBoulder</code> ===<br />
'''isBoulder''' : Boolean (read/write)<br />
<code>true</code> if the ship is a boulder (i.e., has the role "boulder in its roleset)<br />
<br />
=== <code>isCargo</code> ===<br />
'''isCargo''' : Boolean (read-only)<br />
<code>true</code> if the ship is cargo (i.e., has scan_class CLASS_CARGO and contains at least one unit)<br />
<br />
=== <code>isCloaked</code> ===<br />
'''isCloaked''' : Boolean (read/write)<br />
<code>true</code> if the ship has a cloaking device which is currently active <code>false</code> otherwise. If the ship has a cloaking device and sufficient energy to use it (<code>energy > 0.75 * [[Oolite JavaScript Reference: Entity#maxEnergy|maxEnergy]]</code>), you can activate it by setting <code>isCloaked</code> to <code>true</code>.<br />
<br />
=== <code>isDerelict</code> ===<br />
'''isDerelict''' : Boolean (read-only)<br />
<code>true</code> if the ship is a derelict (i.e., the pilot has ejected from the ship, or the ship was created with the ship-key: "is_hulk")<br />
<br />
=== <code>isFleeing</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isFleeing''' : Boolean (read-only)<br />
<code>true</code> if the ship is currently fleeing combat. This may be queried for the player ship too, though the value is somewhat of a guess in that case as it's impossible to say for certain what the player is intending by their actions.<br />
<br />
=== <code>isFrangible</code> ===<br />
'''isFrangible''' : Boolean (read-only)<br />
<code>true</code> if the ship is frangible (i.e., its subentities can be destroyed separately from the main ship), <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>isJamming</code> ===<br />
'''isJamming''' : Boolean (read-only)<br />
<code>true</code> if the ship has a military scanner jammer which is currently active <code>false</code> otherwise.<br />
<br />
=== <code>isMinable</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isMinable''' : Boolean (read-only)<br />
<code>true</code> if the ship will break up usefully when hit by a mining laser, <code>false</code> otherwise. By default this is true for anything with "asteroid" or "boulder" in its role list - if you need to add anything which miners shouldn't be shooting at to those roles, give it <code>"no_boulders" = yes;</code> in its [[shipdata.plist]].<br />
<br />
=== <code>isMine</code> ===<br />
'''isMine''' : Boolean (read-only)<br />
<code>true</code> if the ship is a mine, <code>false</code> otherwise.<br />
<br />
=== <code>isMissile</code> ===<br />
'''isMissile''' : Boolean (read-only)<br />
<code>true</code> if the ship is a missile, <code>false</code> otherwise.<br />
<br />
=== <code>isPiloted</code> ===<br />
'''isPiloted''' : Boolean (read-only)<br />
<code>true</code> if the ship has a pilot on board, <code>false</code> otherwise. Generally have ships, station and escape pods pilots and have cargo, rocks, missiles or buoys no pilots.<br />
<br />
=== <code>isPirate</code> ===<br />
'''isPirate''' : Boolean (read-only)<br />
<code>true</code> if the ship is a pirate vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "pirate"</code>.<br />
<br />
=== <code>isPirateVictim</code> ===<br />
'''isPirateVictim''' : Boolean (read-only)<br />
<code>true</code> if the ship’s [[#primaryRole|primary role]] is listed in ''pirate-victim-roles.plist'', <code>false</code> otherwise. This is the same test used by the pirate AI to select victims.<br />
<br />
=== <code>isPolice</code> ===<br />
'''isPolice''' : Boolean (read-only)<br />
<code>true</code> if the ship is a police vessel, <code>false</code> otherwise. Currently equivalent to <code>[[Oolite JavaScript Reference: Entity#scanClass|scanClass]] == "CLASS_POLICE"</code>.<br />
<br />
=== <code>isRock</code> ===<br />
'''isRock''' : Boolean (read-only)<br />
<code>true</code> if the ship is a rock (i.e., has scan_class: CLASS_ROCK)<br />
<br />
=== <code>isThargoid</code> ===<br />
'''isThargoid''' : Boolean (read-only)<br />
<code>true</code> if the ship is a Thargoid vessel, <code>false</code> otherwise. Currently equivalent to <code>[[Oolite JavaScript Reference: Entity#scanClass|scanClass]] == "CLASS_THARGOID"</code>.<br />
<br />
=== <code>isTrader</code> ===<br />
'''isTrader''' : Boolean (read-only)<br />
<code>true</code> if the ship is a merchant vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "trader" || isPlayer</code>. '''Note:''' <code>[[#isPirateVictim|isPirateVictim]]</code> may be a better choice in many cases.<br />
<br />
=== <code>isTurret</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isTurret''' : Boolean (read-only)<br />
<code>true</code> if the ship is a plasma turret sub-entity, <code>false</code> otherwise.<br />
<br />
=== <code>isWeapon</code> ===<br />
'''isWeapon''' : Boolean (read-only)<br />
<code>true</code> if the ship is a weapon, <code>false</code> otherwise. Currently equivalent to <code>[[#isMissile|isMissile]] || [[#isMine|isMine]] </code>, but new categories of weapon could be added in future.<br />
<br />
=== <code>laserHeatLevel</code>* ===<br />
{{Oolite-prop-added|1.77}}<br />
'''laserHeatLevel''' : Number (read-only, 0 to 1)<br />
The temperature of the ship's currently active weapon. Thermal cut-out is active above 0.85. For non-player ships, if their forward weapon is empty, then the temperature of the forward weapon may be the temperature of a subentity forward weapon.<br />
'''laserHeatLevelAft''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelForward''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelPort''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelStarboard''' : Number (read-only, 0 to 1)<br />
The temperature of specific laser mounts can also be queried.<br />
<br />
=== <code>lightsActive</code> ===<br />
'''lightsActive''' : Boolean (read-write)<br />
Setting this property to <code>true</code> turns on all the entity’s flashers, and setting it to <code>false</code> turns them off. Setting it sets the <code>lightsActive</code> property for all subentities, but subentities’ setting can also be manipulated separately. In addition to affecting flashers, the value can be used by shaders.<br />
<br />
Note: <code>lightsActive</code> is always <code>true</code> when a ship is spawned, although individual flashers may be off because they have <code>initially_on</code> set to false in their ''shipdata.plist'' declarations.<br />
<br />
=== <code>markedForFines</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''markedForFines''' : Boolean (read-only)<br />
<code>True</code> if the ship has been marked for fines the next time it docks at this system's main station.<br />
<br />
'''See also''' : [[#markTargetForFines|markTargetForFines()]]<br />
<br />
=== <code>maxEscorts</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxEscorts''' : Number (read/write)<br />
The maximum number of escorts this ship can have. This cannot be set lower than the number of escorts it currently has, or higher than the value of the MAX_ESCORTS constant (currently 16). There may be other reasons why a ship can have fewer escorts than the value of <code>maxEscorts</code> (for instance, ships which are escorts cannot have their own escorts)<br />
<br />
'''See also:''' <code>[[#escortGroup|escortGroup]]</code><br />
<br />
=== <code>maxPitch</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxPitch''' : Number (read-only, read/write from 1.81)<br />
The maximum pitch rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#pitch|pitch]]</code><br />
<br />
=== <code>maxRoll</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxRoll''' : Number (read-only, read/write from 1.81)<br />
The maximum roll rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#roll|roll]]</code><br />
<br />
=== <code>maxSpeed</code> ===<br />
'''maxSpeed''' : Number (read-only, read/write from 1.81)<br />
The ship’s maximum speed under normal power. Note that <code>[[#speed|speed]]</code> may exceed this when [[witch fuel injectors]] or [[hyperspeed]] are in use.<br />
<br />
'''See also:''' <code>[[#speed|speed]]</code><br />
<br />
=== <code>maxThrust</code> ===<br />
'''maxThrust''' : Number (read-only, read/write from 1.81)<br />
The ship’s maximum <code>[[#thrust|thrust]]</code>. This value is the one defined as <code>thrust</code> in ''[[Shipdata.plist#thrust|shipdata.plist]]''.<br />
<br />
=== <code>maxYaw</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxYaw''' : Number (read-only, read/write from 1.81)<br />
The maximum yaw rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#yaw|yaw]]</code><br />
<br />
=== <code>missileCapacity</code> ===<br />
'''missileCapacity''' : Number (read-only integer)<br />
The maximum number of missiles the ship can carry.<br />
<br />
=== <code>missileLoadTime</code> ===<br />
'''missileLoadTime''' : Number (read-write nonnegative)<br />
The minimum amount of time between two missiles. The corresponding ''[[shipdata.plist]]'' key is <code>missile_load_time</code>.<br />
<br />
=== <code>missiles</code> ===<br />
'''missiles''' : Array (read-only array of [[Oolite JavaScript Reference: EquipmentInfo|EquipmentInfo]])<br />
The ship’s loaded missiles.<br />
<br />
=== <code>name</code> ===<br />
'''name''' : String (read/write, read-only for player)<br />
The name of the ship type (<code>name</code> key in [[shipdata.plist]]).<br />
<br />
''Note'': while <code>name</code> can be changed, this is discouraged (and will probably not be supported in Oolite 2.0). Use <code>[[#displayName|displayName]]</code> instead.<br />
<br />
=== <code>parcelCount</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''parcelCount''' : Number (read-only integer)<br />
The ship’s current number of parcels.<br />
<br />
=== <code>parcels</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''parcels''' : Array (read-only NSDictionary)<br />
The ship’s parcels. (For now only available for the player). Each parcel list contains the entries: <code>name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
For example, the information of the first contract can be obtained by:<br />
player.ship.parcels[0].name<br />
player.ship.parcels[0].start<br />
player.ship.parcels[0].destination<br />
player.ship.parcels[0].startName<br />
player.ship.parcels[0].destinationName<br />
player.ship.parcels[0].eta<br />
player.ship.parcels[0].etaDescription<br />
player.ship.parcels[0].fee // The final fee, paid out on successful delivery.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this parcel.<br />
<br />
=== <code>passengerCapacity</code> ===<br />
'''passengerCapacity''' : Number (read-only integer)<br />
The ship’s maximum passenger capacity.<br />
<br />
=== <code>passengerCount</code> ===<br />
'''passengerCount''' : Number (read-only integer)<br />
The ship’s current number of passengers.<br />
<br />
=== <code>passengers</code> ===<br />
'''passengers''' : Array (read-only NSDictionary)<br />
The ship’s passengers. (For now only available for the player). Each passengers list contains the entries: <code>name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
For example, the information of the first contract can be obtained by:<br />
player.ship.passengers[0].name<br />
player.ship.passengers[0].start<br />
player.ship.passengers[0].destination<br />
player.ship.passengers[0].startName<br />
player.ship.passengers[0].destinationName<br />
player.ship.passengers[0].eta<br />
player.ship.passengers[0].etaDescription<br />
player.ship.passengers[0].fee // The final fee, paid out on successful delivery.<br />
player.ship.passengers[0].premium // The advance fee, already paid on acceptance of the contract.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this passenger, and premium shows the amount the player received when the passenger boarded the ship.<br />
<br />
=== <code>pitch</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''pitch''' : Number (read-only)<br />
The rate of pitch of the ship in radians/second (positive for dive, negative for climb)<br />
<br />
=== <code>portWeapon</code> ===<br />
'''portWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped port weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>potentialCollider</code> ===<br />
'''potentialCollider''' : [[Oolite JavaScript Reference: Entity|Entity]] (read-only)<br />
The entity the ship is currently trying not to crash into, if any.<br />
<br />
=== <code>primaryRole</code> ===<br />
'''primaryRole''' : String (read/write, read-only for player)<br />
The main role of the ship; the role for which it was created. For instance, if a ship’s ''shipdata.plist'' entry specifies the roles “pirate trader(0.5) escort”, and a ship of that type is spawned to be a trader, its <code>primaryRole</code> is <code>"trader"</code>, its <code>roles</code> is <code>["escort", "pirate", "trader"]</code> and its <code>roleWeights</code> is <code> { "escort":1, "pirate":1, "trader":0.5}</code>.<br />
<br />
'''See also:''' <code>[[#roles|roles]]</code>, <code>[[#roleWeights|roleWeights]]</code><br />
<br />
=== <code>reportAIMessages</code> ===<br />
'''reportAIMessages''' : Boolean (read/write)<br />
Debugging facility: set to <code>true</code> to dump information about AI activity to the log. <br />
<br />
=== <code>roleWeights</code> ===<br />
'''roleWeights''' : Object (read-only)<br />
The probabilities for each role in <code>[[#roles|roles]]</code>.<br />
<br />
Example:<br />
this.pirateProb = ship.roleWeights["pirate"]<br />
<br />
'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roles|roles]]</code><br />
<br />
=== <code>roles</code> ===<br />
'''roles''' : Array (read-only array of Strings)<br />
The roles of the ship. This consists of the roles specified in the ship’s ''shipdata.plist'' entry, as well as the <code>[[#primaryRole|primaryRole]]</code> if it is not among those.<br />
<br />
'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roleWeights|roleWeights]]</code>, <code>[[#hasRole|hasRole()]]</code><br />
<br />
=== <code>roll</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''roll''' : Number (read-only, read/write for stations)<br />
The rate of roll of the ship in radians/second (positive for anti-clockwise, negative for clockwise)<br />
<br />
For stations, this can be set to any value between -2 and +2 to adjust their roll rate. The default is 0.4, or the value specified by the <code>station_roll</code> key in shipdata.plist.<br />
<br />
=== <code>savedCoordinates</code> ===<br />
'''savedCoordinates''' : [[Oolite JavaScript Reference: Vector|Vector]] (read-write)<br />
The savedCoordinates of the ship in system co-ordinates. The savedCoordinates vector is only used by AI scripting to store a coordinate that can be used by other AI commands like <code>setDestinationFromCoordinates</code>. It are the same coordinates that are set by the AI command: <code>"setCoordinates: X Y Z"</code><br />
<br />
=== <code>scanDescription</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''scanDescription''' : String (read/write)<br />
The description of the ship in the "legal status" text shown by the [[Scanner Targeting Enhancement]]. If this is null then the default text for the ship's scan class and bounty level will be shown.<br />
<br />
=== <code>scannerDisplayColor1</code> ===<br />
'''scannerDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The first of two colours used by the ship’s scanner “lollipop”. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning <code>null</code> will restore the value from [[shipdata.plist]], or the default value for the ship’s scan class.<br />
<br />
'''See also:''' <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code>, <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code><br />
<br />
=== <code>scannerDisplayColor2</code> ===<br />
'''scannerDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The second scanner colour. If both <code>scannerDisplayColor1</code> and <code>scannerDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.<br />
<br />
'''See also:''' <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code>, <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code><br />
<br />
=== <code>scannerHostileDisplayColor1</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''scannerHostileDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The first of two colours used by the ship’s scanner “lollipop” when the ship is specifically targeting the player with hostile intent. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning <code>null</code> will restore the value from [[shipdata.plist]], or the default value for the ship’s scan class.<br />
<br />
If hostile colours are set but normal colours aren't, then the normal colours will default to those for the ship's scan class. If normal colours are set but hostile colours aren't, the scanner blip will not change colour when the ship is hostile.<br />
<br />
'''See also:''' <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code>, <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code><br />
<br />
=== <code>scannerHostileDisplayColor2</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''scannerHostileDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The second scanner colour when the ship is specifically targeting the player with hostile intent.. If both <code>scannerHostileDisplayColor1</code> and <code>scannerHostileDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.<br />
<br />
'''See also:''' <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code>, <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code><br />
<br />
=== <code>scannerRange</code> ===<br />
'''scannerRange''' : Number (read-only)<br />
The range of the ship’s scanner.<br />
<br />
=== <code>script</code> ===<br />
'''script''' : [[Oolite JavaScript Reference: Script|Script]] (read-only)<br />
The ship’s script.<br />
<br />
=== <code>scriptedMisjump</code> ===<br />
'''scriptedMisjump''' : Boolean (read/write)<br />
When <code>true</code>, the next hyperspace jump will be a misjump. The <code>scriptedMisjump</code> flag will remain <code>true</code> during the <code>shipWillExitWitchspace()</code> event handler, and will be set to <code>false</code> after the <code>shipExitedWitchspace()</code> event.<br />
<br />
=== <code>scriptedMisjumpRange</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''scriptedMisjumpRange''' : Number (read/write)<br />
If this ship misjumps, this number will be consulted to determine the length of the resulting misjump relative to the normal jump range. Setting this does not in itself force a misjump - this must occur through the usual mechanisms. Values must be greater than 0.0 and less than 1.0, and the default is 0.5 for a traditional half-way misjump. This will be reset to 0.5 at the same time as <code>[[#scriptedMisjump|scriptedMisjump]]</code> is reset to <code>false</code>.<br />
<br />
=== <code>scriptInfo</code> ===<br />
'''scriptInfo''' : Object (read-only)<br />
The contents of the <code>script_info</code> key in the ship’s ''[[shipdata.plist]]'' entry, if any. This may be any [[property list]] object, but the recommended approach is to use a dictionary whose keys have a unique prefix (such as you should be using for file names, ship names etc.). A property list dictionary is converted to a JavaScript object with properties corresponding to the dictionary’s keys. All other property list types used with Oolite have directly corresponding JavaScript types.<br><br />
When using numeric values in the scriptInfo, the JS engine is not able to detect the type reliably on all systems, so you always must explicitly convert its content to a number by using parseInt(scriptInfo.myKey) or parseFloat(scriptInfo.myKey).<br />
<br />
=== <code>shipClassName</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''shipClassName''' : String (read/write)<br />
The name of the ship class (e.g. "Python")<br />
<br />
=== <code>shipUniqueName</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''shipUniqueName''' : String (read/write)<br />
The name of this specific ship (e.g. "Sunrise of Lave")<br />
<br />
=== <code>speed</code> ===<br />
'''speed''' : Number (read-only)<br />
The ship’s current speed.<br />
<br />
'''See also:''' <code>[[#maxSpeed|maxSpeed]]</code><br />
<br />
=== <code>starboardWeapon</code> ===<br />
'''starboardWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped forward weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code><br />
<br />
=== <code>subEntities</code> ===<br />
'''subEntities''' : Array (read-only array of Ships)<br />
The ships subentities, or <code>null</code> if it has none. Special subentities such as flashers and exhaust plumes are not included.<br />
<br />
'''See also:''' <code>[[#isFrangible|isFrangible]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>subEntityCapacity</code> ===<br />
'''subEntityCapacity''' : Number (read-only integer)<br />
The original number of subentities on the ship. <br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>subEntityRotation</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''subEntityRotation''' : Quaternion (read/write)<br />
The subentity rotational velocity, expressed as a quaternion. This much rotation will be applied per second. Exact 180 degree rotations should not be specified, as it is not possible to determine what route to use to make that rotation. This property is ignored when set on non-subentities.<br />
<br />
=== <code>sunGlareFilter</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''sunGlareFilter''' : Number (read/write)<br />
The strength of the sun glare filter on this ship. It must be in the range 0 to 1 (0 is no filter).<br />
<br />
=== <code>target</code> ===<br />
'''target''' : Ship (read-write)<br />
The ship’s primary target, i.e. the entity it will attempt to shoot at. This value is automatically co-ordinated between a ship and its subentities.<br />
<br />
=== <code>temperature</code> ===<br />
'''temperature''' : Number (read/write)<br />
The ship’s temperature, normalized such that a temperature of 1.0 is the level at which a ship starts taking heat damage.<br />
<br />
=== <code>thrust</code> ===<br />
'''thrust''' : Number (read/write for NPCs, read-only for player before 1.81)<br />
The ship’s thrust, ranging from 0 to <code>maxThrust</code>. This value determines how fast the ship accelerates or decelerates, specified in m/s².<br />
<br />
'''See also:''' <code>[[#thrustVector|thrustVector]]</code><br />
<br />
=== <code>thrustVector</code> ===<br />
'''thrustVector''' : Vector3D (read-only)<br />
The inertialess velocity generated by the engines.<br />
<br />
'''See also:''' <code>[[#thrust|thrust]]</code>, <code>[[#velocity|velocity]]</code><br />
<br />
=== <code>trackCloseContacts</code> ===<br />
'''trackCloseContacts''' : Boolean (read/write)<br />
If true, AI events are generated for near collisions.<br />
<br />
=== <code>vectorForward</code> ===<br />
'''vectorForward''' : Vector3D (read-only)<br />
The vector pointing forwards from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorForward|vectorForward]]</code>.<br />
<br />
=== <code>vectorRight</code> ===<br />
'''vectorRight''' : Vector3D (read-only)<br />
The vector pointing right from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorRight|vectorRight]]</code>.<br />
<br />
=== <code>vectorUp</code> ===<br />
'''vectorUp''' : Vector3D (read-only)<br />
The vector pointing up from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorUp|vectorUp]]</code>.<br />
<br />
=== <code>velocity</code> ===<br />
'''velocity''' : Vector3D (read/write)<br />
The ship’s velocity.<br />
<br />
'''Note:''' A ship’s velocity consists of two components, inertial velocity and inertialess thrust. Generally, inertial velocity is zero (so <code>velocity</code> is equal to <code>[[#thrustVector|thrustVector]]</code>), but inertial impulses may be applied if a ship collides or is caught in an explosion. If inertial velocity is non-zero, the ship’s engines will work to counteract it. Changing the ship’s velocity will always apply inertial velocity, so for ships with non-zero <code>[[#maxThrust|maxThrust]]</code> the effect will be temporary.<br />
<br />
'''See also:''' <code>[[#thrustVector|thrustVector]]</code><br />
<br />
=== <code>weaponFacings</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''weaponFacings''' : Number (read-only, integer in range 0-15)<br />
The weapon facings available for the ship. The format is the same as the equivalent property in [[shipyard.plist]] or [[shipdata.plist]] - a bitmask with the following bits:<br><br />
1 - fore<br><br />
2 - aft<br><br />
4 - port<br><br />
8 - starboard<br />
<br />
=== <code>weaponPosition*</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''weaponPositionAft''' : Vector (read-only)<br />
'''weaponPositionForward''' : Vector (read-only)<br />
'''weaponPositionPort''' : Vector (read-only)<br />
'''weaponPositionStarboard''' : Vector (read-only)<br />
The position relative to the ship at which the appropriate laser beam will start. These properties do not imply that the ship has or can have any such weapon.<br />
<br />
=== <code>weaponRange</code> ===<br />
'''weaponRange''' : Number (read-only)<br />
The maximum range of the ship’s primary weapon. For the player it is the range of the weapon that fired as last, even when the view direction changed.<br><br />
Range values are: WEAPON_PLASMA_CANNON: 5000, WEAPON_PULSE_LASER: 12500, WEAPON_BEAM_LASER: 15000, WEAPON_MINING_LASER: 12500, WEAPON_THARGOID_LASER: 17500, WEAPON_MILITARY_LASER: 30000, WEAPON_NONE: 32000.<br><br />
(Turrets are secondary weapons with a maximum range of 6000)<br />
<br />
=== <code>withinStationAegis</code> ===<br />
'''withinStationAegis''' : Boolean (read-only)<br />
<code>true</code> if the ship is within the aegis of the system’s main station (i.e., no more than 51 200 game metres from the station, or twice scanner range).<br />
<br />
=== <code>yaw</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''yaw''' : Number (read-only)<br />
The rate of yaw of the ship in radians/second (positive for right, negative for left)<br />
<br />
== Methods ==<br />
=== <code>abandonShip</code> ===<br />
function '''abandonShip'''() : Boolean<br />
Returns <code>true</code> when the ship has an escapepod. It will launch all escapeposd on board leaving the ship behind as a empty hulk. (scanClass = CLASS_CARGO). This command does nothing when no escape-pod is present.<br><br />
Pressence of an escapepod can be tested with: <code>equipmentStatus("EQ_ESCAPE_POD") == "EQUIPMENT_OK"</code><br />
<br />
=== <code>addCollisionException</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''addCollisionException'''(exception : Ship)<br />
Prevented this ship and the selected ship from colliding. See [[#collisionExceptions|collisionExceptions]] and [[#removeCollisionException|removeCollisionException]].<br />
<br />
Prevention from collision will specifically prevent the following:<br />
<br />
* the ships colliding with each other and suffering collision damage and/or momentum change<br />
* the ships receiving collision warning events if they come close to each other<br />
* if one of the ships is a station, the other ship will not be able to dock with it even if it enters a dock<br />
<br />
This has no useful effect when applied to a subentity.<br />
<br />
Adding a collision exception which already exists has no effect but will not cause an error.<br />
<br />
=== <code>addDefenseTarget</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''addDefenseTarget'''(target : Ship)<br />
Adds the target ship to this ship's list of point [[#defenseTargets|defense targets]], if it isn't already.<br />
<br />
=== <code>awardEquipment</code> ===<br />
function '''awardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Adds the given piece of equipment to the ship, if possible, returning <code>true</code> if successful and <code>false</code> otherwise.<br />
<br />
Example:<br />
ship.awardEquipment("EQ_ECM");<br />
<br />
'''See also:''' <code>[[#canAwardEquipment|canAwardEquipment()]]</code>, <code>[[#removeEquipment|removeEquipment()]]</code><br />
<br />
=== <code>canAwardEquipment</code> ===<br />
function '''canAwardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Tests whether it is possible to add a given equipment type. This command takes the conditions for offering inside equipment.plist into account. Returns <code>true</code> if <code>[[#awardEquipment|awardEquipment()]]</code> is expected to succeed, <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#awardEquipment|awardEquipment()]]</code><br />
<br />
=== <code>becomeCascadeExplosion</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''becomeCascadeExplosion'''()<br />
This method causes the ship to explode as if it were hit by a quirium cascade.<br />
<br />
=== <code>broadcastCascadeImminent</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''broadcastCascadeImminent'''()<br />
This method causes the ship to broadcast a message to the AIs of all nearby ships warning them of an imminent cascade explosion. It is polite to call this a few seconds before calling <code>becomeCascadeExplosion</code><br />
<br />
=== <code>broadcastDistressMessage</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''broadcastDistressMessage'''()<br />
This method causes the ship to broadcast a distress message to the AIs of all nearby ships (received also by the player as a comms message). Ships receiving a distress message will often intervene in the fight, depending on their own AI and the roles of the ships already involved.<br />
<br />
=== <code>checkCourseToDestination</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''checkCourseToDestination'''()<br />
Checks the line between the ship's current position and its destination, and returns either null or an Entity (usually a planet, sun or other ship) that this ship would risk collision with if it travelled along that course.<br />
<br />
'''See also''': [[#getSafeCourseToDestination|getSafeCourseToDestination()]]<br />
<br />
=== <code>checkScanner</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''checkScanner'''([poweredOnly : Boolean]) : Array<br />
Runs a fast scanner check and returns the results. At most 32 objects within scanner range will be returned. If the <code>poweredOnly</code> parameter is present and set to true, then only powered objects will be returned (i.e. ships with a scan class other than CLASS_CARGO or CLASS_ROCK).<br />
<br />
This method is usually considerably quicker than [[Oolite_JavaScript_Reference:_System#filteredEntities|system.filteredEntities()]] and similar methods, with little loss of accuracy, though it is still advisable to cache the result for a while before re-scanning.<br />
<br />
=== <code>clearDefenseTargets</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''clearDefenseTargets'''()<br />
Clears the ship's list of point [[#defenseTargets|defense targets]].<br />
<br />
=== <code>commsMessage</code> ===<br />
function '''commsMessage'''(message : String [,target : Ship])<br />
Make the ship broadcast the specified message. Works on buoys and subentities as well as normal ships and stations. Messages are send to a maximum of 16 ships in range and always to the player when in range. When the optional target is used, the message goes only to that ship.<br />
<br />
=== <code>damageAssessment</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''damageAssessment'''() : Number<br />
Returns a number indicating the amount of damage or supply usage by this ship. Zero means that the ship is in excellent fighting condition, while higher numbers indicate increasing amounts of damage or supply shortages.<br />
<br />
=== <code>dealEnergyDamage</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''dealEnergyDamage'''(damage : Number, idealRange : Number [, velocityBias : Number])<br />
Deals damage to all ships within a sphere centred on this ship. If this ship has an owner (e.g. it is a missile or a subentity) the damage will be credited to its owner. Damage is dealt according to the following formula:<br />
* Further away than MAX_SCANNER_RANGE (25.6km): deal no damage<br />
* At or closer than <code>idealRange</code>: deal <code>damage</code> plus (or minus, for receding objects) <code>velocityBias</code> damage for every 0.001LM of relative closing speed, up to a maximum of 1.0LM<br />
* Between <code>idealRange</code> and a derived maximum range: calculate the damage that would have been done at <code>idealRange</code>, and then divide it by the square of the ratio of <code>idealRange</code> and the real range (i.e inverse-square). The derived maximum range is the distance where a target with no relative closing speed would take 1 point of damage.<br />
<br />
As an example, the standard Oolite missile uses <code>dealEnergyDamage(170, 32.5, 0.25)</code>, has a maximum speed of 0.75LM, and its AI tries to detonate it 25m from its target. Some worked examples (for comparision, one energy bank can absorb 64 points of damage, and a standard shield generator can absorb 128 points of damage):<br />
* The missile is fired at a stationary asteroid. It detonates at 25m, within the ideal range, and the relative closing speed is 0.75LM. The asteroid takes 170 + (0.25 * 750) = 357.5 points of damage<br />
* The missile is fired at a Cobra Mk III, which tries to flee from and evade the missile at its top speed of 0.35LM. The missile detonates at 25m, and the evasive manoeuvres mean that it is not heading directly at the Cobra when it detonates. The relative closing speed is 0.38LM. The Cobra takes 170 + (0.25 * 380) = 265 points of damage.<br />
* An Anaconda freighter travelling at 0.2LM fires a missile at a distant Fer-de-lance. After the missile has travelled 150m away from the Anaconda, it is hit by an ECM pulse from the FDL, and detonates. The relative velocity is -0.55LM (the missile is travelling away from the Anaconda), so the damage at the ideal range would be 170 - (0.25 * 550) = 32.5. The damage is then divided by (150 / 32.5)<sup>2</sup>, so the Anaconda takes about 1.5 points of damage.<br />
* A missile fired at something else detonates 500m away from a Sidewinder. The inverse-square rule divides the damage by (500 / 32.5)<sup>2</sup>, so the base damage at this range (ignoring velocityBias) is only 0.7. The Sidewinder is therefore safely outside the blast radius, and is not considered for damage. <br />
<br />
=== <code>deployEscorts</code> ===<br />
function '''deployEscorts'''()<br />
Cause a random number (at least 1 if possible) of the ship's escorts which are not already attacking a target to attack this ship's primary target, unless this function has already been called for the current target without meanwhile being called for a different target.<br />
<br />
=== <code>dockEscorts</code> ===<br />
function '''dockEscorts'''()<br />
Dock the ship’s deployed escorts, if any.<br />
<br />
=== <code>dumpCargo</code> ===<br />
function '''dumpCargo'''([amount : Number, commodity: String]) : Ship<br />
Ejects one item of cargo from the ship, and returns the cargo item. Returns <code>null</code> if the ship has no cargo, anything has been ejected in the last 0.5 seconds, or if sent to the player while docked.<br />
<br />
In 1.79 or later, multiple items may be scheduled for dumping by passing the number as a parameter.<br />
<br />
In 1.81 or later, a preferred commodity may be specified (if this is not present, a random item will be dumped as usual). This preference only applies to the first item dropped, not subsequent ones.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code><br />
<br />
=== <code>ejectItem</code> ===<br />
function '''ejectItem'''(role : String) : Ship<br />
Spawns a ship of role <code>role</code> immediately behind the ship, with a slight backwards velocity. (Note: an equal and opposite reaction is applied to the parent ship, so doing this with large ships is rarely useful. <code>player.ejectItem("station")</code> may seem funny, but don’t come running to me if you have someone’s eye out.) Returns the generated ship, or <code>null</code> if no ship is generated. The scanClass of the ejected item will always be CLASS_CARGO.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code><br />
<br />
=== <code>ejectSpecificItem</code> ===<br />
function '''ejectSpecificItem'''(itemKey : String) : Ship<br />
Spawns a ship with the ''shipdata.plist'' key <code>itemKey</code> immediately behind the ship, with a slight backwards velocity. The scanClass of the ejected item will always be CLASS_CARGO.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectItem|ejectItem]]</code><br />
<br />
=== <code>enterWormhole</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''enterWormhole'''([wormhole : Wormhole])<br />
If the player has entered witchspace, but before the old system is removed from memory, this method may be used to add this ship to the contents of the specified outbound wormhole. If no parameter is given, add them to the player's wormhole.<br />
<br />
If the player is not entering witchspace, this method does nothing: the ship must fly to the wormhole in the normal way to enter it.<br />
<br />
=== <code>equipmentStatus</code> ===<br />
function '''equipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : String<br />
Tests whether the specified type of equipment is installed, and whether it is functioning. Returns one of the following strings: <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>, <code>"EQUIPMENT_UNAVAILABLE"</code> or <code>"EQUIPMENT_UNKNOWN"</code>.<br />
<br />
'''See also:''' <code>[[#setEquipmentStatus|setEquipmentStatus()]]</code><br />
<br />
=== <code>exitAI</code> ===<br />
function '''exitAI'''()<br />
Exit the current AI, restoring the previous one. Equivalent to the <code>[[AI_methods|exitAI]]:</code> AI method. May not be used on player. Will generate a warning if there are no suspended AI states.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code><br />
<br />
=== <code>exitSystem</code> ===<br />
function '''exitSystem'''([targetSystem : Number]) : Boolean<br />
Cause the ship to jump out of the system, if possible. If <code>targetSystem</code> is specified, it will attempt to jump to the specified system, otherwise a random system within range is chosen.<br />
<br />
This method can fail for various reasons, in which case it returns <code>false</code>. It always fails for the player ship.<br />
<br />
=== <code>explode</code> ===<br />
function '''explode'''()<br />
Causes the ship to explode. Works on all ships, including the main station and the player except when docked.<br />
<br />
'''See also:''' <code>[[#remove|remove()]]</code><br />
<br />
=== <code>fireECM</code> ===<br />
function '''fireECM'''()<br />
activates an ecm burst, identical as the AI command.<br />
<br />
=== <code>findNearestStation</code> ===<br />
function '''findNearestStation'''()<br />
Returns the nearest Station entity to this ship. This is quicker than manually searching <code>system.stations</code> and much quicker than using <code>system.filteredEntities()</code>.<br />
<br />
=== <code>fireMissile</code> ===<br />
function '''fireMissile'''([missile]) : Ship<br />
fireMissile() will try to fire the first available missile and will return the missile fired, or <code>null</code> if no missiles can be fired at this time. It can take the optional missile identifier parameter, to allow for a specific missile to be fired. Missiles cannot be fired if the ship hasn’t got a valid target, or if the previous missile was launched less than <code>missile_load_time</code> seconds before. If a missile type was specified, and not found on the ship, no missile will be fired.<br />
<br />
=== <code>getSafeCourseToDestination</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''getSafeCourseToDestination'''()<br />
Returns some coordinates which can be flown to as an intermediate destination to allow travel between the ship's current position and its destination without colliding with any objects on the way. Use this if <code>checkCourseToDestination</code> returns an object you are unable or unwilling to destroy to calculate a new route.<br />
<br />
'''See also''': [[#checkCourseToDestination|checkCourseToDestination()]]<br />
<br />
=== <code>getMaterials</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''getMaterials'''() : Object<br />
getMaterials() returns the ship's current materials dictionary, or if none present an empty dictionary.<br />
<br />
'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code><br />
<br />
=== <code>getShaders</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''getShaders'''() : Object<br />
getShaders() returns the ship's current shaders dictionary, or if none present an empty dictionary.<br />
<br />
'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code><br />
<br />
=== <code>hasEquipmentProviding</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''hasEquipmentProviding'''(key : String)<br />
This method returns <code>true</code> if the ship has any equipment providing the <code>key</code> equipment type, and <code>false</code> otherwise.<br />
<br />
=== <code>hasRole</code> ===<br />
function '''hasRole'''(role : String)<br />
Returns <code>true</code> if the ship has <code>role</code> among its roles, <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#roles|roles]]</code><br />
<br />
=== <code>markTargetForFines</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''markTargetForFines()'''<br />
If this ship is eligible to give out fines and the primary target has a bounty, mark the current primary target for fines, which will need to be paid when the ship docks. If used on a ship other than the player, of course, the fines are not particularly meaningful.<br />
<br />
=== <code>notifyGroupOfWormhole</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''notifyGroupOfWormhole()'''<br />
Tells the ship's group about a wormhole (usually the one this ship has just entered). Causes a <code>wormholeSuggested</code> event to occur in the scripts of other group members.<br />
<br />
=== <code>offerToEscort</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''offerToEscort(mother : Ship)'''<br />
Offer to escort the specified ship. The ship making the offer must have the same scan class as the mothership and must have one of the designated escort roles. After the mothership has made a decision this ship will receive either an <code>escortAccepted</code> or <code>escortRejected</code> ship script event.<br />
<br />
=== <code>perform*</code> ===<br />
Each of these functions switches the frame-by-frame behaviour of the ship to a different mode. It may not necessarily remain in that mode, however - for example, those modes which require a target will usually fall back to idle mode if the target is lost.<br />
<br />
==== <code>performAttack</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performAttack()'''<br />
Attack the current target with available weapons.<br />
<br />
==== <code>performCollect</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performCollect()'''<br />
Attempt to scoop up the current target. If the current target is not scoopable, it will be lost.<br />
<br />
==== <code>performEscort</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performEscort()'''<br />
Escort the group leader. If this ship is not an escort of the group leader, it will not receive escort position updates from that ship.<br />
<br />
==== <code>performFaceDestination</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFaceDestination()'''<br />
Come to a stop, and turn to face the current destination coordinates.<br />
<br />
==== <code>performFlee</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFlee()'''<br />
Flee from the current target, using injectors if possible, until it is out of scanner range.<br />
<br />
==== <code>performFlyToRangeFromDestination</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFlyToRangeFromDestination()'''<br />
Fly to the current [[#destination|destination]] coordinates, stopping when the distance between the ship and those coordinates is the [[#desiredRange|desiredRange]]. If the ship is already closer to the destination coordinates than the desired range, it will move away from the coordinates.<br />
<br />
==== <code>performHold</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performHold()'''<br />
Come to a stop, and continually turn to face the current target<br />
<br />
==== <code>performIdle</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performIdle()'''<br />
Cancel any current turns to return to level flight, then move forward at current speed.<br />
<br />
==== <code>performIntercept</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performIntercept()'''<br />
Fly to intercept (i.e. ram) the current target.<br />
<br />
==== <code>performLandOnPlanet</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performLandOnPlanet()'''<br />
Land on rather than crash into the planet. This is a slow flight, so it is recommended to get close to the planet surface before activating this behaviour.<br />
<br />
==== <code>performMining</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performMining()'''<br />
Attack the current target with a mining laser. This does not count as hostile behaviour, so cannot be used except on rocks.<br />
<br />
==== <code>performScriptedAI</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performScriptedAI()'''<br />
Request flight instructions from a [[OXP_Scripted_AI|scripted AI]] callback each frame.<br />
<br />
==== <code>performScriptedAttackAI</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performScriptedAttackAI()'''<br />
Request flight instructions, including weapons fire, from a [[OXP_Scripted_AI|scripted AI]] callback each frame.<br />
<br />
==== <code>performStop</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performStop()'''<br />
Come to a complete halt<br />
<br />
==== <code>performTumble</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performTumble()'''<br />
Come to a complete halt and rotate randomly.<br />
<br />
=== <code>reactToAIMessage</code> ===<br />
function '''reactToAIMessage'''(message : String)<br />
Immediately perform the specified handler in the ship’s current AI state.<br />
<br />
'''See also:''' <code>[[#sendAIMessage|sendAIMessage()]]</code><br />
<br />
=== <code>recallDockingInstructions</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''recallDockingInstructions'''() : Object<br />
Returns the current docking instructions as an object, and sets the destination, desired range and desired speed to match the instructions. Use this if the ship may have been interrupted while docking to ensure its flight parameters are set correctly.<br />
<br />
'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#requestDockingInstructions|requestDockingInstructions]]</code><br />
<br />
=== <code>remove</code> ===<br />
function '''remove'''([suppressDeathEvent : Boolean])<br />
Immediately removes the ship from the universe. Works on all ships except the player, including the main station.<br>It generates a [[Oolite JavaScript Reference: ship script event handlers#shipRemoved|this.shipRemoved(suppressDeathEvent)]] event. By default it will also trigger a [[Oolite JavaScript Reference: ship script event handlers#shipDied|this.shipDied()]] event, unless <code>suppressDeathEvent</code> is true.<br />
<br />
'''See also:''' <code>[[#explode|explode()]]</code><br />
<br />
=== <code>removeCollisionException</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''removeCollisionException'''(exception : Ship)<br />
Allow this ship and the selected ship to collide again. See [[#collisionExceptions|collisionExceptions]] and [[#addCollisionException|addCollisionException]].<br />
<br />
Removing a collision exception which does not exist has no effect but will not cause an error.<br />
<br />
=== <code>removeDefenseTarget</code>===<br />
{{oolite-method-added|1.79}}<br />
function '''removeDefenseTarget'''(target : Ship)<br />
Ensures that the target ship is not on this ship's list of point [[#defenseTargets|defense targets]].<br />
<br />
=== <code>removeEquipment</code> ===<br />
function '''removeEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]])<br />
Removes the given piece of equipment from the ship.<br />
This function can also be used to remove missiles (and mines). If more than one missile of the same type is found on board, only one of them will be removed.<br />
<br />
Note that in Oolite prior to 1.76.1 there was a bug which could sometimes cause the game to crash if this function was used on pylon-mounted equipment. Therefore, if you do this in your OXP, you should set (at least) 1.76.1 as the version in requires.plist<br />
<br />
Example:<br />
ship.removeEquipment("EQ_ECM");<br />
<br />
=== <code>requestDockingInstructions</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''requestDockingInstructions'''() : Object<br />
Requests the next docking instructions from the station, and returns them as an object, setting the destination, desired range and desired speed to match the instructions. Use this to get the next step in the docking sequence after completing the previous one.<br />
<br />
'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code><br />
<br />
<br />
=== <code>requestHelpFromGroup</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''requestHelpFromGroup'''()<br />
This function sends the <code>helpRequestReceived</code> event to the other ships in this ship's group and escort group, sending the name of this ship's current target as the aggressor.<br />
<br />
=== <code>restoreSubEntities</code> ===<br />
function '''restoreSubEntities'''() : Boolean<br />
Recreate all destroyed or removed subentities of the ship. Returns <code>true</code> if any subentities were added. Whether or not any subentities were added, this will also reset all subentities to their original configuration of position, orientation and other properties.<br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#isFrangible|isFrangible]]</code><br />
<br />
=== <code>selectNewMissile</code> ===<br />
function '''selectNewMissile'''() : equipmentKey<br />
selectNewMissile() will automatically select a missile for a specific ship. It uses the missile_role shipdata.plist key to find out which missiles to select. As with the system populator, there's a small chance that missiles other than the missile_role specified in shipdata will be selected.<br />
e.g.<br />
this.ship.awardEquipment(this.ship.selectNewMissile())<br />
will automatically add the 'right type' of missile to a ship, i.e. one that its captain would normally choose.<br />
<br />
=== <code>sendAIMessage</code> ===<br />
function '''sendAIMessage'''(message : String)<br />
Add a message to the ship’s AI deferred message queue. Messages in the queue are handled immediately after the next periodic <code>UPDATE</code> message. Identical messages are coalesced.<br />
<br />
'''See also:''' <code>[[#reactToAIMessage|reactToAIMessage()]]</code><br />
<br />
=== <code>setAI</code> ===<br />
function '''setAI'''(AIName : String)<br />
Set the current AI, leaving the old one suspended. Equivalent to the <code>[[AI_methods|setAITo]]:</code> AI method. May not be used on player. From 1.79 onwards AI files may either be plist-based (with a .plist extension) or Javascript-based (with a .js extension).<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code><br />
<br />
=== <code>setBounty</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''setBounty'''(bounty : Number, reason : String)<br />
Sets the ship's bounty to the new value. <code>reason</code> will be sent to [[Oolite_JavaScript_Reference:_ship_script_event_handlers#shipBountyChanged|shipBountyChanged()]].<br />
<br />
'''See also:''' <code>[[#bounty|bounty]]</code><br />
<br />
=== <code>setCargo</code> ===<br />
function '''setCargo'''(commodity : String [, count : Number]) : Boolean<br />
Attempts to create <code>count</code> weight units of the commodity <code>commodity</code> for a cargo barrel. (Can not be used to set cargo for ships) When more units are defined than 1 ton, the count is reduced to one ton. It returns false when the selected commodity is unknown. If <code>count</code> is not specified, one will be assumed.<br />
<br />
=== <code>setCargoType</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setCargoType'''(commodityType : String) : Boolean<br />
Attempts to set the ship's cargo hold to contain cargo of the specified type, discarding any cargo already present. This should generally only be used immediately after a ship is spawned. Valid cargo types are:<br />
* '''SCARCE_GOODS''': goods which are likely to be rare in the current system, usually legal.<br />
* '''PLENTIFUL_GOODS''': goods which are likely to be plentiful in the current system, usually legal.<br />
* '''MEDICAL_GOODS''': narcotics (used for the Moray Medical Boat)<br />
* '''ILLEGAL_GOODS''': various goods likely to be rare in the current system, with a strong bias towards contraband<br />
* '''PIRATE_GOODS''': as ILLEGAL_GOODS, but the total amount carried will be lower<br />
This will return false if an unrecognised commodity type is used, and will throw an exception if used on a cargo pod rather than a cargo carrier. Using it on a ship like an Asp without a cargo hold is valid but pointless.<br />
<br />
=== <code>setCrew</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setCrew'''(Object) : Boolean<br />
Sets the ship's crew to one represented by the given object (or sets the ship to uncrewed if null is given as a parameter). Returns true if this succeeds, false otherwise (if the ship is ''always'' unpiloted). The object has the same keys as [[characters.plist]], all of which are optional and will be replaced with default values if unset. They are applied in the following order:<br />
* origin system<br />
* random seed<br />
* role<br />
* the rest<br />
You can therefore set a random seed or role to get particular behaviour, and use the other keys to override it.<br />
<br />
At the moment this function only sets the first crew member (the pilot of the ship)<br />
<br />
=== <code>setEquipmentStatus</code> ===<br />
function '''setEquipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]], statusKey : String)<br />
Changes the status of the given piece of equipment from the ship. The two only valid status keys are <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>.<br />
<br />
'''Note:''' by design, this method will throw an exception if called with an equipment type that does not exist. To test whether an equipment type exists, use <code>[[Oolite JavaScript Reference: EquipmentInfo#infoForKey|EquipmentInfo.infoForKey()]]</code>, which will return <code>null</code> for undefined equipment.<br />
<br />
'''See also:''' <code>[[#equipmentStatus|equipmentStatus()]]</code><br />
<br />
=== <code>setMaterials</code> ===<br />
function '''setMaterials'''(materialDictionary : Object [, shaderDictionary : Object]) : Boolean<br />
Set the materials of the ship’s model. This works exactly like the <code>materials</code> dictionary in [[shipdata.plist]]. The optional <code>shaderDictionary</code> argument overrides <code>materialDictionary</code> if shaders are active.<br />
<br />
'''Example:'''<br />
this.ship.setMaterials({"my_ship_diffuse.png": { diffuse_map: "my_ship_damaged_diffuse.png" }});<br />
<br />
'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code><br />
<br />
=== <code>setScript</code> ===<br />
function '''setScript'''(scriptName : String)<br />
Set, or completely replace, the javascript code associated to a ship entity.<br />
<br />
=== <code>setShaders</code> ===<br />
function '''setShaders'''(shaderDictionary : Object) : Boolean<br />
Set the shader materials of the ship’s model. Equivalent to <code>[[#setMaterials|setMaterials()]]</code> with the <code>materialDictionary</code> value set to the ship’s current material dictionary.<br />
<br />
'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code><br />
<br />
=== <code>spawn</code> ===<br />
function '''spawn'''(role : String [, count : Number]) : Array<br />
Attempts to create <code>count</code> (maximum: 64) ships of role <code>role</code> close to the ship – specifically, inside the ship’s collision radius. (Since creating ships may fail, the number created may be less than <code>count</code>). The created ships are returned in an array. If <code>count</code> is not specified, one will be assumed.<br />
<br />
<code>spawn()</code> is intended for cases when a ship splits into multiple parts or drops parts. In particular, it has the following special behaviour:<br />
* The spawned ships inherit most of the temperature of the parent.<br />
* If the parent is a missile and a child has the <code>[[shipdata.plist#is_submunition|is_submunition]]</code> property, the child will be considered a missile, its target will be set to that of the parent and the child’s owner will be set to the parent.<br />
* <code>spawn()</code> does not set up escorts for the new ships, or generate witchspace effects, or do any special AI handling.<br />
<br />
=== <code>spawnOne</code> ===<br />
function '''spawnOne'''(role : String) : Ship<br />
Convenience method which calls <code>[[#spawn|spawn]](role)</code> and returns the first element of the resulting array, or <code>null</code> if <code>spawn()</code> fails.<br />
<br />
=== <code>switchAI</code> ===<br />
function '''switchAI'''(AIName : String)<br />
Set the current AI, exiting the old one. Equivalent to the <code>[[AI_methods|switchAITo]]:</code> AI method. May not be used on player.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#exitAI|exitAI()]]</code><br />
<br />
=== <code>threatAssessment</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''threatAssessment'''(full : Boolean) : Number<br />
Returns a number indicating the relative strength of the ship. If the 'full' parameter is true, additional information will be considered as part of the assessment which would generally only be known by ships which know this ship or have seen it in combat. Otherwise, only data which could reasonably be expected to be common knowledge based on the class of the ship will be included.<br />
<br />
For example, which weapon facings are available is part of the basic assessment, but what forward laser the ship has is part of the full assessment.<br />
<br />
=== <code>throwSpark</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''throwSpark'''()<br />
Sets the ship to throw a spark as if it was seriously damaged. If this ship is already scheduled to throw a spark, this does nothing.<br />
<br />
=== <code>updateEscortFormation</code> ===<br />
function '''updateEscortFormation'''()<br />
Request that the game updates the target positions for the ship’s escorts by calling the ship’s script’s <code>coordinatesForEscortPosition()</code> method.<br />
<br />
== Static Methods ==<br />
=== <code>keys</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''keys'''() : Array<br />
Returns all dataKeys of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.<br />
var dataKeysArray = Ship.keys();<br />
<br />
=== <code>keysForRole</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''keysForRole'''(role : String) : Array<br />
Returns all dataKeys of ships defined in all [[shipdata.plist]] which contains the given role.<br />
<br />
var role = "trader";<br />
var roleKeys = Ship.keysForRole( role );<br />
log("keysForRole", role + ": " + roleKeys );<br />
<br />
=== <code>roleIsInCategory</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''roles'''(role : String, category : String) : Boolean<br />
Returns whether the role given is in a particular category as defined in [[role-categories.plist]]<br />
<br />
Ship.roleIsInCategory("trader","oolite-pirate-victims"); // true<br />
<br />
=== <code>roles</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''roles'''() : Array<br />
Returns all roles of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.<br />
<br />
var roles = Ship.roles();<br />
for( var i = 0; i < roles.length; i++ ) {<br />
var roleKeys = Ship.keysForRole( roles[i] );<br />
log("roles", i + ". "+roles[i] + ": " + roleKeys );<br />
}<br />
<br />
=== <code>shipDataForKey</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''shipDataForKey'''(datakey : String) : Object<br />
Returns an object containing a representation of the raw [[shipdata.plist]] entry for a given data key, or null if the data key does not exist. Keys not defined in the shipdata.plist entry will not be defined in the object - they won't get their default values.<br />
<br />
Using the ship object properties is generally a better way to get this information, but this is useful if you want to find out what a ship might be like if you did add it.<br />
<br />
var shipdata = Ship.shipDataForKey("cobra3-trader");<br />
log("test",shipdata["name"]); // "Cobra Mark III"<br />
log("test",shipdata["ship_class_name"]); // undefined<br />
log("test",shipdata["ship_unique_name"]); // undefined<br />
log("test",shipdata["display_name"]); // undefined<br />
<br />
==See also==<br />
*[[Shipdata.plist]]<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_World_script_event_handlers&diff=46990Oolite JavaScript Reference: World script event handlers2015-03-10T20:30:13Z<p>Cim: /* playerBoughtNewShip */ 1.81 extra parameter</p>
<hr />
<div>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.<br />
<br />
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. <br />
<br />
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.<br />
<br />
World scripts are always active.<br />
<br />
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 '$').<br />
<br />
=== Game State ===<br />
<br />
==== <code>gamePaused</code> ====<br />
{{oolite-method-added|1.81}}<br />
<br />
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.<br />
<br />
this.gamePaused = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>gameResumed</code> ====<br />
{{oolite-method-added|1.81}}<br />
<br />
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.<br />
<br />
this.gameResumed = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerWillSaveGame</code> ====<br />
<br />
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'<br />
<br />
this.playerWillSaveGame = function(message : String)<br />
{<br />
// Your code here<br />
}<br />
<br />
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.<br />
<br />
==== <code>startUp</code> ====<br />
<br />
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)<br />
<br />
this.startUp = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
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.<br />
<br />
==== <code>startUpComplete</code> ====<br />
{{oolite-method-added|1.79}}<br />
<br />
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:<br />
* <code>startUp</code><br />
* <code>systemWillPopulate</code> (or an alternative handler specified by the system info)<br />
* <code>startUpComplete</code><br />
<br />
=== Docking ===<br />
<br />
==== <code>shipWillDockWithStation</code> ====<br />
<br />
The <code>shipWillDockWithStation</code> handler is called at the beginning of the docking tunnel effect.<br />
<br />
this.shipWillDockWithStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
At this moment "ship.dockedStation == null", "ship.docked == true", "ship.status == STATUS_DOCKING"<br />
<br />
<br />
==== <code>shipDockedWithStation</code> ====<br />
<br />
The <code>shipDockedWithStation</code> handler is called at the end of the docking tunnel effect.<br />
<br />
this.shipDockedWithStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
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.<br />
<br />
==== <code>shipWillLaunchFromStation</code> ====<br />
<br />
The <code>shipWillLaunchFromStation</code> handler is called at the beginning of the launch tunnel effect.<br />
<br />
this.shipWillLaunchFromStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
At this moment "ship.dockedStation == the station", "ship.docked == false", "ship.status == STATUS_LAUNCHING".<br />
<br />
==== <code>shipLaunchedFromStation</code> ====<br />
<br />
The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect.<br />
<br />
this.shipLaunchedFromStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
At this moment "ship.dockedStation == null", "ship.docked == false", "ship.status == STATUS_IN_FLIGHT".<br />
<br />
==== <code>playerStartedAutoPilot</code> ====<br />
<br />
The <code>playerStartedAutoPilot</code> handler is called when the player starts autopilot docking. It is not called for the instantaneous dock command.<br />
<br />
this.playerStartedAutoPilot = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>playerCancelledAutoPilot</code> ====<br />
<br />
The <code>playerCancelledAutoPilot</code> handler is called when the player cancels autopilot docking.<br />
<br />
this.playerCancelledAutoPilot = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>playerDockingRefused</code> ====<br />
<br />
The <code>playerDockingRefused</code> handler is called when a station refuses to provide autopilot docking instructions.<br />
<br />
this.playerDockingRefused = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>playerRequestedDockingClearance</code> ====<br />
<br />
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).<br />
<br />
this.playerRequestedDockingClearance = function(message)<br />
{<br />
// Your code here<br />
}<br />
<br />
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".<br />
<br />
==== <code>playerRescuedEscapePod</code> ====<br />
{{oolite-method-added|1.81}}<br />
<br />
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:<br />
# the rescue fee, in decicredits<br />
# the fee reason, which can be "insurance", "bounty" or "slave" (in the latter case, the fee will always be zero)<br />
# a dictionary like those in the <code>ship.crew</code> property describing the pod occupant<br />
<br />
this.playerRescuedEscapePod = function(fee, reason, occupant)<br />
{<br />
// Your code here<br />
}<br />
<br />
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.<br />
<br />
==== <code>playerCompletedContract</code> ====<br />
{{oolite-method-added|1.81}}<br />
<br />
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:<br />
# The type of contract, which can be "cargo", "parcel" or "passenger"<br />
# The result of the contract, which can be "success", "late", "failed", or for cargo contracts only "short"<br />
# The fee paid for the contract in decicredits<br />
# The contract information dictionary<br />
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.<br />
<br />
this.playerCompletedContract = function(type, result, fee, contract)<br />
{<br />
// Your code here<br />
}<br />
<br />
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.<br />
<br />
==== <code>playerEnteredContract</code> ====<br />
{{oolite-method-added|1.81}}<br />
<br />
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:<br />
# The type of contract, which can be "cargo", "parcel" or "passenger"<br />
# The contract information dictionary<br />
<br />
this.playerEnteredContract = function(type, contract)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Witchspace Jumps ===<br />
<br />
==== <code>playerStartedJumpCountdown</code> ====<br />
<br />
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.<br />
<br />
this.playerStartedJumpCountdown = function(type, seconds)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerCancelledJumpCountdown</code> ====<br />
<br />
The <code>playerCancelledJumpCountdown</code> handler is called when the user cancels a witchspace or galactic witchspace jump countdown.<br />
<br />
this.playerCancelledJumpCountdown = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>playerJumpFailed</code> ====<br />
<br />
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:<br />
* '''"insufficient fuel"''' - the ship no longer has enough fuel to make the jump (e.g. injector use or fuel leak).<br />
* '''"blocked"''' - a heavy ship is near the player (specifically <code>object mass</code> / <code>object distance</code><sup>2</sup> >= 10.0, and <code>object distance</code> <= scanner range).<br />
* '''"malfunction"''' - the jump malfunctioned in a way that leaves the player ship in the current system.<br />
* '''"malfunction"''' - the Galactic Hyperdrive is damaged or removed during a galactic jump countdown.<br />
<br />
Also theoretically possible but unlikely in current Oolite:<br />
* '''"too far"''' - the jump destination is outside the 7LY range (but wasn't when the countdown started).<br />
* '''"no target"''' - the jump destination is the current location (but wasn't when the countdown started).<br />
<br />
this.playerJumpFailed = function(reason)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipWillEnterWitchspace</code> ====<br />
<br />
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.<br />
<br />
// 1.80 or earlier<br />
this.shipWillEnterWitchspace = function(cause)<br />
{<br />
// Your code here<br />
}<br />
<br />
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)<br />
<br />
// 1.81 or later<br />
this.shipWillEnterWitchspace = function(cause, destination)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipWillExitWitchspace</code> ====<br />
<br />
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.<br />
<br />
this.shipWillExitWitchspace = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedWitchspace</code> ====<br />
<br />
The <code>shipExitedWitchspace</code> handler is called after a witchspace jump has concluded and the tunnel effect has been shown.<br />
<br />
this.shipExitedWitchspace = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerEnteredNewGalaxy</code> ====<br />
<br />
The <code>playerEnteredNewGalaxy</code> handler is called just before shipWillExitWitchspace.<br />
<br />
the sequence of events for a player jumping to a different galaxy is as follows:<br />
<br />
shipWillEnterWitchspace (world event)<br><br />
playerWillEnterWitchspace (NPC ship event)<br><br />
playerEnteredNewGalaxy (world event)<br><br />
shipWillExitWitchspace (world event)<br><br />
shipExitedWitchspace (world event)<br><br />
<br />
this.playerEnteredNewGalaxy = function(galaxyNumber)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Enter/Exit Aegis ===<br />
<br />
==== <code>shipEnteredStationAegis</code> ====<br />
<br />
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.<br />
<br />
this.shipEnteredStationAegis = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedStationAegis</code> ====<br />
<br />
The <code>shipExitedStationAegis</code> handler is called when the player leaves the aegis of the main-station (2x scanner range from main-station).<br />
<br />
this.shipExitedStationAegis = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipEnteredPlanetaryVicinity</code> ====<br />
<br />
The <code>shipEnteredPlanetaryVicinity</code> handler is called when the player enters the planet aegis (3x planet radius).<br />
<br />
this.shipEnteredPlanetaryVicinity = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedPlanetaryVicinity</code> ====<br />
<br />
The <code>shipExitedPlanetaryVicinity</code> handler is called when the player leaves the planet aegis (3x planet radius).<br />
<br />
this.shipExitedPlanetaryVicinity = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipApproachingPlanetSurface</code> ====<br />
<br />
The <code>shipApproachingPlanetSurface</code> handler is called when the player is very close to the planet (crosses a border ± 500 meter above the surface).<br />
<br />
this.shipApproachingPlanetSurface = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLeavingPlanetSurface</code> ====<br />
<br />
The <code>shipLeavingPlanetSurface</code> handler is called when the player leaves the planet (crosses a border ± 500 meter above the surface).<br />
<br />
this.shipLeavingPlanetSurface = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Combat ===<br />
<br />
==== <code>alertConditionChanged</code> ====<br />
<br />
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)<br />
<br />
this.alertConditionChanged = function(newCondition, oldCondition)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerTargetedMissile</code> ====<br />
<br />
The <code>playerTargetedMissile</code> handler is called when the player targets the nearest missile by pressing T (shift-t) on the keybord.<br />
<br />
this.playerTargetedMissile = function(missile)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAttackedOther</code> ====<br />
<br />
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.<br />
<br />
this.shipAttackedOther = function(other)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAttackedWithMissile</code> ====<br />
<br />
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.<br />
<br />
this.shipAttackedWithMissile = function(missile, whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBeingAttacked</code> ====<br />
<br />
The <code>shipBeingAttacked</code> handler is called when a laser shot hits. <code>whom</code> the identity of the ship that attacked.<br />
<br />
this.shipBeingAttacked = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBeingAttackedByCloaked</code> ====<br />
<br />
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!<br />
<br />
this.shipBeingAttackedByCloaked = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipKilledOther</code> ====<br />
<br />
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. (Handler added in test version 1.75) <br />
<br />
this.shipKilledOther = function(whom,damageType)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetDestroyed</code> ====<br />
<br />
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.<br />
<br />
this.shipTargetDestroyed = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipDied</code> ====<br />
<br />
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.<br />
<br />
this.shipDied = function(whom, why)<br />
{<br />
// Your code here<br />
}<br />
'''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".<br><br />
("cascade weapon" is new in 1.74 and "removed" / "energy damage" were accidentally switched in 1.73)<br />
<br />
<br />
==== <code>shipFiredMissile</code> ====<br />
<br />
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.<br />
<br />
this.shipFiredMissile = function(missile, target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetLost</code> ====<br />
<br />
The <code>shipTargetLost</code> handler is called when the target gets lost. <code>target</code> contains the lost target entity.<br />
<br />
this.shipTargetLost = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetCloaked</code> ====<br />
<br />
The <code>shipTargetCloaked</code> handler is called when the target cloakes.<br />
<br />
this.shipTargetCloaked = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Equipment and Cargo ===<br />
<br />
==== <code>equipmentAdded</code> ====<br />
{{Oolite-method-added|1.81}}<br />
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.<br />
<br />
this.equipmentAdded = function(equipmentKey)<br />
{<br />
// Your code here<br />
}<br />
<br />
This is often more convenient than monitoring both <code>equipmentRepaired</code> and <code>playerBoughtEquipment</code>, and will also detect equipment addition by script.<br />
<br />
==== <code>equipmentDamaged</code> ====<br />
<br />
The <code>equipmentDamaged</code> handler is called when equipment gets damaged. (world script only)<br />
<br />
this.equipmentDamaged = function(equipment)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>equipmentRemoved</code> ====<br />
{{Oolite-method-added|1.81}}<br />
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.<br />
<br />
this.equipmentRemoved = function(equipmentKey)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>equipmentRepaired</code> ====<br />
{{Oolite-method-added|1.77}}<br />
<br />
The <code>equipmentRepaired</code> handler is called when equipment gets repaired. (world script only)<br />
<br />
this.equipmentRepaired = function(equipment)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerBoughtCargo</code> ====<br />
{{Oolite-method-added|1.77}}<br />
<br />
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.<br />
<br />
this.playerBoughtCargo = function(commodity, units, price)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerBoughtEquipment</code> ====<br />
<br />
The <code>playerBoughtEquipment</code> handler is called when equipment is bought at the outfit screen.<br />
<br />
this.playerBoughtEquipment = function(equipment)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>playerBoughtNewShip</code> ====<br />
<br />
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.<br />
<br />
this.playerBoughtNewShip = function(ship, price)<br />
{<br />
// Your code here<br />
}<br />
<br />
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|player.replaceShip]]<br />
<br />
==== <code>playerSoldCargo</code> ====<br />
{{Oolite-method-added|1.77}}<br />
<br />
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.<br />
<br />
this.playerSoldCargo = function(commodity, units, price)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipScoopedFuel</code> ====<br />
{{Oolite-method-added|1.77}}<br />
<br />
The <code>shipScoopedFuel</code> handler is called whenever the player's ship transfers 0.1LY of fuel from the scoops to the tank.<br />
<br />
this.shipScoopedFuel = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipScoopedOther</code> ====<br />
<br />
The <code>shipScoopedOther</code> handler is called when a ship scoops cargo. The scooped item is transferred as argument.<br>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.<br />
<br />
this.shipScoopedOther = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Other ===<br />
<br />
==== <code>compassTargetChanged</code> ====<br />
<br />
The <code>compassTargetChanged</code> handler is called when a new target is selected. Mode can be any of the following:<br />
<br />
COMPASS_MODE_BASIC<br />
COMPASS_MODE_PLANET<br />
COMPASS_MODE_STATION<br />
COMPASS_MODE_SUN<br />
COMPASS_MODE_TARGET<br />
COMPASS_MODE_BEACONS<br />
<br />
script example <br />
<br />
this.compassTargetChanged = function(whom, mode)<br />
{<br />
log(' Now targeting ' + whom);<br />
// Your code here<br />
}<br />
<br />
==== <code>dayChanged</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
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.<br />
<br />
this.dayChanged = function(newday)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>guiScreenChanged</code> ====<br />
<br />
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)<br><br />
This handler will not fire for every screen the player can switch to, but only when switching to any of the following screens: <br />
<br />
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><br />
<br />
1.77: adds <code>GUI_SCREEN_INTERFACES</code> and removes <code>GUI_SCREEN_CONTRACTS</code><br />
<br />
this.guiScreenChanged = function(to, from)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>guiScreenWillChange</code> ====<br />
<br />
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)<br />
<br />
this.guiScreenWillChange = function(to, from)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>missionChoiceWasReset</code> ====<br />
<br />
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)<br />
<br />
this.missionChoiceWasReset= function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>missionScreenEnded</code> ====<br />
<br />
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)<br />
<br />
this.missionScreenEnded = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>missionScreenOpportunity</code> ====<br />
<br />
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)<br />
<br />
this.missionScreenOpportunity= function()<br />
{<br />
// Your code here<br />
}<br />
<br />
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.<br />
<br />
==== <code>reportScreenEnded</code> ====<br />
<br />
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)<br />
<br />
this.reportScreenEnded = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCollided</code> ====<br />
<br />
The <code>shipCollided</code> handler is send after a collision with otherShip.<br />
<br />
this.shipCollided = function(otherShip)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipSpawned</code> ====<br />
<br />
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.<br><br />
This handler for the woldScript 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.<br />
<br />
this.shipSpawned = function(ship)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLaunchedEscapePod</code> ====<br />
<br />
The <code>shipLaunchedEscapePod</code> handler is called when the player bails out. This will be followed by a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds.<br />
<br />
this.shipLaunchedEscapePod = function(escapepod)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>systemInformationChanged</code> ====<br />
{{oolite-method-added|1.79}}<br />
<br />
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.<br />
<br />
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.<br />
<br />
this.systemInformationChanged = function(galaxy,system,key,newValue)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>viewDirectionChanged</code> ====<br />
<br />
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",<br />
"VIEW_CUSTOM",<br />
"VIEW_GUI_DISPLAY".<br />
<br />
this.viewDirectionChanged = function(viewString)<br />
{<br />
if (viewString == "VIEW_PORT")<br />
{<br />
// Your code here<br />
}<br />
}<br />
<br />
=== System population ===<br />
<br />
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.<br />
<br />
=== Defunct ===<br />
<br />
==== <code>equipmentDestroyed</code> ====<br />
''Handler no longer exists in current stable version 1.80''<br />
<br />
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)<br />
<br />
this.equipmentDestroyed = function(equipment)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>tickle</code> (removed in 1.77) ====<br />
<br />
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.<br />
<br />
=== Missing Events ===<br />
<br />
All the initially planned events have been implemented in 1.74.<br />
<br />
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].<br />
<br />
'''See also:''' [[Oolite JavaScript Reference: ship_script_event_handlers|ship_script_event_handlers]]<br />
<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_SystemInfo&diff=46933Oolite JavaScript Reference: SystemInfo2015-03-07T15:33:29Z<p>Cim: /* Static methods */ setInterstellarProperty</p>
<hr />
<div><small>'''Prototype:''' <code>Object</code></small><br /><br />
<br />
'''<code>SystemInfo</code>''' objects provide information about a specific system. <code>SystemInfo</code>s can be retrieved for any system in the current galaxy, but not systems in other galaxies. If you keep a reference to a <code>SystemInfo</code> object after the player goes to a different galaxy, attempts to read properties of the stored <code>SystemInfo</code> will cause an exception.<br />
<br />
In interstellar space, <code>system.info</code> refers to a temporary <code>SystemInfo</code> object whose properties cannot be written to. Attempting to read properties of such a temporary <code>SystemInfo</code> after leaving interstellar space will raise an exception.<br />
<br />
== Properties ==<br />
=== <code>coordinates</code> ===<br />
'''coordinates''' : {{oojsclass|Vector3D}} (read-only)<br />
The coordinates of the system in light years. e.g. for Lave: <code>(8, 34.6, 0)</code>. The z component is always zero.<br />
<br />
The upper left corner has the coordinate <code>(0, 0, 0)</code>. Going right increases the x value while going down on the map increases the y value.<br />
<br />
'''Example:'''<br />
System.infoForSystem(galaxyNumber, 7).coordinates<br />
returns the coordinates of the system with an ID number of 7 in the current galaxy. In the first galaxy that would be the coordinates for Lave: <code>(8, 34.6, 0)</code>.<br />
<br />
=== <code>galaxyID</code> ===<br />
'''galaxyID''' : Number (read-only nonnegative integer)<br />
The ID number of the galaxy.<br />
<br />
=== <code>internalCoordinates</code> ===<br />
'''internalCoordinates''' : {{oojsclass|Vector3D}} (read-only)<br />
'''Discouraged in favour of <code>[[#coordinates|coordinates]]</code>.'''<br /><br />
The coordinate of the system in the internal coordinate system.<br />
<br />
=== <code>systemID</code> ===<br />
'''systemID''' : Number (read-only nonnegative integer)<br />
The ID number of the system.<br />
<br />
== More properties ==<br />
In addition to the properties above, you can access many other system properties, using the same keys as [[planetinfo.plist]].<br />
<br />
'''Example:'''<br />
<code>system.info.description = "This is a dull planet."</code><br />
sets the description of the current planet to “This is a dull planet.”<br />
<br />
Modified properties are permanent and are stored in saved game. Changes made by scripts override those in ''[[planetinfo.plist]]''. Set a property to <code>null</code> to restore the ''[[planetinfo.plist]]'' value, or the default.<br />
<br />
== Methods ==<br />
=== <code>distanceToSystem</code> ===<br />
function '''distanceToSystem'''(system : SystemInfo) : Number<br />
Returns the distance in light years to another <code>SystemInfo</code>.<br />
<br />
'''Example:'''<br />
System.infoForSystem(galaxyNumber, 7).distanceToSystem(System.infoForSystem(galaxyNumber, 8))<br />
If galaxyNumber is 0, this returns 92.8.<br />
<br />
=== <code>routeToSystem</code> ===<br />
function '''routeToSystem'''(system : SystemInfo [, "OPTIMIZED_BY_JUMPS" | "OPTIMIZED_BY_TIME"] ) : Object<br />
Returns a dictionary containing the route information to another <code>SystemInfo</code>. The dictionary contains the array of system IDs that belong to the <code>route</code> found, the <code>distance</code> and the <code>time</code> corresponding to said route. Takes the optional parameter <code>"OPTIMIZED_BY_JUMPS"</code> (default) or <code>"OPTIMIZED_BY_TIME"</code> to calculate least number of jumps or fastest transit time routes respectively.<br />
<br />
'''Example:'''<br />
var myRoute = System.infoForSystem(galaxyNumber, 7).routeToSystem(System.infoForSystem(galaxyNumber, 8))<br />
myRoute.route<br />
myRoute.distance<br />
myRoute.time<br />
returns:<br />
7,129,227,73,89,222,29,42,131,62,150,36,28,16,185,86,138,51,8 (the route)<br />
96.40 (distance of added jumps)<br />
530.40 (travelled time)<br />
<br />
Warning: in version 1.76 or earlier there is a bug in this method which may cause a crash if either the start or end of the route is in interstellar space (i.e. system ID -1). In later versions this simply returns null.<br />
<br />
=== <code>samplePrice</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''samplePrice'''(commodity : String) : Array<br />
Return a sample main market price in decicredits for the commodity with that key in this system. As this requires reading system information, it will only work for systems in the current galaxy. There is of course no guarantee that the price returned by this function will be anywhere near the actual price when the system is next entered.<br />
<br />
=== <code>setProperty</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''setProperty'''(key : String, value: String, layer: Number [, manifest: String])<br />
<br />
This lets you set properties with more control than provided by writing directly to <code>systemInfo.property</code>. <code>layer</code> is the layer from 0 to 3 that the change should be applied at, as in [[planetinfo.plist]]. Layer 2 is the default layer for Javascript-initiated changes, but 3 may be used for changes absolutely crucial for OXP functionality.<br />
<br />
It is also possible to make changes on behalf of a different OXP by passing the manifest ID of that OXP as the fourth parameter. Otherwise the OXP responsible for the current script execution context will be used.<br />
<br />
=== <code>systemsInRange</code> ===<br />
function '''systemsInRange'''([range : Number]) : Array<br />
Returns an array of <code>SystemInfo</code>s in range (default: 7) from the given system.<br />
<br />
'''Note:''' will not produce correct results if used in interstellar space.<br />
<br />
'''Example:'''<br />
system.info.systemsInRange(5);<br />
<br />
== Static methods ==<br />
=== <code>filteredSystems</code> ===<br />
function '''filteredSystems'''(this : Object, predicate : Function) : Array of SystemInfo<br />
A list of the <code>SystemInfo</code>s for which <code>predicate</code> returns <code>true</code>.<br />
<br />
'''Example:'''<br />
// This is the actual implementation of <code>[[#systemsInRange|systemsInRange()]]</code>.<br />
SystemInfo.prototype.systemsInRange = function systemsInRange(range) <br />
{ <br />
if (range === undefined) <br />
{ <br />
range = 7; <br />
} <br />
<br />
return SystemInfo.filteredSystems(this, function(other) <br />
{ <br />
return (other.systemID !== this.systemID) && (this.distanceToSystem(other) <= range); <br />
}); <br />
}<br />
<br />
=== <code>setInterstellarProperty</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''setInterstellarProperty'''(galaxy : Number, fromsystem : Number, tosystem : Number, key : String, value: String, layer: Number [, manifest: String])<br />
<br />
This is similar to [[#setProperty|setProperty]] but for setting properties of interstellar space regions. Changes made to the current interstellar space region will only take effect if the player leaves and returns. <br />
<br />
Note that the order of fromsystem (the last real system visited) and tosystem (the target of the latest jump) is significant - 0,7,55 is Lave to Leesti; 0,55,7 is Leesti to Lave. In many cases setting the same change for both directions may be necessary.<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Ship_script_event_handlers&diff=46813Oolite JavaScript Reference: Ship script event handlers2015-02-28T09:53:28Z<p>Cim: /* stationReceivedDockingRequest */ and stationAcceptedDockingRequest</p>
<hr />
<div>This page provides a list of event handlers which can be implemented by [[Scripting Oolite with JavaScript|JavaScript scripts for Oolite]].<br />
<br />
Ship scripts are linked to Oolite either using the appropriate [[shipdata.plist#script|shipdata.plist]] setting or via javascript using [[Oolite JavaScript Reference: Ship#setScript|ship.setScript]] and are only active when the ship is present. More than one ship can be assigned the same ship script. Each ship will create its own separate copy of the script, each one independent from the others.<br />
<br />
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.<br />
<br />
Note that a ship script event which affects the player ship (therefore not those marked NPC only, station only, etc.) will also appear as a [[Oolite JavaScript Reference: world_script_event_handlers|world script event]].<br />
<br />
In Oolite 1.79 onwards, each ship has two scripts: the "ship script" as in previous versions (<code>ship.script</code>) and an AI script (<code>ship.AIScript</code>) which manages [[Oolite_Javascript_AI|Javascript-based AI]]. The former is intended for constant events related to the ship itself, and the latter is intended for event handling which varies based on what the ship is currently doing. Both scripts receive all events which do not expect a return value. Events expecting a return value are sent to the ship script ''only''.<br />
<br />
=== Docking ===<br />
<br />
==== <code>shipWillDockWithStation</code> ====<br />
<br />
The <code>shipWillDockWithStation</code> handler is called at the beginning of the docking tunnel effect.<br />
<br />
this.shipWillDockWithStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
At this moment "ship.dockedStation == nil", "ship.status == STATUS_DOCKING"<br />
<br />
<br />
==== <code>shipDockedWithStation</code> ====<br />
<br />
The <code>shipDockedWithStation</code> handler is called at the end of the docking tunnel effect.<br />
<br />
this.shipDockedWithStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
At this moment "ship.dockedStation == the station", "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.<br />
<br />
<br />
==== <code>shipWillLaunchFromStation</code> ====<br />
This handler was added for npc ships with test release 1.75, before it was a worldScript only handler.<br />
<br />
The <code>shipWillLaunchFromStation</code> handler is called for ship scripts on ship creation, before the shipSpawned event. <br />
<br />
this.shipWillLaunchFromStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLaunchedFromStation</code> ====<br />
<br />
The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tract, when the ship has clearly left the station and AI updating begins.<br />
<br />
this.shipLaunchedFromStation = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationWithdrewDockingClearance</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>stationWithdrewDockingClearance</code> handler is received when the station the ship is trying to dock with unexpectedly withdraws clearance (e.g. if <code>station.abortAllDockings</code> is called).<br />
<br />
this.stationWithdrewDockingClearance = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
=== Witchspace Jumps ===<br />
<br />
==== <code>playerWillEnterWitchspace</code> ====<br />
<br />
The <code>playerWillEnterWitchspace</code> handler is called just before a witchspace jump starts and after the <code>shipWillEnterWitchspace</code> handler fires. It is send to all ships in the system to signal that the player is about to leave the system. (By jump or by wormhole)<br />
<br />
this.playerWillEnterWitchspace = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedWormhole</code> ====<br />
<br />
The <code>shipExitedWormhole</code> handler is called when a ship exits a wormhole.<br />
<br />
this.shipExitedWormhole = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipWillEnterWormhole</code> ====<br />
<br />
The <code>shipWillEnterWormhole</code> handler is called when a ship enters a wormhole. only<br />
<br />
this.shipWillEnterWormhole = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>shipWitchspaceBlocked</code> ====<br />
{{oolite-method-added|1.79}}<br />
<br />
The <code>shipWitchspaceBlocked</code> handler is called when a ship is prevented from entering witchspace by the presence of a nearby large mass. The blocking object is passed as a parameter<br />
<br />
this.shipWitchspaceBlocked = function(blocker)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>wormholeSuggested</code> ====<br />
{{oolite-method-added|1.79}}<br />
<br />
The <code>wormholeSuggested</code> handler is called when another ship enters witchspace and suggests that this ship follows. The wormhole used is passed as a parameter. This is most commonly called when a group leader enters witchspace and wishes to take its escorts with it.<br />
<br />
this.wormholeSuggested = function(wormhole)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Enter/Exit Aegis ===<br />
<br />
==== <code>shipEnteredStationAegis</code> ====<br />
<br />
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.<br />
<br />
this.shipEnteredStationAegis = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedStationAegis</code> ====<br />
<br />
The <code>shipExitedStationAegis</code> handler is called when the player leaves the aegis of the main-station (2x scanner range from main-station).<br />
<br />
this.shipExitedStationAegis = function(station)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipEnteredPlanetaryVicinity</code> ====<br />
<br />
The <code>shipEnteredPlanetaryVicinity</code> handler is called when the player enters the planet aegis (3x planet radius).<br />
<br />
this.shipEnteredPlanetaryVicinity = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipExitedPlanetaryVicinity</code> ====<br />
<br />
The <code>shipExitedPlanetaryVicinity</code> handler is called when the player leaves the planet aegis (3x planet radius).<br />
<br />
this.shipExitedPlanetaryVicinity = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipApproachingPlanetSurface</code> ====<br />
<br />
The <code>shipApproachingPlanetSurface</code> handler is called when the player is very close to the planet (crosses a border ± 500 meter above the surface).<br />
<br />
this.shipApproachingPlanetSurface = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLeavingPlanetSurface</code> ====<br />
<br />
The <code>shipLeavingPlanetSurface</code> handler is called when the player leaves the planet (crosses a border ± 500 meter above the surface).<br />
<br />
this.shipLeavingPlanetSurface = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Combat ===<br />
<br />
==== <code>cascadeWeaponDetected</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>cascadeWeaponDetected</code> handler fires when a Q-bomb (or equivalent device) detonates within scanner range of the player. The stock Q-mine (and potentially OXP equivalents) will also send this handler at the start of the countdown, giving ships more time to react. The weapon entity will be passed as a parameter.<br />
<br />
this.cascadeWeaponDetected = function(weapon)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>defenseTargetDestroyed</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>defenseTargetDestroyed</code> handler is sent when a defense (i.e. secondary) target is destroyed. A reference to the destroyed ship (which will become invalid shortly) is passed as a parameter.<br />
<br />
this.defenseTargetDestroyed = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>escortAttack</code> ====<br />
<br />
The <code>escortAttack</code> handler is sent to all escorts of a mothership that are deployed. The mother first changes the escorts AI to interceptAI.plist and also sets the escort target to his own target before sending this handler to the escorts.<br />
<br />
this.escortAttack = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>helpRequestReceived</code> ====<br />
{{oolite-method-added|1.79}}<br />
<br />
The <code>helpRequestReceived</code> handler is sent when an ally of this ship is being attacked and requires help. There are two parameters, the ally and the enemy.<br />
<br />
this.helpRequestReceived = function(ally, enemy)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAttackedOther</code> ====<br />
The <code>shipAttackedOther</code> handler is called when this ship hits another with a laser shot. <code>other</code> is the identity of the ship being hit (added in test version 1.74.2).<br />
<br />
this.shipAttackedOther = function(other)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAttackedWithMissile</code> ====<br />
<br />
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.<br />
<br />
this.shipAttackedWithMissile = function(missile, whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAttackerDistracted</code> ====<br />
<br />
The <code>shipAttackerDistracted</code> handler is called when the ship's current attacker is distracted by another ship. <code>whom</code> contains the ship which is doing the distracting.<br />
<br />
this.shipAttackerDistracted = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBeingAttacked</code> ====<br />
<br />
The <code>shipBeingAttacked</code> handler is called when a laser shot hits. <code>whom</code> the identity of the ship that attacked.<br />
<br />
this.shipBeingAttacked = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBeingAttackedByCloaked</code> ====<br />
<br />
The <code>shipBeingAttackedByCloaked</code> handler is called when a laser shot from a cloaked ship hits. There is no parameter provided to identify the cloaked ship.<br />
<br />
this.shipBeingAttackedByCloaked = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBeingAttackedUnsuccessfully</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>shipBeingAttackedUnsuccessfully</code> handler is called when a laser shot narrowly misses the ship, when fired by an uncloaked ship intending to hit. <code>whom</code> the identity of the ship that attacked.<br />
<br />
this.shipBeingAttackedUnsuccessfully = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCloakActivated</code> ====<br />
<br />
The <code>shipCloakActivated</code> handler is called whenever the script's target ship activates its cloaking device. No parameters are required for this handler (added in test version 1.74).<br />
<br />
this.shipCloakActivated = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCloakDeactivated</code> ====<br />
<br />
The <code>shipCloakDeactivated</code> handler is called whenever the script's target ship deactivates its cloaking device. No parameters are required for this handler (added in test version 1.74).<br />
<br />
this.shipCloakDectivated = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetDestroyed</code> ====<br />
<br />
The <code>shipTargetDestroyed</code> handler is called when the target gets destroyed by this ship. <code>target</code> contains the destroyed target entity. This command is always preceded by the <code>shipTargetLost</code> handler.<br />
<br />
this.shipTargetDestroyed = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipDied</code> ====<br />
<br />
The <code>shipDied</code> handler is called when the ship or player dies.<br />
<br />
this.shipDied = function(whom, why)<br />
{<br />
// Your code here<br />
}<br />
'''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".<br><br />
("cascade weapon" is new in 1.74 and "removed" / "energy damage" were accidentally switched in 1.73)<br />
<br />
==== <code>shipEnergyBecameFull </code> ====<br />
<br />
The <code>shipEnergyBecameFull </code> handler is called when the energy level reaches its maximum value again. <br />
<br />
this.shipEnergyBecameFull = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipEnergyIsLow</code> ====<br />
<br />
The <code>shipEnergyIsLow</code> handler is called every time when a ship gets energy damage while the energy level lies below 25% of its maximum value.<br />
<br />
this.shipEnergyIsLow = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipHitByECM</code> ====<br />
<br />
The <code>shipHitByECM</code> handler is called when a ship receives a ECM pulse. <code>pulsesRemaining</code> contains the number of pulses that still have to be send by the sending ship. When a ship activates his ecm, he will send 4 pulses with 0.5 seconds interval and increasing range.: 6400 --> 12800 --> 19200 --> 25600. (Handler added in test version 1.71)<br />
<br />
this.shipHitByECM = function(pulsesRemaining)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipFiredMissile</code> ====<br />
<br />
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. (Handler added in test version 1.74)<br />
<br />
this.shipFiredMissile = function(missile, target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipKilledOther</code> ====<br />
<br />
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. (Handler added in test version 1.75) <br />
<br />
this.shipKilledOther = function(whom,damageType)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetAcquired</code> ====<br />
<br />
The <code>shipTargetAcquired</code> handler is called whenever a new target is selected. (Handler added in test version 1.74) <br />
<br />
this.shipTargetAcquired = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetCloaked</code> ====<br />
<br />
The <code>shipTargetCloaked</code> handler is called when the target cloakes.<br />
<br />
this.shipTargetCloaked = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTargetLost</code> ====<br />
<br />
The <code>shipTargetLost</code> handler is called when the target gets lost. <code>target</code> contains the lost target entity.<br>(Handler introduced in 1.74 as replacement with consistent name for the old handler: 'shipLostTarget'.)<br />
<br />
this.shipTargetLost = function(target)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipTakingDamage</code> ====<br />
<br />
The <code>shipTakingDamage</code> handler is called when a ship sustains damage. Handler is added in Oolite 1.75<br><br />
It transfers the <code>amount</code> of damage, <code>who</code> caused the damage and the <code>type</code> of damage.<br />
<br />
For the player ship, only damage not absorbed by the shields will appear in <code>amount</code>, but the handler will be called anyway with zero as the amount if the shields absorb all the damage.<br />
<br />
this.shipTakingDamage = function(amount, whom, type)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Miscellaneous ===<br />
<br />
==== <code>cargoDumpedNearby</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>cargoDumpedNearby</code> handler is sent when a nearby ship dumps a cargo pod.<br />
<br />
this.cargoDumpedNearby = function(cargo: ship, releasedBy: ship)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>commsMessageReceived</code> ====<br />
<br />
The <code>commsMessageReceived</code> handler is sent when receiving a message from other ships. Handler is added in Oolite 1.75<br />
<br />
this.commsMessageReceived = function(message: string, sender: ship)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>distressMessageReceived</code> ====<br />
<br />
The <code>distressMessageReceived</code> handler is sent when receiving a distress message from other ships. Handler is added in Oolite 1.75<br />
<br />
this.distressMessageReceived = function(aggressor: ship, sender: ship)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>equipmentAdded</code> ====<br />
{{Oolite-method-added|1.81}}<br />
The <code>equipmentAdded</code> handler is called whenever a 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.<br />
<br />
this.equipmentAdded = function(equipmentKey)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>equipmentRemoved</code> ====<br />
{{Oolite-method-added|1.81}}<br />
The <code>equipmentRemoved</code> handler is called whenever a 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.<br />
<br />
this.equipmentAdded = function(equipmentKey)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAchievedDesiredRange</code> ====<br />
{{Oolite-method-added|1.79}}<br />
The <code>shipAchievedDesiredRange</code> handler is called when the ship reaches the desired range from its destination during certain flight behaviours.<br />
<br />
this.shipAchievedDesiredRange = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipAIFrustrated</code> ====<br />
{{Oolite-method-added|1.79}}<br />
The <code>shipAIFrustrated</code> handler is called when the ship's low-level behaviour is unable to achieve the desired result (e.g. a <code>performFlee</code> request is not getting further from the target). A short string describing the context of the frustration is passed as a parameter.<br />
<br />
this.shipAIFrustrated = function(context)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipBountyChanged</code> ====<br />
{{Oolite-method-added|1.77}}<br />
<br />
The <code>shipBountyChanged</code> handler is sent when an event tries to change the bounty level of the ship. <code>delta</code> may be zero, positive or negative. <code>reason</code> is a string that may either contain a standard value or a custom value set by an OXP. The standard values are:<br />
* '''setup actions''': Bounty level settings in the system populator or as a side effect of launching a ship from a station with a particular role.<br />
* '''scripted''': OXP scripted changes to bounties, with no specified cause.<br />
* '''attacked police''': The ship attacked a police ship<br />
* '''attacked main station''': The ship attacked the main station<br />
* '''attacked innocent''': The ship attacked a Clean ship and was seen doing so<br />
* '''seen by police''': The ship was seen by police committing a crime<br />
* '''distress call''': A police ship responded to a distress call from a ship that this ship is attacking<br />
* '''illegal exports''': The ship launched from a main station while carrying illegal goods (player only)<br />
* '''assisting offenders''': The bounty adjustment applied when a clean ship escorts an offender, or vice versa (NPC only)<br />
* '''new galaxy''': The ship entered a new galaxy (player only)<br />
* '''new system''': The ship entered a new system<br />
* '''paid fine''': The ship was marked for fines by police, and then paid them on docking (player only)<br />
* '''escape pod''': The ship is a replacement ship from escape pod insurance (player only)<br />
* '''assisting police''': The ship helped out a police ship in combat<br />
* '''unknown''': The bounty changed for an unknown reason. This should not occur.<br />
<br />
this.shipBountyChanged = function(delta,reason)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCloseContact</code> ====<br />
<br />
The <code>shipCloseContact</code> handler is sent when approaching otherShip and when "track_contacts" in shipData is true.<br />
<br />
this.shipCloseContact = function(otherShip)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipCollided</code> ====<br />
<br />
The <code>shipCollided</code> handler is sent after a collision with otherShip.<br />
<br />
this.shipCollided = function(otherShip)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipNowFacingDestination</code> ====<br />
{{Oolite-method-added|1.79}}<br />
The <code>shipNowFacingDestination</code> handler is called when the ship is facing its destination during certain flight behaviours.<br />
<br />
this.shipNowFacingDestination = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipReachedEndPoint</code> ====<br />
<br />
The <code>shipReachedEndPoint</code> handler is sent after reaching the last navigation point when in mode <code>performFlyRacepoints</code>.<br />
<br />
shipReachedEndPoint = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipReachedNavPoint</code> ====<br />
<br />
The <code>shipReachedNavPoint</code> handler is sent after reaching a navigation point when in mode <code>performFlyRacepoints</code>.<br />
<br />
this.shipReachedNavPoint = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipScoopedOther</code> ====<br />
<br />
The <code>shipScoopedOther</code> handler is called when a ship scoops scripted_cargo. ("cargo_type" = CARGO_SCRIPTED_ITEM) Other cargo, even scooping escapepods, doesn't trigger a handler.<br>The scooped item is transferred as argument. The scooped cargo itselfs gets the handler: <code>shipWasScooped</code> with the scooper as argument. Starting with Oolite 1.77 this handler will fire on every scooped object.<br />
<br />
this.shipScoopedOther = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLaunchedEscapePod</code> ====<br />
<br />
The <code>shipLaunchedEscapePod</code> handler is called when the pilot bails out. This will be followed by a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds when it is the player that is ejecting.<br />
<br />
this.shipLaunchedEscapePod = function(escapepod, passengers)<br />
{<br />
// Your code here<br />
}<br />
<br />
<code>escapepod</code> contains the main pod with the pilot. <code>passengers</code> will be added with Oolite 1.77 and is an array with passenger pods for those ships that have more than one escape-capsule defined.<br />
<br />
=== NPC only ===<br />
<br />
==== <code>aiAwoken</code> ====<br />
{{oolite-method-added|1.79}}<br />
This is sent to the ship periodically when <code>ship.AIScriptWakeTime</code> passes. One of the actions of this handler should be to cause a new wake time to be set. It is received by both the ship script and the AI script but usually only of interest to the latter.<br />
<br />
==== <code>aiStarted</code> ====<br />
{{oolite-method-added|1.79}}<br />
This is sent to the ship when a new Javascript-based AI is loaded. The AI Script should then use it to do initialisation. The ship script can usually ignore it.<br />
<br />
==== <code>coordinatesForEscortPosition</code> ====<br />
<br />
The <code>coordinatesForEscortPosition</code> handler fires whenever the game engine wishes to know the positions of escorts relative to their group leader, and fires in the group leader's ship script at that time. It is given two parameters: the number of the escort, and the maximum number of escorts the group leader might have (which is not necessarily the number of escorts it currently has, of course). Unlike most ship script handlers, which return void, ''this handler is required to return a Vector'' (or a value equivalent to a Vector) describing the relative position of the escort to the mothership.<br />
<br />
coordinatesForEscortPosition = function(num,max)<br />
{<br />
// Your code here<br />
return escort_position;<br />
}<br />
<br />
The escort position is relative to the mothership, and in the mothership's coordinate system. For example, to place an escort 500m to the right of the mothership, return <code>new Vector(500, 0, 0);</code>. You are responsible for ensuring that there is sufficient space between the escorts and the mothership, and between any pair of escorts, or they will spend most of their time trying to avoid collisions with each other. If you intend to use the same ship script on several ships of varying sizes, you may wish to include the mothership's [[Oolite_JavaScript_Reference:_Entity#collisionRadius|collisionRadius]] in the calculations.<br />
<br />
Placing escorts directly ahead of the mothership (e.g. <code>new Vector(0, 0, 500);</code>) or too close to the mothership will trigger collision warnings for the mothership, making it difficult to maintain level flight for any significant time.<br />
<br />
==== <code>entityDestroyed</code> ====<br />
<br />
The <code>entityDestroyed</code> handler fires immediately ''after'' the ship becomes invalid, regardless of the reason, except when the game restarts. This is the best place for all kind of 'clean-up' code, for example stopping [[Oolite_JavaScript_Reference:_Timer|Timers]] associated with the ship script. (Added with Oolite 1.75.1)<br />
<br />
entityDestroyed = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>escortAccepted</code> ====<br />
<br />
The <code>escortAccepted</code> handler is called when a mother ship accepts this ship as an escort. The mothership simultaneously gets a <code>shipAcceptedEscort</code> event.<br />
<br />
this.escortAccepted = function(mothership)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>escortDock</code> ====<br />
<br />
The <code>escortDock</code> handler is called by a mother ships that uses the AI command: <code>dockEscorts</code>. Escorts are instructed to change AI into dockingAI.plist and enter the ABORT state of this AI after a certain delay. Than this event is send to all his escorts, each with a different delay with 3 seconds spacing.<br />
<br />
this.escortDock = function(delay)<br />
{<br />
// Your code here<br />
}<br />
<br />
<br />
==== <code>escortRejected</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>escortRejected</code> handler is called when a mother ship rejects this ship as an escort.<br />
<br />
this.escortRejected = function(mothership)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>offenceCommittedNearby</code> ====<br />
<br />
The <code>offenceCommittedNearby</code> handler is only send to police ships in scanner range of a hostile action. It transfers the attacker and the victim to the police vessel.<br />
<br />
this.offenceCommittedNearby = function(attacker, victim)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>scriptedAI</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>scriptedAI</code> handler is called each frame while the ship's AI is in "performScriptedAI" or "performScriptedAttackAI" mode. It must return an object defining the ship's flight parameters. The <code>delta</code> parameter is the length of the current frame in seconds. [[OXP_Scripted_AI|More information on using this functionality]]<br />
<br />
this.scriptedAI = function(delta)<br />
{<br />
// Your code here<br />
return flightParameters;<br />
}<br />
<br />
==== <code>shipAcceptedEscort</code> ====<br />
<br />
The <code>shipAcceptedEscort</code> handler is called when this ship accepts a new ship as an escort. The escort simultaneously gets a <code>escortAccepted</code> event. <br />
<br />
this.shipAcceptedEscort = function(newEscort)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipLandedOnPlanet</code> ====<br />
<br />
The <code>shipLandedOnPlanet</code> handler is called for ships landing on a planet. It transfers the <code>planet</code> parameter. (Will be added with Oolite 1.77)<br />
<br />
shipLandedOnPlanet = function(planet)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipRemoved</code> ====<br />
<br />
The <code>shipRemoved</code> handler is called for ships removed by script. It transfers the <code>suppressDeathEvent</code> parameter so the script knows if there will also follow a shipDied() event.<br />
<br />
shipRemoved = function(suppressDeathEvent)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipSpawned</code> ====<br />
<br />
The <code>shipSpawned</code> handler is called for newly added ships. It does not trigger on adding but on the first update after adding. On a witchspace jump it means that first all ships are added to the system, then afterwards all the shipSpawned() events are triggered. Note that this is not called for subentities - if subentities need specific set up running, this must be called from the main ship's handler.<br />
<br />
this.shipSpawned = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>spawnedAsEscort</code> ====<br />
<br />
The <code>spawnedAsEscort</code> handler is called for newly added escort ships. It does trigger on adding the ship and before the shipSpawned() handlers is activated. It has the mothership as argument. <br />
<br />
this.spawnedAsEscort = function(mother)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipWasDumped</code> ====<br />
<br />
The <code>shipWasDumped</code> handler is sent to the cargopod when a ship jettisons it. The dumping ship is transferred as the argument. <br />
<br />
this.shipWasScooped = function(dumper)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>shipWasScooped</code> ====<br />
<br />
The <code>shipWasScooped</code> handler is send to the cargopod when a ship scoops scripted_cargo. ("cargo_type" = CARGO_SCRIPTED_ITEM) The scooper is transferred as argument. The scooper itself gets a trigger on the handler <code>shipScoopedOther</code>.<br />
<br />
this.shipWasScooped = function(scooper)<br />
{<br />
// Your code here<br />
}<br />
<br />
=== Stations only ===<br />
<br />
==== <code>alertConditionChanged</code> ====<br />
<br />
The <code>alertConditionChanged</code> handler is called when a station's alert status ([[Oolite_JavaScript_Reference:_Station#alertCondition|Station.alertCondition]]) changes. Only the player and stations have an alert condition. The equivalent player event is handled inside [[Oolite_JavaScript_Reference:_world_script_event_handlers|world scripts]].<br />
<br />
this.alertConditionChanged = function(newCondition, oldCondition)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>otherShipDocked</code> ====<br />
<br />
The <code>otherShipDocked</code> handler is called with a station script only, when an ship docks. It has the docked ship as argument.<br />
<br />
this.otherShipDocked = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationDockingQueuesAreEmpty</code> ====<br />
{{oolite-method-added|1.79}}<br />
The <code>stationDockingQueuesAreEmpty</code> handler is called when the last ship in the queues docks with the station (or gives up docking and leaves).<br />
<br />
this.stationDockingQueuesAreEmpty = function()<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationLaunchedShip</code> ====<br />
<br />
The <code>stationLaunchedShip</code> handler is called with a station script only, when a ship launches. It has the launched ship as argument.<br><br />
<br />
this.stationLaunchedShip = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationAcceptedDockingRequest</code> ====<br />
{{oolite-method-added|1.81}}<br />
The <code>stationReceivedDockingRequest</code> handler is called when a ship has requested docking clearance and has been allocated a dock. Due to the way in which docking clearance works, this is likely to be called several times for the same ship as it moves through the docking sequence.<br />
<br />
this.stationReceivedDockingRequest = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
==== <code>stationReceivedDockingRequest</code> ====<br />
{{oolite-method-added|1.81}}<br />
The <code>stationReceivedDockingRequest</code> handler is called when a ship requests docking clearance. The ship requesting is passed as a parameter. This is often necessary for carriers which will need to come to a stop before ships can dock with them. Due to the way in which docking clearance works, this is likely to be called several times for the same ship as it moves through the docking sequence.<br />
<br />
this.stationReceivedDockingRequest = function(whom)<br />
{<br />
// Your code here<br />
}<br />
<br />
(note: a handler by this name was present in 1.79 and 1.80, but was called at the wrong time and should not be used. Set a minimum version of 1.81 if you use this event handler)<br />
<br />
==== <code>willOpenDockingPortFor</code> ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>willOpenDockingPortFor</code> handler is called with a station script only, when a ship requests docking, in cases where a dock is set to generally disallow docking (i.e. [[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsDocking]] is false). It returns a Boolean:<br />
* if it returns false (or this function isn't defined), this dock will not be opened later for the requesting ship, and it should not try again.<br />
* if it returns true, this dock will be opened later for the requesting ship, and it should try again later if it cannot find another suitable dock on this station.<br />
The handler is passed the identity of the dock and the requesting ship<br />
<br />
this.willOpenDockingPortFor = function(dock, ship)<br />
{<br />
// Your code here<br />
return allow;<br />
}<br />
<br />
=== Docks Only ===<br />
{{oolite-method-added|1.77}}<br />
<br />
==== acceptDockingRequestFrom ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>acceptDockingRequestFrom</code> handler is called when a ship is looking for docking clearance from the station, and is considering this dock. To get as far as calling this handler, the dock must have [[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsDocking]] true, and be large enough to physically fit the ship.<br />
<br />
It returns a boolean: true to accept the request (which, depending on docking queue lengths will not necessarily mean that this dock is the one that the ship heads for), and false to reject the request. 'true' is assumed if this handler is not defined.<br />
<br />
This handler may be called multiple times for the same ship if the ship is having difficulty finding a suitable docking queue.<br />
<br />
this.acceptDockingRequestFrom = function(ship)<br />
{<br />
// Your code here<br />
return allow;<br />
}<br />
<br />
==== acceptLaunchingRequestFrom ====<br />
{{oolite-method-added|1.77}}<br />
<br />
The <code>acceptLaunchingRequestFrom</code> handler is called when a ship is looking for launching clearance from the station, and is considering this dock. To get as far as calling this handler, the dock must have [[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsLaunching]] true, and be large enough to physically fit the ship (unless the ship is the player).<br />
<br />
It returns a boolean: true to accept the request (which, depending on launching queue lengths will not necessarily mean that this dock is the one that the ship uses), and false to reject the request. 'true' is assumed if this handler is not defined.<br />
<br />
this.acceptLaunchingRequestFrom = function(ship)<br />
{<br />
// Your code here<br />
return allow;<br />
}<br />
<br />
<br />
<br />
<br />
<br />
=== Missing Events ===<br />
<br />
All initially planned events have a corresponding event handler in v1.74.<br />
<br />
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].<br />
<br />
'''See also:''' [[Oolite JavaScript Reference: world_script_event_handlers|world_script_event_handlers]]<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Ship&diff=46790Oolite JavaScript Reference: Ship2015-02-24T18:24:05Z<p>Cim: /* subEntityRotation */ new property</p>
<hr />
<div><small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Entity|Entity]]</code></small><br /><br />
<small>'''Subtypes:''' <code>[[Oolite JavaScript Reference: Station|Station]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code></small><br />
<br />
The '''<code>Ship</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing a ship, station, missile, cargo pod or other flying item – anything that can be specified in [[shipdata.plist]]. A <code>Ship</code> has all the properties and methods of a <code>Entity</code>, and several others.<br />
<br />
<code>[[Oolite JavaScript Reference: Station|Station]]</code>s and the <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code> are types of ship. Note that these more specific types have additional properties and methods.<br />
<br />
== Properties ==<br />
=== <code>accuracy</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''accuracy''' : Number (read/write, read-only and irrelevant for player ship)<br />
The accuracy of the ship's AI. Varies between -5 and +10 for ships, or 0 and +10 for missiles. Setting a value outside the allowed range will set the closest value within the allowed range.<br />
<br />
For missiles, this affects the missile tracking, with 0 being the default value.<br />
<br />
For NPC ships, this affects their combat AI in many ways. Values of +5 or higher enable various [[OXP_NPC_Combat_AI|special combat AIs]] for a tough fight.<br />
<br />
=== <code>aftWeapon</code> ===<br />
'''aftWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped aft weapon, or <code>null</code>.<br />
<br />
'''See also:''' <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>AI</code> ===<br />
'''AI''' : String (read-only)<br />
The name of the ship’s current plist-based state machine AI. If the ship is using Javascript-based AI, this will always be "<code>nullAI.plist</code>"<br />
<br />
'''See also:''' <code>[[#AIState|AIState]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AIScript|AIScript]]</code><br />
<br />
=== <code>AIFoundTarget</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''AIFoundTarget''' : Entity (read/write, read-only for player)<br />
The "found target" of the ship's AI. This is set by various AI state commands, and is often copied to the primary target with the <code>setTargetToFoundTarget</code> AI command.<br />
<br />
=== <code>AIPrimaryAggressor</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''AIPrimaryAggressor''' : Entity (read/write, read-only for player)<br />
The "primary aggressor" of the ship's AI. Often the last ship to attack this ship.<br />
<br />
=== <code>AIScript</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''AIScript''' : String (read-only)<br />
The name of the ship’s current Javascript-based AI. If the ship is using plist-based AI, this will always be "<code>oolite-nullAI.js</code>"<br />
<br />
'''See also:''' <code>[[#AIScriptWakeTime|AIScriptWakeTime]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AI|AI]]</code><br />
<br />
=== <code>AIScriptWakeTime</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''AIScriptWaketime''' : Number (read-write)<br />
The next game time at which the ship's Javascript-based AI script will receive an <code>aiAwoken</code> event.<br />
<br />
=== <code>AIState</code> ===<br />
'''AIState''' : String (read/write, read-only for player)<br />
The ship’s plist AI’s current state.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#reactToAIMessage|reactToAIMessage()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code><br />
<br />
=== <code>alertCondition</code> ===<br />
'''alertCondition''' : Number (read-only integer)<br />
The ship's current alert condition (Docked = 0, Green = 1, Yellow = 2, Red = 3). Non-Station non-Player ships are generally only found at condition Yellow or Red.<br />
<br />
'''See also:''' [[Oolite_JavaScript_Reference:_Station#alertCondition|station.alertCondition]]<br />
<br />
=== <code>autoAI</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''autoAI''' : Boolean (read-only)<br />
The value of the "<code>auto_ai</code>" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the AI of this ship to better fit into scenarios or roles. If this is false, the ship's provider would prefer you not to alter the AI of this ship but to use it as-is.<br />
<br />
=== <code>autoWeapons</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''autoWeapons''' : Boolean (read-only)<br />
The value of the "<code>auto_weapons</code>" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the properties of this ship to better fit into scenarios or roles. If this is false, the ship's provider would prefer you not to alter the properties of this ship but to use it as-is.<br />
<br />
=== <code>beaconCode</code> ===<br />
'''beaconCode''' : String (read-only in 1.76, read-write from 1.77)<br />
If the ship is a beacon, an identifying string. The first character is used for identification on the [[Advanced Space Compass]]. For non-beacons, this property is <code>null</code>. This can not be changed by script for either the player's ship or the main station.<br />
<br />
'''See also:''' <code>[[#isBeacon|isBeacon]]</code><br />
<br />
=== <code>beaconLabel</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''beaconLabel''' : String (read/write)<br />
A full label for the beacon. This is useful where the beacon code and the full beacon label do not begin with the same letter.<br />
<br />
=== <code>boundingBox</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''boundingBox''' : Vector (read-only)<br />
For ships, a vector describing the dimensions of the cuboid box containing the ship aligned to the ship axes, including all non-flasher sub-entities. For sub-entities, the dimensions of the box for the sub-entity alone.<br />
<br />
Vector components match the standard model order - <code>x</code> is width, <code>y</code> is height, <code>z</code> is length.<br />
<br />
=== <code>bounty</code> ===<br />
'''bounty''' : Number (read/write integer)<br />
The bounty on the ship.<br />
<br />
In 1.77, changes to the bounty are given a reason. If you change this directly, the reason sent to [[Oolite_JavaScript_Reference:_ship_script_event_handlers#shipBountyChanged|shipBountyChanged]] will be "scripted". To set a different reason, use [[#setBounty|setBounty]] instead.<br />
<br />
=== <code>cargoList</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''cargoList''' : Array (read-only)<br />
A list of the ship's current cargo, grouped by cargo type. For the player ship, this is equivalent to <code>player.ship.manifest.list</code><br />
<br />
=== <code>cargoSpaceCapacity</code> ===<br />
'''cargoSpaceCapacity''' : Number (read-only in 1.80, read/write in 1.81, integer)<br />
The ship’s cargo capacity, in tons.<br />
<br />
=== <code>collisionExceptions</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''collisionExceptions''' : Array (read-only)<br />
A list of ships this ship is currently prevented from colliding with. See [[#addCollisionException|addCollisionException]] and [[#removeCollisionException|removeCollisionException]].<br />
<br />
=== <code>commodity</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''commodity''' : String (read-only)<br />
The commodity for cargo containers as a lowercase string. Returns <code>null</code> for non-cargo ships. For scripted cargo that has no specific cargo defined, it returns the general description "goods".<br />
<br />
=== <code>commodityAmount</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''commodityAmount''' : Number (read-only)<br />
The amount of commodity in a cargo container. (not the number of containers in a ship)<br />
<br />
=== <code>contracts</code> ===<br />
'''contracts''' : Array (read-only NSDictionary)<br />
The ship’s contracts. (For now only available for the player). Each contract contains the entries: <code>commodity: string, quantity: integer, description: string, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
<br />
For example, the information of the first contract can be obtained by:<br />
player.ship.contracts[0].commodity<br />
player.ship.contracts[0].quantity<br />
player.ship.contracts[0].description<br />
player.ship.contracts[0].start<br />
player.ship.contracts[0].destination<br />
player.ship.contracts[0].startName<br />
player.ship.contracts[0].destinationName<br />
player.ship.contracts[0].eta // Estimated Time of Arrival.<br />
player.ship.contracts[0].etaDescription<br />
player.ship.contracts[0].fee // The profit of the contract, paid out on successful delivery.<br />
player.ship.contracts[0].premium // The sum paid to obtain the goods and paid back on successful delivery.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this contract, and premium was the amount the player had to pay to secure this contract.<br />
<br />
=== <code>cloakAutomatic</code> ===<br />
'''cloakAutomatic''' : Boolean (read/write)<br />
If <code>true</code> (the default), the ship will automatically engage its cloak while attacking. Otherwise, it must be managed by a script. The corresponding ''[[shipdata.plist]]'' key is <code>cloak_automatic</code>.<br />
<br />
=== <code>crew</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''crew''' : Array (read-only)<br />
An array containing the ship's crew. Each crew member is represented as a dictionary. Note that in current Oolite versions ships only have a single crew member defined.<br />
<br />
=== <code>cruiseSpeed</code> ===<br />
'''cruiseSpeed''' : Number (read-only nonnegative)<br />
The ship’s “normal” <code>[[#desiredSpeed|desiredSpeed]]</code>, used in normal flight. Normally this is 80 % of <code>[[#maxSpeed|maxSpeed]]</code>, but it may be lowered when accepting a slow escort.<br />
<br />
=== <code>currentWeapon</code> ===<br />
{{oolite-prop-added|1.77}} <br />
'''currentWeapon''' : EquipmentType (read/write)<br />
A shortcut property to whichever of <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code> or <code>[[#starboardWeapon|starboardWeapon]]</code> represents the ship's currently active laser mount.<br />
<br />
=== <code>dataKey</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''dataKey''' : String (read-only)<br />
The ship data key used to define this ship (e.g. <code>adder-player</code> or <code>coriolis-station</code>)<br />
<br />
=== <code>defenseTargets</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''defenseTargets''' : Array (read-only)<br />
The array of defense targets that the ship has. If the ship has point defense weapons (turrets, thargoid lasers) it may fire them at these targets if it cannot hit its primary target.<br />
<br />
'''See also:''' <code>[[#addDefenseTarget|addDefenseTarget]]</code>, <code>[[#clearDefenseTargets|clearDefenseTargets]]</code><br />
<br />
=== <code>desiredRange</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''desiredRange''' : Number (read/write nonnegative, read-only for player)<br />
The range the AI uses in various AI routines to set a distance between the ship and another object - for example, the radius of a sphere around a destination point, or the distance to flee from a hostile ship.<br />
<br />
=== <code>desiredSpeed</code> ===<br />
'''desiredSpeed''' : Number (read/write nonnegative, read-only for player)<br />
The speed the AI will attempt to maintain. The AI core and AI script may change this from time to time. The corresponding AI method is <code>setSpeedFactorTo:</code>; a speed factor of 1.0 corresponds to a <code>desiredSpeed</code> equal to <code>[[#maxSpeed|maxSpeed]]</code>.<br />
<br />
'''See also:''' <code>[[#cruiseSpeed|cruiseSpeed]]</code><br />
<br />
=== <code>destination</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''destination''' : Vector (read/write, read-only for player)<br />
The destination coordinates for the AI, used in behaviours such as <code>performFlyToRangeFromDestination</code>.<br />
<br />
=== <code>destinationSystem</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''destinationSystem''' : Number (read/write)<br />
The destination system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.<br />
<br />
=== <code>displayName</code> ===<br />
'''displayName''' : String (read/write, read-only for player)<br />
The name of the ship as seen by the player. By default in 1.78 or earlier it is the same as <code>[[#name|name]]</code>. In 1.79 or later it is a combination of [[#shipClassName|shipClassName]] and [[#shipUniqueName|shipUniqueName]]<br />
<br />
=== <code>dockingInstructions</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''dockingInstructions''' : Object (read-only)<br />
If the ship is currently attempting to dock with a station, this describes the next step on its docking procedure<br />
<br />
{<br />
station: [Station "Coriolis Station" "Coriolis Station" position: (-31043.6, -94232.3, 619036) scanClass: CLASS_STATION status: STATUS_ACTIVE],<br />
match_rotation: 0,<br />
ai_message: "APPROACH_COORDINATES",<br />
speed: 512,<br />
destination: {<br />
x: -28033.37401563089,<br />
y: -92813.76688970842,<br />
z: 622226.0625336492<br />
},<br />
range: 96<br />
}<br />
<br />
'''See also:''' <code>[[#requestDockingInstructions|requestDockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code><br />
<br />
=== <code>energyRechargeRate</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''energyRechargeRate''' : Number (read-only, read/write from 1.81)<br />
The rate at which energy is replenished in every second. The corresponding ''[[shipdata.plist]]'' key is <code>energy_recharge_rate</code>.<br />
<br />
Note for the player ship that this includes the boost from an extra or naval energy unit, and NPC (but not player) ships with military shield boosters also have an increase to this in lieu of actual shields.<br />
<br />
=== <code>entityPersonality</code> ===<br />
'''entityPersonality''' : Number (read-only integer)<br />
A random number in the range 0..32767 which is generated when the ship is created. Equivalent to the <code>entityPersonalityInt</code> [[Shaders in Oolite: uniforms#Ship|uniform binding]].<br />
<br />
=== <code>equipment</code> ===<br />
'''equipment''' : Array of [[Oolite_JavaScript_Reference:_EquipmentInfo|EquipmentInfo ]] (read-only)<br />
The equipment a ship is carrying.<br />
<br />
=== <code>escortGroup</code> ===<br />
'''escortGroup''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]<br />
The ship’s deployed escorts.<br />
<br />
'''See also:''' <code>[[#maxEscorts|maxEscorts]]</code><br />
<br />
=== <code>escorts</code> ===<br />
'''escorts''' : Array (read-only array of [[Oolite JavaScript Reference: Entity|Entity]]s)<br />
The ship’s deployed escorts.<br />
<br />
=== <code>exhaustEmissiveColor</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''exhaustEmissiveColor''' : Color (read/write)<br />
The baseline colour of the ship's exhaust. Damage to the ship, and use of injectors and torus drive, apply a fixed transformation to this colour, so not all colours are effective as exhaust colours.<br />
<br />
=== <code>exhausts</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''exhausts''' : Array (read-only)<br />
An array of the ship's [[Oolite_JavaScript_Reference:_ExhaustPlume|ExhaustPlume]] subentities.<br />
<br />
=== <code>extraCargo</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''extraCargo''' : Number (read-only integer)<br />
The amount the cargo capacity increases when an extra cargobay is installed. The corresponding ''[[shipdata.plist]]'' key is <code>extra_cargo</code>.<br />
<br />
=== <code>flashers</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''flashers''' : Array (read-only)<br />
An array of the ship's [[Oolite_JavaScript_Reference:_Flasher|Flasher]] subentities.<br />
<br />
=== <code>forwardWeapon</code> ===<br />
'''forwardWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped forward weapon, or <code>null</code>.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>fuel</code> ===<br />
'''fuel''' : Number (read/write)<br />
The ship’s current fuel capacity, in LY. The game will limit this to the range 0..7, and round it off to the nearest tenth.<br />
<br />
'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#fuelLeakRate|PlayerShip.fuelLeakRate]]</code><br />
<br />
=== <code>fuelChargeRate</code> ===<br />
'''fuelChargeRate''' : Number (read-only)<br />
The cost, relative to the cost for a new Cobra III, of a unit of fuel. When buying fuel for a ship, the price in [[equipment.plist]] will be multiplied by this number.<br />
<br />
=== <code>group</code> ===<br />
'''group''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]<br />
Contains ship’s belonging to each other. Added pirate groups are an example or a station with its launched defenders.<br><br />
A group is an individual object that can be linked to several ships belonging to the same group. When a ship dies and the group object has still owners, the group stays active as object. The group is only removed from memory after the last ship that had this group as property is removed.<br><br />
Adding a group to a ship does not automatic puts that ship in the group. For that to happen you need also use the addShip() command. <br />
e.g. <br />
this.ship.group = new ShipGroup();<br />
this.ship.group.addShip(this.ship);<br />
<br />
=== <code>hasHostileTarget</code> ===<br />
'''hasHostileTarget''' : Boolean (read-only)<br />
<code>true</code> if the ship’s AI is trying to kill something, <code>false</code> otherwise. Always <code>false</code> for the player.<br />
<br />
=== <code>hasHyperspaceMotor</code> ===<br />
'''hasHyperspaceMotor''' : Boolean (read-only)<br />
True if the ship can make witchspace jumps. The corresponding ''[[shipdata.plist]]'' entry is <code>hyperspace_motor</code>.<br />
<br />
=== <code>hasSuspendedAI</code> ===<br />
'''hasSuspendedAI''' : Boolean (read-only)<br />
<code>true</code> if the ship has suspended AIs, <code>false</code> otherwise.<br />
<br />
=== <code>heatInsulation</code> ===<br />
'''heatInsulation''' : Number (read/write)<br />
The ship’s heat insulation factor. 1.0 is normal, higher values mean more resistance to heat.<br />
<br />
Note that in 1.80 and earlier writes to this property had no effect on the player ship.<br />
<br />
=== <code>homeSystem</code> ===<br />
{{Oolite-prop-added|1.79}}<br />
'''homeSystem''' : Number (read/write)<br />
The home system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.<br />
<br />
=== <code>hyperspaceSpinTime</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''hyperspaceSpinTime''' : Number (read/write)<br />
The length of the ship's hyperspace countdown.<br />
<br />
Setting this to a negative value disables the drive entirely.<br />
<br />
Note that most NPC ship jumps use <code>ship.exitSystem()</code> to make the jump, which does not have a delay. Provided this value is zero or positive, the ship will jump instantly if <code>ship.exitSystem()</code> is called. The AI must use this property elsewhere if a delay before jumping is required.<br />
<br />
=== <code>injectorBurnRate</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorBurnRate''' : Number (read/write)<br />
The rate at which the ship's injectors burn fuel in deci-LY per second. The default is 0.25.<br />
<br />
=== <code>injectorSpeedFactor</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''injectorSpeedFactor''' : Number (read/write)<br />
The multiplier to maximum speed granted to this ship when it is using injectors. The default is 7, and values must be between 1.0 and 32.0 (the torus drive's speed)<br />
<br />
=== <code>isBeacon</code> ===<br />
'''isBeacon''' : Boolean (read-only)<br />
<code>true</code> if the ship is a beacon (i.e., can show up on the [[Advanced Space Compass]] with a character indicating its identity), <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#beaconCode|beaconCode]]</code><br />
<br />
=== <code>isBoulder</code> ===<br />
'''isBoulder''' : Boolean (read/write)<br />
<code>true</code> if the ship is a boulder (i.e., has the role "boulder in its roleset)<br />
<br />
=== <code>isCargo</code> ===<br />
'''isCargo''' : Boolean (read-only)<br />
<code>true</code> if the ship is cargo (i.e., has scan_class CLASS_CARGO and contains at least one unit)<br />
<br />
=== <code>isCloaked</code> ===<br />
'''isCloaked''' : Boolean (read/write)<br />
<code>true</code> if the ship has a cloaking device which is currently active <code>false</code> otherwise. If the ship has a cloaking device and sufficient energy to use it (<code>energy > 0.75 * [[Oolite JavaScript Reference: Entity#maxEnergy|maxEnergy]]</code>), you can activate it by setting <code>isCloaked</code> to <code>true</code>.<br />
<br />
=== <code>isDerelict</code> ===<br />
'''isDerelict''' : Boolean (read-only)<br />
<code>true</code> if the ship is a derelict (i.e., the pilot has ejected from the ship, or the ship was created with the ship-key: "is_hulk")<br />
<br />
=== <code>isFleeing</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isFleeing''' : Boolean (read-only)<br />
<code>true</code> if the ship is currently fleeing combat. This may be queried for the player ship too, though the value is somewhat of a guess in that case as it's impossible to say for certain what the player is intending by their actions.<br />
<br />
=== <code>isFrangible</code> ===<br />
'''isFrangible''' : Boolean (read-only)<br />
<code>true</code> if the ship is frangible (i.e., its subentities can be destroyed separately from the main ship), <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>isJamming</code> ===<br />
'''isJamming''' : Boolean (read-only)<br />
<code>true</code> if the ship has a military scanner jammer which is currently active <code>false</code> otherwise.<br />
<br />
=== <code>isMinable</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isMinable''' : Boolean (read-only)<br />
<code>true</code> if the ship will break up usefully when hit by a mining laser, <code>false</code> otherwise. By default this is true for anything with "asteroid" or "boulder" in its role list - if you need to add anything which miners shouldn't be shooting at to those roles, give it <code>"no_boulders" = yes;</code> in its [[shipdata.plist]].<br />
<br />
=== <code>isMine</code> ===<br />
'''isMine''' : Boolean (read-only)<br />
<code>true</code> if the ship is a mine, <code>false</code> otherwise.<br />
<br />
=== <code>isMissile</code> ===<br />
'''isMissile''' : Boolean (read-only)<br />
<code>true</code> if the ship is a missile, <code>false</code> otherwise.<br />
<br />
=== <code>isPiloted</code> ===<br />
'''isPiloted''' : Boolean (read-only)<br />
<code>true</code> if the ship has a pilot on board, <code>false</code> otherwise. Generally have ships, station and escape pods pilots and have cargo, rocks, missiles or buoys no pilots.<br />
<br />
=== <code>isPirate</code> ===<br />
'''isPirate''' : Boolean (read-only)<br />
<code>true</code> if the ship is a pirate vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "pirate"</code>.<br />
<br />
=== <code>isPirateVictim</code> ===<br />
'''isPirateVictim''' : Boolean (read-only)<br />
<code>true</code> if the ship’s [[#primaryRole|primary role]] is listed in ''pirate-victim-roles.plist'', <code>false</code> otherwise. This is the same test used by the pirate AI to select victims.<br />
<br />
=== <code>isPolice</code> ===<br />
'''isPolice''' : Boolean (read-only)<br />
<code>true</code> if the ship is a police vessel, <code>false</code> otherwise. Currently equivalent to <code>[[Oolite JavaScript Reference: Entity#scanClass|scanClass]] == "CLASS_POLICE"</code>.<br />
<br />
=== <code>isRock</code> ===<br />
'''isRock''' : Boolean (read-only)<br />
<code>true</code> if the ship is a rock (i.e., has scan_class: CLASS_ROCK)<br />
<br />
=== <code>isThargoid</code> ===<br />
'''isThargoid''' : Boolean (read-only)<br />
<code>true</code> if the ship is a Thargoid vessel, <code>false</code> otherwise. Currently equivalent to <code>[[Oolite JavaScript Reference: Entity#scanClass|scanClass]] == "CLASS_THARGOID"</code>.<br />
<br />
=== <code>isTrader</code> ===<br />
'''isTrader''' : Boolean (read-only)<br />
<code>true</code> if the ship is a merchant vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "trader" || isPlayer</code>. '''Note:''' <code>[[#isPirateVictim|isPirateVictim]]</code> may be a better choice in many cases.<br />
<br />
=== <code>isTurret</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''isTurret''' : Boolean (read-only)<br />
<code>true</code> if the ship is a plasma turret sub-entity, <code>false</code> otherwise.<br />
<br />
=== <code>isWeapon</code> ===<br />
'''isWeapon''' : Boolean (read-only)<br />
<code>true</code> if the ship is a weapon, <code>false</code> otherwise. Currently equivalent to <code>[[#isMissile|isMissile]] || [[#isMine|isMine]] </code>, but new categories of weapon could be added in future.<br />
<br />
=== <code>laserHeatLevel</code>* ===<br />
{{Oolite-prop-added|1.77}}<br />
'''laserHeatLevel''' : Number (read-only, 0 to 1)<br />
The temperature of the ship's currently active weapon. Thermal cut-out is active above 0.85. For non-player ships, if their forward weapon is empty, then the temperature of the forward weapon may be the temperature of a subentity forward weapon.<br />
'''laserHeatLevelAft''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelForward''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelPort''' : Number (read-only, 0 to 1)<br />
'''laserHeatLevelStarboard''' : Number (read-only, 0 to 1)<br />
The temperature of specific laser mounts can also be queried.<br />
<br />
=== <code>lightsActive</code> ===<br />
'''lightsActive''' : Boolean (read-write)<br />
Setting this property to <code>true</code> turns on all the entity’s flashers, and setting it to <code>false</code> turns them off. Setting it sets the <code>lightsActive</code> property for all subentities, but subentities’ setting can also be manipulated separately. In addition to affecting flashers, the value can be used by shaders.<br />
<br />
Note: <code>lightsActive</code> is always <code>true</code> when a ship is spawned, although individual flashers may be off because they have <code>initially_on</code> set to false in their ''shipdata.plist'' declarations.<br />
<br />
=== <code>markedForFines</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''markedForFines''' : Boolean (read-only)<br />
<code>True</code> if the ship has been marked for fines the next time it docks at this system's main station.<br />
<br />
'''See also''' : [[#markTargetForFines|markTargetForFines()]]<br />
<br />
=== <code>maxEscorts</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxEscorts''' : Number (read/write)<br />
The maximum number of escorts this ship can have. This cannot be set lower than the number of escorts it currently has, or higher than the value of the MAX_ESCORTS constant (currently 16). There may be other reasons why a ship can have fewer escorts than the value of <code>maxEscorts</code> (for instance, ships which are escorts cannot have their own escorts)<br />
<br />
'''See also:''' <code>[[#escortGroup|escortGroup]]</code><br />
<br />
=== <code>maxPitch</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxPitch''' : Number (read-only, read/write from 1.81)<br />
The maximum pitch rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#pitch|pitch]]</code><br />
<br />
=== <code>maxRoll</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxRoll''' : Number (read-only, read/write from 1.81)<br />
The maximum roll rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#roll|roll]]</code><br />
<br />
=== <code>maxSpeed</code> ===<br />
'''maxSpeed''' : Number (read-only, read/write from 1.81)<br />
The ship’s maximum speed under normal power. Note that <code>[[#speed|speed]]</code> may exceed this when [[witch fuel injectors]] or [[hyperspeed]] are in use.<br />
<br />
'''See also:''' <code>[[#speed|speed]]</code><br />
<br />
=== <code>maxThrust</code> ===<br />
'''maxThrust''' : Number (read-only, read/write from 1.81)<br />
The ship’s maximum <code>[[#thrust|thrust]]</code>. This value is the one defined as <code>thrust</code> in ''[[Shipdata.plist#thrust|shipdata.plist]]''.<br />
<br />
=== <code>maxYaw</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''maxYaw''' : Number (read-only, read/write from 1.81)<br />
The maximum yaw rate of the ship, in radians per second.<br />
<br />
'''See also:''' <code>[[#yaw|yaw]]</code><br />
<br />
=== <code>missileCapacity</code> ===<br />
'''missileCapacity''' : Number (read-only integer)<br />
The maximum number of missiles the ship can carry.<br />
<br />
=== <code>missileLoadTime</code> ===<br />
'''missileLoadTime''' : Number (read-write nonnegative)<br />
The minimum amount of time between two missiles. The corresponding ''[[shipdata.plist]]'' key is <code>missile_load_time</code>.<br />
<br />
=== <code>missiles</code> ===<br />
'''missiles''' : Array (read-only array of [[Oolite JavaScript Reference: EquipmentInfo|EquipmentInfo]])<br />
The ship’s loaded missiles.<br />
<br />
=== <code>name</code> ===<br />
'''name''' : String (read/write, read-only for player)<br />
The name of the ship type (<code>name</code> key in [[shipdata.plist]]).<br />
<br />
''Note'': while <code>name</code> can be changed, this is discouraged (and will probably not be supported in Oolite 2.0). Use <code>[[#displayName|displayName]]</code> instead.<br />
<br />
=== <code>parcelCount</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''parcelCount''' : Number (read-only integer)<br />
The ship’s current number of parcels.<br />
<br />
=== <code>parcels</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''parcels''' : Array (read-only NSDictionary)<br />
The ship’s parcels. (For now only available for the player). Each parcel list contains the entries: <code>name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
For example, the information of the first contract can be obtained by:<br />
player.ship.parcels[0].name<br />
player.ship.parcels[0].start<br />
player.ship.parcels[0].destination<br />
player.ship.parcels[0].startName<br />
player.ship.parcels[0].destinationName<br />
player.ship.parcels[0].eta<br />
player.ship.parcels[0].etaDescription<br />
player.ship.parcels[0].fee // The final fee, paid out on successful delivery.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this parcel.<br />
<br />
=== <code>passengerCapacity</code> ===<br />
'''passengerCapacity''' : Number (read-only integer)<br />
The ship’s maximum passenger capacity.<br />
<br />
=== <code>passengerCount</code> ===<br />
'''passengerCount''' : Number (read-only integer)<br />
The ship’s current number of passengers.<br />
<br />
=== <code>passengers</code> ===<br />
'''passengers''' : Array (read-only NSDictionary)<br />
The ship’s passengers. (For now only available for the player). Each passengers list contains the entries: <code>name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer</code><br><br />
For example, the information of the first contract can be obtained by:<br />
player.ship.passengers[0].name<br />
player.ship.passengers[0].start<br />
player.ship.passengers[0].destination<br />
player.ship.passengers[0].startName<br />
player.ship.passengers[0].destinationName<br />
player.ship.passengers[0].eta<br />
player.ship.passengers[0].etaDescription<br />
player.ship.passengers[0].fee // The final fee, paid out on successful delivery.<br />
player.ship.passengers[0].premium // The advance fee, already paid on acceptance of the contract.<br />
<br />
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this passenger, and premium shows the amount the player received when the passenger boarded the ship.<br />
<br />
=== <code>pitch</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''pitch''' : Number (read-only)<br />
The rate of pitch of the ship in radians/second (positive for dive, negative for climb)<br />
<br />
=== <code>portWeapon</code> ===<br />
'''portWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped port weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code><br />
<br />
=== <code>potentialCollider</code> ===<br />
'''potentialCollider''' : [[Oolite JavaScript Reference: Entity|Entity]] (read-only)<br />
The entity the ship is currently trying not to crash into, if any.<br />
<br />
=== <code>primaryRole</code> ===<br />
'''primaryRole''' : String (read/write, read-only for player)<br />
The main role of the ship; the role for which it was created. For instance, if a ship’s ''shipdata.plist'' entry specifies the roles “pirate trader(0.5) escort”, and a ship of that type is spawned to be a trader, its <code>primaryRole</code> is <code>"trader"</code>, its <code>roles</code> is <code>["escort", "pirate", "trader"]</code> and its <code>roleWeights</code> is <code> { "escort":1, "pirate":1, "trader":0.5}</code>.<br />
<br />
'''See also:''' <code>[[#roles|roles]]</code>, <code>[[#roleWeights|roleWeights]]</code><br />
<br />
=== <code>reportAIMessages</code> ===<br />
'''reportAIMessages''' : Boolean (read/write)<br />
Debugging facility: set to <code>true</code> to dump information about AI activity to the log. <br />
<br />
=== <code>roleWeights</code> ===<br />
'''roleWeights''' : Object (read-only)<br />
The probabilities for each role in <code>[[#roles|roles]]</code>.<br />
<br />
Example:<br />
this.pirateProb = ship.roleWeights["pirate"]<br />
<br />
'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roles|roles]]</code><br />
<br />
=== <code>roles</code> ===<br />
'''roles''' : Array (read-only array of Strings)<br />
The roles of the ship. This consists of the roles specified in the ship’s ''shipdata.plist'' entry, as well as the <code>[[#primaryRole|primaryRole]]</code> if it is not among those.<br />
<br />
'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roleWeights|roleWeights]]</code>, <code>[[#hasRole|hasRole()]]</code><br />
<br />
=== <code>roll</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''roll''' : Number (read-only, read/write for stations)<br />
The rate of roll of the ship in radians/second (positive for anti-clockwise, negative for clockwise)<br />
<br />
For stations, this can be set to any value between -2 and +2 to adjust their roll rate. The default is 0.4, or the value specified by the <code>station_roll</code> key in shipdata.plist.<br />
<br />
=== <code>savedCoordinates</code> ===<br />
'''savedCoordinates''' : [[Oolite JavaScript Reference: Vector|Vector]] (read-write)<br />
The savedCoordinates of the ship in system co-ordinates. The savedCoordinates vector is only used by AI scripting to store a coordinate that can be used by other AI commands like <code>setDestinationFromCoordinates</code>. It are the same coordinates that are set by the AI command: <code>"setCoordinates: X Y Z"</code><br />
<br />
=== <code>scanDescription</code> ===<br />
{{Oolite-prop-added|1.81}}<br />
'''scanDescription''' : String (read/write)<br />
The description of the ship in the "legal status" text shown by the [[Scanner Targeting Enhancement]]. If this is null then the default text for the ship's scan class and bounty level will be shown.<br />
<br />
=== <code>scannerDisplayColor1</code> ===<br />
'''scannerDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The first of two colours used by the ship’s scanner “lollipop”. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning <code>null</code> will restore the value from [[shipdata.plist]], or the default value for the ship’s scan class.<br />
<br />
'''See also:''' <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code>, <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code><br />
<br />
=== <code>scannerDisplayColor2</code> ===<br />
'''scannerDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The second scanner colour. If both <code>scannerDisplayColor1</code> and <code>scannerDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.<br />
<br />
'''See also:''' <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code>, <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code><br />
<br />
=== <code>scannerHostileDisplayColor1</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''scannerHostileDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The first of two colours used by the ship’s scanner “lollipop” when the ship is specifically targeting the player with hostile intent. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning <code>null</code> will restore the value from [[shipdata.plist]], or the default value for the ship’s scan class.<br />
<br />
If hostile colours are set but normal colours aren't, then the normal colours will default to those for the ship's scan class. If normal colours are set but hostile colours aren't, the scanner blip will not change colour when the ship is hostile.<br />
<br />
'''See also:''' <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code>, <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code><br />
<br />
=== <code>scannerHostileDisplayColor2</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''scannerHostileDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)<br />
The second scanner colour when the ship is specifically targeting the player with hostile intent.. If both <code>scannerHostileDisplayColor1</code> and <code>scannerHostileDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.<br />
<br />
'''See also:''' <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code>, <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code><br />
<br />
=== <code>scannerRange</code> ===<br />
'''scannerRange''' : Number (read-only)<br />
The range of the ship’s scanner.<br />
<br />
=== <code>script</code> ===<br />
'''script''' : [[Oolite JavaScript Reference: Script|Script]] (read-only)<br />
The ship’s script.<br />
<br />
=== <code>scriptedMisjump</code> ===<br />
'''scriptedMisjump''' : Boolean (read/write)<br />
When <code>true</code>, the next hyperspace jump will be a misjump. The <code>scriptedMisjump</code> flag will remain <code>true</code> during the <code>shipWillExitWitchspace()</code> event handler, and will be set to <code>false</code> after the <code>shipExitedWitchspace()</code> event.<br />
<br />
=== <code>scriptedMisjumpRange</code> ===<br />
{{oolite-prop-added|1.77}}<br />
'''scriptedMisjumpRange''' : Number (read/write)<br />
If this ship misjumps, this number will be consulted to determine the length of the resulting misjump relative to the normal jump range. Setting this does not in itself force a misjump - this must occur through the usual mechanisms. Values must be greater than 0.0 and less than 1.0, and the default is 0.5 for a traditional half-way misjump. This will be reset to 0.5 at the same time as <code>[[#scriptedMisjump|scriptedMisjump]]</code> is reset to <code>false</code>.<br />
<br />
=== <code>scriptInfo</code> ===<br />
'''scriptInfo''' : Object (read-only)<br />
The contents of the <code>script_info</code> key in the ship’s ''[[shipdata.plist]]'' entry, if any. This may be any [[property list]] object, but the recommended approach is to use a dictionary whose keys have a unique prefix (such as you should be using for file names, ship names etc.). A property list dictionary is converted to a JavaScript object with properties corresponding to the dictionary’s keys. All other property list types used with Oolite have directly corresponding JavaScript types.<br><br />
When using numeric values in the scriptInfo, the JS engine is not able to detect the type reliably on all systems, so you always must explicitly convert its content to a number by using parseInt(scriptInfo.myKey) or parseFloat(scriptInfo.myKey).<br />
<br />
=== <code>shipClassName</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''shipClassName''' : String (read/write)<br />
The name of the ship class (e.g. "Python")<br />
<br />
=== <code>shipUniqueName</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''shipUniqueName''' : String (read/write)<br />
The name of this specific ship (e.g. "Sunrise of Lave")<br />
<br />
=== <code>speed</code> ===<br />
'''speed''' : Number (read-only)<br />
The ship’s current speed.<br />
<br />
'''See also:''' <code>[[#maxSpeed|maxSpeed]]</code><br />
<br />
=== <code>starboardWeapon</code> ===<br />
'''starboardWeapon''' : EquipmentType (read-only, read/write in 1.77)<br />
The currently equipped forward weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.<br />
<br />
'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code><br />
<br />
=== <code>subEntities</code> ===<br />
'''subEntities''' : Array (read-only array of Ships)<br />
The ships subentities, or <code>null</code> if it has none. Special subentities such as flashers and exhaust plumes are not included.<br />
<br />
'''See also:''' <code>[[#isFrangible|isFrangible]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>subEntityCapacity</code> ===<br />
'''subEntityCapacity''' : Number (read-only integer)<br />
The original number of subentities on the ship. <br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code><br />
<br />
=== <code>subEntityRotation</code> ===<br />
{{oolite-prop-added|1.81}}<br />
'''subEntityRotation''' : Quaternion (read/write)<br />
The subentity rotational velocity, expressed as a quaternion. This much rotation will be applied per second. Exact 180 degree rotations should not be specified, as it is not possible to determine what route to use to make that rotation. This property is ignored when set on non-subentities.<br />
<br />
=== <code>sunGlareFilter</code> ===<br />
{{oolite-prop-added|1.79}}<br />
'''sunGlareFilter''' : Number (read/write)<br />
The strength of the sun glare filter on this ship. It must be in the range 0 to 1 (0 is no filter).<br />
<br />
=== <code>target</code> ===<br />
'''target''' : Ship (read-write)<br />
The ship’s primary target, i.e. the entity it will attempt to shoot at. This value is automatically co-ordinated between a ship and its subentities.<br />
<br />
=== <code>temperature</code> ===<br />
'''temperature''' : Number (read/write)<br />
The ship’s temperature, normalized such that a temperature of 1.0 is the level at which a ship starts taking heat damage.<br />
<br />
=== <code>thrust</code> ===<br />
'''thrust''' : Number (read/write for NPCs, read-only for player before 1.81)<br />
The ship’s thrust, ranging from 0 to <code>maxThrust</code>. This value determines how fast the ship accelerates or decelerates, specified in m/s².<br />
<br />
'''See also:''' <code>[[#thrustVector|thrustVector]]</code><br />
<br />
=== <code>thrustVector</code> ===<br />
'''thrustVector''' : Vector3D (read-only)<br />
The inertialess velocity generated by the engines.<br />
<br />
'''See also:''' <code>[[#thrust|thrust]]</code>, <code>[[#velocity|velocity]]</code><br />
<br />
=== <code>trackCloseContacts</code> ===<br />
'''trackCloseContacts''' : Boolean (read/write)<br />
If true, AI events are generated for near collisions.<br />
<br />
=== <code>vectorForward</code> ===<br />
'''vectorForward''' : Vector3D (read-only)<br />
The vector pointing forwards from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorForward|vectorForward]]</code>.<br />
<br />
=== <code>vectorRight</code> ===<br />
'''vectorRight''' : Vector3D (read-only)<br />
The vector pointing right from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorRight|vectorRight]]</code>.<br />
<br />
=== <code>vectorUp</code> ===<br />
'''vectorUp''' : Vector3D (read-only)<br />
The vector pointing up from the ship (in world space for ships, relative to the parent for subentities). Equivalent to <code>ship.[[Oolite JavaScript Reference: Entity#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#vectorUp|vectorUp]]</code>.<br />
<br />
=== <code>velocity</code> ===<br />
'''velocity''' : Vector3D (read/write)<br />
The ship’s velocity.<br />
<br />
'''Note:''' A ship’s velocity consists of two components, inertial velocity and inertialess thrust. Generally, inertial velocity is zero (so <code>velocity</code> is equal to <code>[[#thrustVector|thrustVector]]</code>), but inertial impulses may be applied if a ship collides or is caught in an explosion. If inertial velocity is non-zero, the ship’s engines will work to counteract it. Changing the ship’s velocity will always apply inertial velocity, so for ships with non-zero <code>[[#maxThrust|maxThrust]]</code> the effect will be temporary.<br />
<br />
'''See also:''' <code>[[#thrustVector|thrustVector]]</code><br />
<br />
=== <code>weaponFacings</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''weaponFacings''' : Number (read-only, integer in range 0-15)<br />
The weapon facings available for the ship. The format is the same as the equivalent property in [[shipyard.plist]] or [[shipdata.plist]] - a bitmask with the following bits:<br><br />
1 - fore<br><br />
2 - aft<br><br />
4 - port<br><br />
8 - starboard<br />
<br />
=== <code>weaponPosition*</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''weaponPositionAft''' : Vector (read-only)<br />
'''weaponPositionForward''' : Vector (read-only)<br />
'''weaponPositionPort''' : Vector (read-only)<br />
'''weaponPositionStarboard''' : Vector (read-only)<br />
The position relative to the ship at which the appropriate laser beam will start. These properties do not imply that the ship has or can have any such weapon.<br />
<br />
=== <code>weaponRange</code> ===<br />
'''weaponRange''' : Number (read-only)<br />
The maximum range of the ship’s primary weapon. For the player it is the range of the weapon that fired as last, even when the view direction changed.<br><br />
Range values are: WEAPON_PLASMA_CANNON: 5000, WEAPON_PULSE_LASER: 12500, WEAPON_BEAM_LASER: 15000, WEAPON_MINING_LASER: 12500, WEAPON_THARGOID_LASER: 17500, WEAPON_MILITARY_LASER: 30000, WEAPON_NONE: 32000.<br><br />
(Turrets are secondary weapons with a maximum range of 6000)<br />
<br />
=== <code>withinStationAegis</code> ===<br />
'''withinStationAegis''' : Boolean (read-only)<br />
<code>true</code> if the ship is within the aegis of the system’s main station (i.e., no more than 51 200 game metres from the station, or twice scanner range).<br />
<br />
=== <code>yaw</code> ===<br />
{{Oolite-prop-added|1.77}}<br />
'''yaw''' : Number (read-only)<br />
The rate of yaw of the ship in radians/second (positive for right, negative for left)<br />
<br />
== Methods ==<br />
=== <code>abandonShip</code> ===<br />
function '''abandonShip'''() : Boolean<br />
Returns <code>true</code> when the ship has an escapepod. It will launch all escapeposd on board leaving the ship behind as a empty hulk. (scanClass = CLASS_CARGO). This command does nothing when no escape-pod is present.<br><br />
Pressence of an escapepod can be tested with: <code>equipmentStatus("EQ_ESCAPE_POD") == "EQUIPMENT_OK"</code><br />
<br />
=== <code>addCollisionException</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''addCollisionException'''(exception : Ship)<br />
Prevented this ship and the selected ship from colliding. See [[#collisionExceptions|collisionExceptions]] and [[#removeCollisionException|removeCollisionException]].<br />
<br />
Prevention from collision will specifically prevent the following:<br />
<br />
* the ships colliding with each other and suffering collision damage and/or momentum change<br />
* the ships receiving collision warning events if they come close to each other<br />
* if one of the ships is a station, the other ship will not be able to dock with it even if it enters a dock<br />
<br />
This has no useful effect when applied to a subentity.<br />
<br />
Adding a collision exception which already exists has no effect but will not cause an error.<br />
<br />
=== <code>addDefenseTarget</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''addDefenseTarget'''(target : Ship)<br />
Adds the target ship to this ship's list of point [[#defenseTargets|defense targets]], if it isn't already.<br />
<br />
=== <code>awardEquipment</code> ===<br />
function '''awardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Adds the given piece of equipment to the ship, if possible, returning <code>true</code> if successful and <code>false</code> otherwise.<br />
<br />
Example:<br />
ship.awardEquipment("EQ_ECM");<br />
<br />
'''See also:''' <code>[[#canAwardEquipment|canAwardEquipment()]]</code>, <code>[[#removeEquipment|removeEquipment()]]</code><br />
<br />
=== <code>canAwardEquipment</code> ===<br />
function '''canAwardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean<br />
Tests whether it is possible to add a given equipment type. This command takes the conditions for offering inside equipment.plist into account. Returns <code>true</code> if <code>[[#awardEquipment|awardEquipment()]]</code> is expected to succeed, <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#awardEquipment|awardEquipment()]]</code><br />
<br />
=== <code>becomeCascadeExplosion</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''becomeCascadeExplosion'''()<br />
This method causes the ship to explode as if it were hit by a quirium cascade.<br />
<br />
=== <code>broadcastCascadeImminent</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''broadcastCascadeImminent'''()<br />
This method causes the ship to broadcast a message to the AIs of all nearby ships warning them of an imminent cascade explosion. It is polite to call this a few seconds before calling <code>becomeCascadeExplosion</code><br />
<br />
=== <code>broadcastDistressMessage</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''broadcastDistressMessage'''()<br />
This method causes the ship to broadcast a distress message to the AIs of all nearby ships (received also by the player as a comms message). Ships receiving a distress message will often intervene in the fight, depending on their own AI and the roles of the ships already involved.<br />
<br />
=== <code>checkCourseToDestination</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''checkCourseToDestination'''()<br />
Checks the line between the ship's current position and its destination, and returns either null or an Entity (usually a planet, sun or other ship) that this ship would risk collision with if it travelled along that course.<br />
<br />
'''See also''': [[#getSafeCourseToDestination|getSafeCourseToDestination()]]<br />
<br />
=== <code>checkScanner</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''checkScanner'''([poweredOnly : Boolean]) : Array<br />
Runs a fast scanner check and returns the results. At most 32 objects within scanner range will be returned. If the <code>poweredOnly</code> parameter is present and set to true, then only powered objects will be returned (i.e. ships with a scan class other than CLASS_CARGO or CLASS_ROCK).<br />
<br />
This method is usually considerably quicker than [[Oolite_JavaScript_Reference:_System#filteredEntities|system.filteredEntities()]] and similar methods, with little loss of accuracy, though it is still advisable to cache the result for a while before re-scanning.<br />
<br />
=== <code>clearDefenseTargets</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''clearDefenseTargets'''()<br />
Clears the ship's list of point [[#defenseTargets|defense targets]].<br />
<br />
=== <code>commsMessage</code> ===<br />
function '''commsMessage'''(message : String [,target : Ship])<br />
Make the ship broadcast the specified message. Works on buoys and subentities as well as normal ships and stations. Messages are send to a maximum of 16 ships in range and always to the player when in range. When the optional target is used, the message goes only to that ship.<br />
<br />
=== <code>damageAssessment</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''damageAssessment'''() : Number<br />
Returns a number indicating the amount of damage or supply usage by this ship. Zero means that the ship is in excellent fighting condition, while higher numbers indicate increasing amounts of damage or supply shortages.<br />
<br />
=== <code>dealEnergyDamage</code>===<br />
{{oolite-method-added|1.77}}<br />
function '''dealEnergyDamage'''(damage : Number, idealRange : Number [, velocityBias : Number])<br />
Deals damage to all ships within a sphere centred on this ship. If this ship has an owner (e.g. it is a missile or a subentity) the damage will be credited to its owner. Damage is dealt according to the following formula:<br />
* Further away than MAX_SCANNER_RANGE (25.6km): deal no damage<br />
* At or closer than <code>idealRange</code>: deal <code>damage</code> plus (or minus, for receding objects) <code>velocityBias</code> damage for every 0.001LM of relative closing speed, up to a maximum of 1.0LM<br />
* Between <code>idealRange</code> and a derived maximum range: calculate the damage that would have been done at <code>idealRange</code>, and then divide it by the square of the ratio of <code>idealRange</code> and the real range (i.e inverse-square). The derived maximum range is the distance where a target with no relative closing speed would take 1 point of damage.<br />
<br />
As an example, the standard Oolite missile uses <code>dealEnergyDamage(170, 32.5, 0.25)</code>, has a maximum speed of 0.75LM, and its AI tries to detonate it 25m from its target. Some worked examples (for comparision, one energy bank can absorb 64 points of damage, and a standard shield generator can absorb 128 points of damage):<br />
* The missile is fired at a stationary asteroid. It detonates at 25m, within the ideal range, and the relative closing speed is 0.75LM. The asteroid takes 170 + (0.25 * 750) = 357.5 points of damage<br />
* The missile is fired at a Cobra Mk III, which tries to flee from and evade the missile at its top speed of 0.35LM. The missile detonates at 25m, and the evasive manoeuvres mean that it is not heading directly at the Cobra when it detonates. The relative closing speed is 0.38LM. The Cobra takes 170 + (0.25 * 380) = 265 points of damage.<br />
* An Anaconda freighter travelling at 0.2LM fires a missile at a distant Fer-de-lance. After the missile has travelled 150m away from the Anaconda, it is hit by an ECM pulse from the FDL, and detonates. The relative velocity is -0.55LM (the missile is travelling away from the Anaconda), so the damage at the ideal range would be 170 - (0.25 * 550) = 32.5. The damage is then divided by (150 / 32.5)<sup>2</sup>, so the Anaconda takes about 1.5 points of damage.<br />
* A missile fired at something else detonates 500m away from a Sidewinder. The inverse-square rule divides the damage by (500 / 32.5)<sup>2</sup>, so the base damage at this range (ignoring velocityBias) is only 0.7. The Sidewinder is therefore safely outside the blast radius, and is not considered for damage. <br />
<br />
=== <code>deployEscorts</code> ===<br />
function '''deployEscorts'''()<br />
Cause a random number (at least 1 if possible) of the ship's escorts which are not already attacking a target to attack this ship's primary target, unless this function has already been called for the current target without meanwhile being called for a different target.<br />
<br />
=== <code>dockEscorts</code> ===<br />
function '''dockEscorts'''()<br />
Dock the ship’s deployed escorts, if any.<br />
<br />
=== <code>dumpCargo</code> ===<br />
function '''dumpCargo'''([amount : Number]) : Ship<br />
Ejects one item of cargo from the ship, and returns the cargo item. Returns <code>null</code> if the ship has no cargo, anything has been ejected in the last 0.5 seconds, or if sent to the player while docked.<br />
<br />
In 1.79 or later, multiple items may be scheduled for dumping by passing the number as a parameter.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code><br />
<br />
=== <code>ejectItem</code> ===<br />
function '''ejectItem'''(role : String) : Ship<br />
Spawns a ship of role <code>role</code> immediately behind the ship, with a slight backwards velocity. (Note: an equal and opposite reaction is applied to the parent ship, so doing this with large ships is rarely useful. <code>player.ejectItem("station")</code> may seem funny, but don’t come running to me if you have someone’s eye out.) Returns the generated ship, or <code>null</code> if no ship is generated. The scanClass of the ejected item will always be CLASS_CARGO.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code><br />
<br />
=== <code>ejectSpecificItem</code> ===<br />
function '''ejectSpecificItem'''(itemKey : String) : Ship<br />
Spawns a ship with the ''shipdata.plist'' key <code>itemKey</code> immediately behind the ship, with a slight backwards velocity. The scanClass of the ejected item will always be CLASS_CARGO.<br />
<br />
'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectItem|ejectItem]]</code><br />
<br />
=== <code>enterWormhole</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''enterWormhole'''([wormhole : Wormhole])<br />
If the player has entered witchspace, but before the old system is removed from memory, this method may be used to add this ship to the contents of the specified outbound wormhole. If no parameter is given, add them to the player's wormhole.<br />
<br />
If the player is not entering witchspace, this method does nothing: the ship must fly to the wormhole in the normal way to enter it.<br />
<br />
=== <code>equipmentStatus</code> ===<br />
function '''equipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : String<br />
Tests whether the specified type of equipment is installed, and whether it is functioning. Returns one of the following strings: <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>, <code>"EQUIPMENT_UNAVAILABLE"</code> or <code>"EQUIPMENT_UNKNOWN"</code>.<br />
<br />
'''See also:''' <code>[[#setEquipmentStatus|setEquipmentStatus()]]</code><br />
<br />
=== <code>exitAI</code> ===<br />
function '''exitAI'''()<br />
Exit the current AI, restoring the previous one. Equivalent to the <code>[[AI_methods|exitAI]]:</code> AI method. May not be used on player. Will generate a warning if there are no suspended AI states.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code><br />
<br />
=== <code>exitSystem</code> ===<br />
function '''exitSystem'''([targetSystem : Number]) : Boolean<br />
Cause the ship to jump out of the system, if possible. If <code>targetSystem</code> is specified, it will attempt to jump to the specified system, otherwise a random system within range is chosen.<br />
<br />
This method can fail for various reasons, in which case it returns <code>false</code>. It always fails for the player ship.<br />
<br />
=== <code>explode</code> ===<br />
function '''explode'''()<br />
Causes the ship to explode. Works on all ships, including the main station and the player except when docked.<br />
<br />
'''See also:''' <code>[[#remove|remove()]]</code><br />
<br />
=== <code>fireECM</code> ===<br />
function '''fireECM'''()<br />
activates an ecm burst, identical as the AI command.<br />
<br />
=== <code>findNearestStation</code> ===<br />
function '''findNearestStation'''()<br />
Returns the nearest Station entity to this ship. This is quicker than manually searching <code>system.stations</code> and much quicker than using <code>system.filteredEntities()</code>.<br />
<br />
=== <code>fireMissile</code> ===<br />
function '''fireMissile'''([missile]) : Ship<br />
fireMissile() will try to fire the first available missile and will return the missile fired, or <code>null</code> if no missiles can be fired at this time. It can take the optional missile identifier parameter, to allow for a specific missile to be fired. Missiles cannot be fired if the ship hasn’t got a valid target, or if the previous missile was launched less than <code>missile_load_time</code> seconds before. If a missile type was specified, and not found on the ship, no missile will be fired.<br />
<br />
=== <code>getSafeCourseToDestination</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''getSafeCourseToDestination'''()<br />
Returns some coordinates which can be flown to as an intermediate destination to allow travel between the ship's current position and its destination without colliding with any objects on the way. Use this if <code>checkCourseToDestination</code> returns an object you are unable or unwilling to destroy to calculate a new route.<br />
<br />
'''See also''': [[#checkCourseToDestination|checkCourseToDestination()]]<br />
<br />
=== <code>getMaterials</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''getMaterials'''() : Object<br />
getMaterials() returns the ship's current materials dictionary, or if none present an empty dictionary.<br />
<br />
'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code><br />
<br />
=== <code>getShaders</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''getShaders'''() : Object<br />
getShaders() returns the ship's current shaders dictionary, or if none present an empty dictionary.<br />
<br />
'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code><br />
<br />
=== <code>hasEquipmentProviding</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''hasEquipmentProviding'''(key : String)<br />
This method returns <code>true</code> if the ship has any equipment providing the <code>key</code> equipment type, and <code>false</code> otherwise.<br />
<br />
=== <code>hasRole</code> ===<br />
function '''hasRole'''(role : String)<br />
Returns <code>true</code> if the ship has <code>role</code> among its roles, <code>false</code> otherwise.<br />
<br />
'''See also:''' <code>[[#roles|roles]]</code><br />
<br />
=== <code>markTargetForFines</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''markTargetForFines()'''<br />
If this ship is eligible to give out fines and the primary target has a bounty, mark the current primary target for fines, which will need to be paid when the ship docks. If used on a ship other than the player, of course, the fines are not particularly meaningful.<br />
<br />
=== <code>notifyGroupOfWormhole</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''notifyGroupOfWormhole()'''<br />
Tells the ship's group about a wormhole (usually the one this ship has just entered). Causes a <code>wormholeSuggested</code> event to occur in the scripts of other group members.<br />
<br />
=== <code>offerToEscort</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''offerToEscort(mother : Ship)'''<br />
Offer to escort the specified ship. The ship making the offer must have the same scan class as the mothership and must have one of the designated escort roles. After the mothership has made a decision this ship will receive either an <code>escortAccepted</code> or <code>escortRejected</code> ship script event.<br />
<br />
=== <code>perform*</code> ===<br />
Each of these functions switches the frame-by-frame behaviour of the ship to a different mode. It may not necessarily remain in that mode, however - for example, those modes which require a target will usually fall back to idle mode if the target is lost.<br />
<br />
==== <code>performAttack</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performAttack()'''<br />
Attack the current target with available weapons.<br />
<br />
==== <code>performCollect</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performCollect()'''<br />
Attempt to scoop up the current target. If the current target is not scoopable, it will be lost.<br />
<br />
==== <code>performEscort</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performEscort()'''<br />
Escort the group leader. If this ship is not an escort of the group leader, it will not receive escort position updates from that ship.<br />
<br />
==== <code>performFaceDestination</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFaceDestination()'''<br />
Come to a stop, and turn to face the current destination coordinates.<br />
<br />
==== <code>performFlee</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFlee()'''<br />
Flee from the current target, using injectors if possible, until it is out of scanner range.<br />
<br />
==== <code>performFlyToRangeFromDestination</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performFlyToRangeFromDestination()'''<br />
Fly to the current [[#destination|destination]] coordinates, stopping when the distance between the ship and those coordinates is the [[#desiredRange|desiredRange]]. If the ship is already closer to the destination coordinates than the desired range, it will move away from the coordinates.<br />
<br />
==== <code>performHold</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performHold()'''<br />
Come to a stop, and continually turn to face the current target<br />
<br />
==== <code>performIdle</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performIdle()'''<br />
Cancel any current turns to return to level flight, then move forward at current speed.<br />
<br />
==== <code>performIntercept</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performIntercept()'''<br />
Fly to intercept (i.e. ram) the current target.<br />
<br />
==== <code>performLandOnPlanet</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performLandOnPlanet()'''<br />
Land on rather than crash into the planet. This is a slow flight, so it is recommended to get close to the planet surface before activating this behaviour.<br />
<br />
==== <code>performMining</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performMining()'''<br />
Attack the current target with a mining laser. This does not count as hostile behaviour, so cannot be used except on rocks.<br />
<br />
==== <code>performScriptedAI</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performScriptedAI()'''<br />
Request flight instructions from a [[OXP_Scripted_AI|scripted AI]] callback each frame.<br />
<br />
==== <code>performScriptedAttackAI</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performScriptedAttackAI()'''<br />
Request flight instructions, including weapons fire, from a [[OXP_Scripted_AI|scripted AI]] callback each frame.<br />
<br />
==== <code>performStop</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performStop()'''<br />
Come to a complete halt<br />
<br />
==== <code>performTumble</code> ====<br />
{{oolite-method-added|1.79}}<br />
function '''performTumble()'''<br />
Come to a complete halt and rotate randomly.<br />
<br />
=== <code>reactToAIMessage</code> ===<br />
function '''reactToAIMessage'''(message : String)<br />
Immediately perform the specified handler in the ship’s current AI state.<br />
<br />
'''See also:''' <code>[[#sendAIMessage|sendAIMessage()]]</code><br />
<br />
=== <code>recallDockingInstructions</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''recallDockingInstructions'''() : Object<br />
Returns the current docking instructions as an object, and sets the destination, desired range and desired speed to match the instructions. Use this if the ship may have been interrupted while docking to ensure its flight parameters are set correctly.<br />
<br />
'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#requestDockingInstructions|requestDockingInstructions]]</code><br />
<br />
=== <code>remove</code> ===<br />
function '''remove'''([suppressDeathEvent : Boolean])<br />
Immediately removes the ship from the universe. Works on all ships except the player, including the main station.<br>It generates a [[Oolite JavaScript Reference: ship script event handlers#shipRemoved|this.shipRemoved(suppressDeathEvent)]] event. By default it will also trigger a [[Oolite JavaScript Reference: ship script event handlers#shipDied|this.shipDied()]] event, unless <code>suppressDeathEvent</code> is true.<br />
<br />
'''See also:''' <code>[[#explode|explode()]]</code><br />
<br />
=== <code>removeCollisionException</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''removeCollisionException'''(exception : Ship)<br />
Allow this ship and the selected ship to collide again. See [[#collisionExceptions|collisionExceptions]] and [[#addCollisionException|addCollisionException]].<br />
<br />
Removing a collision exception which does not exist has no effect but will not cause an error.<br />
<br />
=== <code>removeDefenseTarget</code>===<br />
{{oolite-method-added|1.79}}<br />
function '''removeDefenseTarget'''(target : Ship)<br />
Ensures that the target ship is not on this ship's list of point [[#defenseTargets|defense targets]].<br />
<br />
=== <code>removeEquipment</code> ===<br />
function '''removeEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]])<br />
Removes the given piece of equipment from the ship.<br />
This function can also be used to remove missiles (and mines). If more than one missile of the same type is found on board, only one of them will be removed.<br />
<br />
Note that in Oolite prior to 1.76.1 there was a bug which could sometimes cause the game to crash if this function was used on pylon-mounted equipment. Therefore, if you do this in your OXP, you should set (at least) 1.76.1 as the version in requires.plist<br />
<br />
Example:<br />
ship.removeEquipment("EQ_ECM");<br />
<br />
=== <code>requestDockingInstructions</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''requestDockingInstructions'''() : Object<br />
Requests the next docking instructions from the station, and returns them as an object, setting the destination, desired range and desired speed to match the instructions. Use this to get the next step in the docking sequence after completing the previous one.<br />
<br />
'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code><br />
<br />
<br />
=== <code>requestHelpFromGroup</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''requestHelpFromGroup'''()<br />
This function sends the <code>helpRequestReceived</code> event to the other ships in this ship's group and escort group, sending the name of this ship's current target as the aggressor.<br />
<br />
=== <code>restoreSubEntities</code> ===<br />
function '''restoreSubEntities'''() : Boolean<br />
Recreate all destroyed or removed subentities of the ship. Returns <code>true</code> if any subentities were added. Whether or not any subentities were added, this will also reset all subentities to their original configuration of position, orientation and other properties.<br />
<br />
'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#isFrangible|isFrangible]]</code><br />
<br />
=== <code>selectNewMissile</code> ===<br />
function '''selectNewMissile'''() : equipmentKey<br />
selectNewMissile() will automatically select a missile for a specific ship. It uses the missile_role shipdata.plist key to find out which missiles to select. As with the system populator, there's a small chance that missiles other than the missile_role specified in shipdata will be selected.<br />
e.g.<br />
this.ship.awardEquipment(this.ship.selectNewMissile())<br />
will automatically add the 'right type' of missile to a ship, i.e. one that its captain would normally choose.<br />
<br />
=== <code>sendAIMessage</code> ===<br />
function '''sendAIMessage'''(message : String)<br />
Add a message to the ship’s AI deferred message queue. Messages in the queue are handled immediately after the next periodic <code>UPDATE</code> message. Identical messages are coalesced.<br />
<br />
'''See also:''' <code>[[#reactToAIMessage|reactToAIMessage()]]</code><br />
<br />
=== <code>setAI</code> ===<br />
function '''setAI'''(AIName : String)<br />
Set the current AI, leaving the old one suspended. Equivalent to the <code>[[AI_methods|setAITo]]:</code> AI method. May not be used on player. From 1.79 onwards AI files may either be plist-based (with a .plist extension) or Javascript-based (with a .js extension).<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code><br />
<br />
=== <code>setBounty</code> ===<br />
{{oolite-method-added|1.77}}<br />
function '''setBounty'''(bounty : Number, reason : String)<br />
Sets the ship's bounty to the new value. <code>reason</code> will be sent to [[Oolite_JavaScript_Reference:_ship_script_event_handlers#shipBountyChanged|shipBountyChanged()]].<br />
<br />
'''See also:''' <code>[[#bounty|bounty]]</code><br />
<br />
=== <code>setCargo</code> ===<br />
function '''setCargo'''(commodity : String [, count : Number]) : Boolean<br />
Attempts to create <code>count</code> weight units of the commodity <code>commodity</code> for a cargo barrel. (Can not be used to set cargo for ships) When more units are defined than 1 ton, the count is reduced to one ton. It returns false when the selected commodity is unknown. If <code>count</code> is not specified, one will be assumed.<br />
<br />
=== <code>setCargoType</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setCargoType'''(commodityType : String) : Boolean<br />
Attempts to set the ship's cargo hold to contain cargo of the specified type, discarding any cargo already present. This should generally only be used immediately after a ship is spawned. Valid cargo types are:<br />
* '''SCARCE_GOODS''': goods which are likely to be rare in the current system, usually legal.<br />
* '''PLENTIFUL_GOODS''': goods which are likely to be plentiful in the current system, usually legal.<br />
* '''MEDICAL_GOODS''': narcotics (used for the Moray Medical Boat)<br />
* '''ILLEGAL_GOODS''': various goods likely to be rare in the current system, with a strong bias towards contraband<br />
* '''PIRATE_GOODS''': as ILLEGAL_GOODS, but the total amount carried will be lower<br />
This will return false if an unrecognised commodity type is used, and will throw an exception if used on a cargo pod rather than a cargo carrier. Using it on a ship like an Asp without a cargo hold is valid but pointless.<br />
<br />
=== <code>setCrew</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''setCrew'''(Object) : Boolean<br />
Sets the ship's crew to one represented by the given object (or sets the ship to uncrewed if null is given as a parameter). Returns true if this succeeds, false otherwise (if the ship is ''always'' unpiloted). The object has the same keys as [[characters.plist]], all of which are optional and will be replaced with default values if unset. They are applied in the following order:<br />
* origin system<br />
* random seed<br />
* role<br />
* the rest<br />
You can therefore set a random seed or role to get particular behaviour, and use the other keys to override it.<br />
<br />
At the moment this function only sets the first crew member (the pilot of the ship)<br />
<br />
=== <code>setEquipmentStatus</code> ===<br />
function '''setEquipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]], statusKey : String)<br />
Changes the status of the given piece of equipment from the ship. The two only valid status keys are <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>.<br />
<br />
'''Note:''' by design, this method will throw an exception if called with an equipment type that does not exist. To test whether an equipment type exists, use <code>[[Oolite JavaScript Reference: EquipmentInfo#infoForKey|EquipmentInfo.infoForKey()]]</code>, which will return <code>null</code> for undefined equipment.<br />
<br />
'''See also:''' <code>[[#equipmentStatus|equipmentStatus()]]</code><br />
<br />
=== <code>setMaterials</code> ===<br />
function '''setMaterials'''(materialDictionary : Object [, shaderDictionary : Object]) : Boolean<br />
Set the materials of the ship’s model. This works exactly like the <code>materials</code> dictionary in [[shipdata.plist]]. The optional <code>shaderDictionary</code> argument overrides <code>materialDictionary</code> if shaders are active.<br />
<br />
'''Example:'''<br />
this.ship.setMaterials({"my_ship_diffuse.png": { diffuse_map: "my_ship_damaged_diffuse.png" }});<br />
<br />
'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code><br />
<br />
=== <code>setScript</code> ===<br />
function '''setScript'''(scriptName : String)<br />
Set, or completely replace, the javascript code associated to a ship entity.<br />
<br />
=== <code>setShaders</code> ===<br />
function '''setShaders'''(shaderDictionary : Object) : Boolean<br />
Set the shader materials of the ship’s model. Equivalent to <code>[[#setMaterials|setMaterials()]]</code> with the <code>materialDictionary</code> value set to the ship’s current material dictionary.<br />
<br />
'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code><br />
<br />
=== <code>spawn</code> ===<br />
function '''spawn'''(role : String [, count : Number]) : Array<br />
Attempts to create <code>count</code> (maximum: 64) ships of role <code>role</code> close to the ship – specifically, inside the ship’s collision radius. (Since creating ships may fail, the number created may be less than <code>count</code>). The created ships are returned in an array. If <code>count</code> is not specified, one will be assumed.<br />
<br />
<code>spawn()</code> is intended for cases when a ship splits into multiple parts or drops parts. In particular, it has the following special behaviour:<br />
* The spawned ships inherit most of the temperature of the parent.<br />
* If the parent is a missile and a child has the <code>[[shipdata.plist#is_submunition|is_submunition]]</code> property, the child will be considered a missile, its target will be set to that of the parent and the child’s owner will be set to the parent.<br />
* <code>spawn()</code> does not set up escorts for the new ships, or generate witchspace effects, or do any special AI handling.<br />
<br />
=== <code>spawnOne</code> ===<br />
function '''spawnOne'''(role : String) : Ship<br />
Convenience method which calls <code>[[#spawn|spawn]](role)</code> and returns the first element of the resulting array, or <code>null</code> if <code>spawn()</code> fails.<br />
<br />
=== <code>switchAI</code> ===<br />
function '''switchAI'''(AIName : String)<br />
Set the current AI, exiting the old one. Equivalent to the <code>[[AI_methods|switchAITo]]:</code> AI method. May not be used on player.<br />
<br />
'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#exitAI|exitAI()]]</code><br />
<br />
=== <code>threatAssessment</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''threatAssessment'''(full : Boolean) : Number<br />
Returns a number indicating the relative strength of the ship. If the 'full' parameter is true, additional information will be considered as part of the assessment which would generally only be known by ships which know this ship or have seen it in combat. Otherwise, only data which could reasonably be expected to be common knowledge based on the class of the ship will be included.<br />
<br />
For example, which weapon facings are available is part of the basic assessment, but what forward laser the ship has is part of the full assessment.<br />
<br />
=== <code>throwSpark</code> ===<br />
{{oolite-method-added|1.79}}<br />
function '''throwSpark'''()<br />
Sets the ship to throw a spark as if it was seriously damaged. If this ship is already scheduled to throw a spark, this does nothing.<br />
<br />
=== <code>updateEscortFormation</code> ===<br />
function '''updateEscortFormation'''()<br />
Request that the game updates the target positions for the ship’s escorts by calling the ship’s script’s <code>coordinatesForEscortPosition()</code> method.<br />
<br />
== Static Methods ==<br />
=== <code>keys</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''keys'''() : Array<br />
Returns all dataKeys of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.<br />
var dataKeysArray = Ship.keys();<br />
<br />
=== <code>keysForRole</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''keysForRole'''(role : String) : Array<br />
Returns all dataKeys of ships defined in all [[shipdata.plist]] which contains the given role.<br />
<br />
var role = "trader";<br />
var roleKeys = Ship.keysForRole( role );<br />
log("keysForRole", role + ": " + roleKeys );<br />
<br />
=== <code>roleIsInCategory</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''roles'''(role : String, category : String) : Boolean<br />
Returns whether the role given is in a particular category as defined in [[role-categories.plist]]<br />
<br />
Ship.roleIsInCategory("trader","oolite-pirate-victims"); // true<br />
<br />
=== <code>roles</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''roles'''() : Array<br />
Returns all roles of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.<br />
<br />
var roles = Ship.roles();<br />
for( var i = 0; i < roles.length; i++ ) {<br />
var roleKeys = Ship.keysForRole( roles[i] );<br />
log("roles", i + ". "+roles[i] + ": " + roleKeys );<br />
}<br />
<br />
=== <code>shipDataForKey</code> ===<br />
{{Oolite-method-added|1.79}}<br />
function '''shipDataForKey'''(datakey : String) : Object<br />
Returns an object containing a representation of the raw [[shipdata.plist]] entry for a given data key, or null if the data key does not exist. Keys not defined in the shipdata.plist entry will not be defined in the object - they won't get their default values.<br />
<br />
Using the ship object properties is generally a better way to get this information, but this is useful if you want to find out what a ship might be like if you did add it.<br />
<br />
var shipdata = Ship.shipDataForKey("cobra3-trader");<br />
log("test",shipdata["name"]); // "Cobra Mark III"<br />
log("test",shipdata["ship_class_name"]); // undefined<br />
log("test",shipdata["ship_unique_name"]); // undefined<br />
log("test",shipdata["display_name"]); // undefined<br />
<br />
==See also==<br />
*[[Shipdata.plist]]<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_SystemInfo&diff=46789Oolite JavaScript Reference: SystemInfo2015-02-24T18:07:36Z<p>Cim: /* setProperty */ Document 1.81</p>
<hr />
<div><small>'''Prototype:''' <code>Object</code></small><br /><br />
<br />
'''<code>SystemInfo</code>''' objects provide information about a specific system. <code>SystemInfo</code>s can be retrieved for any system in the current galaxy, but not systems in other galaxies. If you keep a reference to a <code>SystemInfo</code> object after the player goes to a different galaxy, attempts to read properties of the stored <code>SystemInfo</code> will cause an exception.<br />
<br />
In interstellar space, <code>system.info</code> refers to a temporary <code>SystemInfo</code> object whose properties cannot be written to. Attempting to read properties of such a temporary <code>SystemInfo</code> after leaving interstellar space will raise an exception.<br />
<br />
== Properties ==<br />
=== <code>coordinates</code> ===<br />
'''coordinates''' : {{oojsclass|Vector3D}} (read-only)<br />
The coordinates of the system in light years. e.g. for Lave: <code>(8, 34.6, 0)</code>. The z component is always zero.<br />
<br />
The upper left corner has the coordinate <code>(0, 0, 0)</code>. Going right increases the x value while going down on the map increases the y value.<br />
<br />
'''Example:'''<br />
System.infoForSystem(galaxyNumber, 7).coordinates<br />
returns the coordinates of the system with an ID number of 7 in the current galaxy. In the first galaxy that would be the coordinates for Lave: <code>(8, 34.6, 0)</code>.<br />
<br />
=== <code>galaxyID</code> ===<br />
'''galaxyID''' : Number (read-only nonnegative integer)<br />
The ID number of the galaxy.<br />
<br />
=== <code>internalCoordinates</code> ===<br />
'''internalCoordinates''' : {{oojsclass|Vector3D}} (read-only)<br />
'''Discouraged in favour of <code>[[#coordinates|coordinates]]</code>.'''<br /><br />
The coordinate of the system in the internal coordinate system.<br />
<br />
=== <code>systemID</code> ===<br />
'''systemID''' : Number (read-only nonnegative integer)<br />
The ID number of the system.<br />
<br />
== More properties ==<br />
In addition to the properties above, you can access many other system properties, using the same keys as [[planetinfo.plist]].<br />
<br />
'''Example:'''<br />
<code>system.info.description = "This is a dull planet."</code><br />
sets the description of the current planet to “This is a dull planet.”<br />
<br />
Modified properties are permanent and are stored in saved game. Changes made by scripts override those in ''[[planetinfo.plist]]''. Set a property to <code>null</code> to restore the ''[[planetinfo.plist]]'' value, or the default.<br />
<br />
== Methods ==<br />
=== <code>distanceToSystem</code> ===<br />
function '''distanceToSystem'''(system : SystemInfo) : Number<br />
Returns the distance in light years to another <code>SystemInfo</code>.<br />
<br />
'''Example:'''<br />
System.infoForSystem(galaxyNumber, 7).distanceToSystem(System.infoForSystem(galaxyNumber, 8))<br />
If galaxyNumber is 0, this returns 92.8.<br />
<br />
=== <code>routeToSystem</code> ===<br />
function '''routeToSystem'''(system : SystemInfo [, "OPTIMIZED_BY_JUMPS" | "OPTIMIZED_BY_TIME"] ) : Object<br />
Returns a dictionary containing the route information to another <code>SystemInfo</code>. The dictionary contains the array of system IDs that belong to the <code>route</code> found, the <code>distance</code> and the <code>time</code> corresponding to said route. Takes the optional parameter <code>"OPTIMIZED_BY_JUMPS"</code> (default) or <code>"OPTIMIZED_BY_TIME"</code> to calculate least number of jumps or fastest transit time routes respectively.<br />
<br />
'''Example:'''<br />
var myRoute = System.infoForSystem(galaxyNumber, 7).routeToSystem(System.infoForSystem(galaxyNumber, 8))<br />
myRoute.route<br />
myRoute.distance<br />
myRoute.time<br />
returns:<br />
7,129,227,73,89,222,29,42,131,62,150,36,28,16,185,86,138,51,8 (the route)<br />
96.40 (distance of added jumps)<br />
530.40 (travelled time)<br />
<br />
Warning: in version 1.76 or earlier there is a bug in this method which may cause a crash if either the start or end of the route is in interstellar space (i.e. system ID -1). In later versions this simply returns null.<br />
<br />
=== <code>samplePrice</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''samplePrice'''(commodity : String) : Array<br />
Return a sample main market price in decicredits for the commodity with that key in this system. As this requires reading system information, it will only work for systems in the current galaxy. There is of course no guarantee that the price returned by this function will be anywhere near the actual price when the system is next entered.<br />
<br />
=== <code>setProperty</code> ===<br />
{{oolite-method-added|1.81}}<br />
function '''setProperty'''(key : String, value: String, layer: Number [, manifest: String])<br />
<br />
This lets you set properties with more control than provided by writing directly to <code>systemInfo.property</code>. <code>layer</code> is the layer from 0 to 3 that the change should be applied at, as in [[planetinfo.plist]]. Layer 2 is the default layer for Javascript-initiated changes, but 3 may be used for changes absolutely crucial for OXP functionality.<br />
<br />
It is also possible to make changes on behalf of a different OXP by passing the manifest ID of that OXP as the fourth parameter. Otherwise the OXP responsible for the current script execution context will be used.<br />
<br />
=== <code>systemsInRange</code> ===<br />
function '''systemsInRange'''([range : Number]) : Array<br />
Returns an array of <code>SystemInfo</code>s in range (default: 7) from the given system.<br />
<br />
'''Note:''' will not produce correct results if used in interstellar space.<br />
<br />
'''Example:'''<br />
system.info.systemsInRange(5);<br />
<br />
== Static methods ==<br />
=== <code>filteredSystems</code> ===<br />
function '''filteredSystems'''(this : Object, predicate : Function) : Array of SystemInfo<br />
A list of the <code>SystemInfo</code>s for which <code>predicate</code> returns <code>true</code>.<br />
<br />
'''Example:'''<br />
// This is the actual implementation of <code>[[#systemsInRange|systemsInRange()]]</code>.<br />
SystemInfo.prototype.systemsInRange = function systemsInRange(range) <br />
{ <br />
if (range === undefined) <br />
{ <br />
range = 7; <br />
} <br />
<br />
return SystemInfo.filteredSystems(this, function(other) <br />
{ <br />
return (other.systemID !== this.systemID) && (this.distanceToSystem(other) <= range); <br />
}); <br />
}<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_System_Populator&diff=46729Oolite System Populator2015-02-05T20:02:57Z<p>Cim: Remove 1.79 warning</p>
<hr />
<div>The Oolite System Populator has three parts:<br />
# Via [[planetinfo.plist]] populator and repopulator functions are defined. Different functions may be defined for different systems.<br />
# The populator function is called whenever a new system (or region of interstellar space) needs populating: immediately after the [[Oolite_JavaScript_Reference:_world_script_event_handlers#startUp|startUp]] world event, and immediately before the [[Oolite_JavaScript_Reference:_world_script_event_handlers#shipWillExitWitchspace|shipWillExitWitchspace]] world event. It acts like a world event itself, but does not have a fixed name. This function should use [[Oolite_JavaScript_Reference:_System#setPopulator|system.setPopulator()]] to set up system population.<br />
# The repopulator function is called every twenty seconds of [[Time_scales_in_Oolite#Game_real_time|game real time]]. This function should use functions like [[Oolite_JavaScript_Reference:_System#addGroup|system.addGroup()]] and [[Oolite_JavaScript_Reference:_Station#launchShipWithRole|station.launchShipWithRole()]] to add new ships to the system as required to replace those which have been destroyed, or for other new arrivals.<br />
<br />
== Defining populator functions ==<br />
<br />
There are three default populator and repopulator functions.<br />
* '''For normal systems''': <code>systemWillPopulate</code> and <code>systemWillRepopulate</code><br />
* '''For interstellar space''': <code>interstellarSpaceWillPopulate</code> and <code>interstellarSpaceWillRepopulate</code><br />
* '''For nova systems''': <code>novaSystemWillPopulate</code> and <code>novaSystemWillRepopulate</code><br />
<br />
OXPs which intend to add additional content to "normal" systems should define these functions in a worldscript, and use them to add to or amend the default population.<br />
<br />
OXPs which wish to "take over" a system or systems should use [[planetinfo.plist]] to set a different populator function which is unique to their worldscript(s). This then prevents normal system population, including modifications from other more generic OXPs (provided those OXPs have been written to use this new population method, of course)<br />
<br />
== The system populator function ==<br />
<br />
The system populator is a dictionary of populator definitions set by using the [[Oolite_JavaScript_Reference:_System#setPopulator|system.setPopulator()]] function. Existing definitions may be overwritten by specifying a new definition for that key, and the definitions set up so far may be read in [[Oolite_JavaScript_Reference:_System#populatorSettings|system.populatorSettings]]<br />
<br />
Each definition has the following required parameters:<br />
* '''callback''' : a function which takes a single parameter, a Vector. This function when called should then add entities to the system at or near the Vector passed to it using the standard <code>system.addShips</code> or <code>system.addGroup</code> functions.<br />
<br />
...and the following optional parameters:<br />
* '''priority''' : a number. The default is 100. Populator definitions will be run in priority order, with ties broken randomly. Values below 100 should be considered reserved for Oolite if you are using the default populator functions, and only used with an understanding of the implications.<br />
* '''location''' : a string which must either be "COORDINATES" (the default) or a region name. Region names are listed below.<br />
* '''locationSeed''' : a number. The default is zero. If this is zero, the location is picked entirely randomly within the named region. Otherwise, it is picked using a seeded random number generator, guaranteed to give the same answer every time it is used in this system (but not the same answer as in other systems). If the <code>groupCount</code> is greater than zero and a <code>locationSeed</code> is set, an appropriate number of deterministic locations within the region will be picked, always in the same order.<br />
* '''coordinates''' : this must be a valid Vector expression if <code>location</code> is "COORDINATES". It is ignored otherwise.<br />
* '''groupCount''' : a number, default 1. This is the number of times the callback function will be called. It is only really useful with <code>location</code>s other than "COORDINATES".<br />
* '''deterministic''' : a boolean, default false. If this is true (only possible when using "COORDINATES" or a non-zero <code>locationSeed</code>, and not in nova systems or interstellar space) this is a promise to Oolite that this populator function will always be called with these parameters if the player revisits this system, provided the OXP has the power to do so, and will always have the same effect when it is called. (i.e. it has not been uninstalled, had the system populator function changed under it, has its populator entries removed by another OXP, etc.). Currently secondary stations added by deterministic populators may allow the player to save and load the game. If the player saves the game at such a station, which is then not there when they reload the game, they will be returned to the main station as a safety measure.<br />
<br />
===Named regions===<br />
The following named regions exist in Oolite 1.79 or later.<br />
* '''WITCHPOINT''' : A position within scanner range of the witchpoint. In interstellar space and nova systems, all named regions are equivalent to this. Unrecognised region names will also be treated as "WITCHPOINT"<br />
* '''LANE_PS''', '''LANE_WP''', '''LANE_WS''' : A position on the space lane between the planet, sun and witchpoint, within two scanner ranges of the centre of the lane, and not within three radii of the planet or sun, or scanner range of the witchpoint.<br />
* '''LANE_WPS''' : Picks one of the lane parameters, weighted to the lengths of the three lanes.<br />
* '''STATION_AEGIS''' : A position within two scanner ranges of the main station, but not too close to the planet.<br />
* '''PLANET_ORBIT''', '''PLANET_ORBIT_HIGH''', '''PLANET_ORBIT_LOW''' : A position less than 1 radii from the main planet's surface (low orbit), between 1 and 3 radii (orbit), or between 3 and 7 radii (high orbit)<br />
* '''STAR_ORBIT''', '''STAR_ORBIT_HIGH''', '''STAR_ORBIT_LOW''' : As the planet orbits, but relative to the system's star's position and radius.<br />
* '''TRIANGLE''' : A position in the the triangle described by the sun, main planet, and witchpoint, at least three radii from the sun and planet and three scanner ranges from the witchpoint.<br />
* '''INNER_SYSTEM''', '''INNER_SYSTEM_OFFPLANE''' : A position at least as close to the sun as the planet is, but no closer than three radii. If "OFFPLANE" is not specified, the position will be close to the plane described by the sun, main planet and witchpoint.<br />
* '''OUTER_SYSTEM''', '''OUTER_SYSTEM_OFFPLANE''' : A position at least as far from the sun as the planet is, but no further than 10,000km from it. Note that coordinates in this area may take the player 15 minutes or more to reach at full torus speeds, and ships travelling at conventional speeds may take several hours or even days to reach these locations from the inner system.<br />
<br />
== The system repopulator function ==<br />
<br />
The system repopulator function will be called approximately every twenty seconds, and can be used to replace ships that have been destroyed. Generally such replacements should enter the system in a believable way - exiting witchspace near the witchpoint, by being launched from an appropriate station or the planet, or by some similar method. It is important for smooth gameplay that this function runs very quickly. If calculations are needed, run as many as possible in the populator function to save the result.</div>Cimhttps://wiki.alioth.net/index.php?title=Trade-goods.plist&diff=46727Trade-goods.plist2015-02-05T17:11:14Z<p>Cim: /* Secondary Market Modifications */ Correct property names</p>
<hr />
<div>'''Note: this page describes functionality currently only in the 1.81 development code. It may change further before being part of a stable release.'''<br />
<br />
The trade-goods.plist file replaces and extends the old [[commodities.plist]] and [[illegal_goods.plist]] files from Oolite 1.81 onwards to allow greater flexibility in trade good definitions, including defining entirely new goods.<br />
<br />
The file is a dictionary, with keys as commodity keys, and values defining the quantities, prices and other properties of those commodities.<br />
<br />
{<br />
"food" = {<br />
"name" = "[commodity-name food]";<br />
"classes" = ("oolite-consumer","oolite-edible","oolite-farming");<br />
"quantity_unit" = 0; // 0=t<br />
"peak_export" = 7; // Poor Ag<br />
"peak_import" = 0; // Rich Ind<br />
"price_average" = 50; // decicredits<br />
// fraction of average ~= 2.75 credits<br />
"price_economic" = 0.55;<br />
// fraction of average ~= 0.2 credits<br />
"price_random" = 0.04;<br />
"quantity_average" = 13.5; // gets rounded<br />
"quantity_economic" = 0.52;<br />
"quantity_random" = 0.04;<br />
"legality_export" = 0;<br />
"legality_import" = 0;<br />
"trumble_opinion" = 1.0;<br />
"sort_order" = 100;<br />
};<br />
}<br />
<br />
The following keys are accepted within a commodity definition<br />
<br />
== Property keys ==<br />
<br />
=== capacity ===<br />
The maximum amount of this good which can be held at a main station market. The default is 127 units.<br />
<br />
=== classes ===<br />
An array of good class names. Good classes can be used by secondary stations to set pricing rules for groups of goods.<br />
<br />
The following classes are defined by Oolite, with the core goods in those classes also listed. OXPs should usually add these classes as appropriate to custom trade goods they create, and may also define their own classes (which should be given an OXP-specific prefix). Some built-in classes only contain one built-in good, to allow for easier sub-typing by OXPs.<br />
<br />
* '''oolite-alien''': goods which were not made by a Cooperative species (Alien Items)<br />
* '''oolite-animalproduct''': goods which are obtained from animals but are not themselves animals (Furs)<br />
* '''oolite-business''': goods which are usually obtained for industrial or other corporate use (Computers, Machinery, Alloys, Minerals, Gold, Platinum)<br />
* '''oolite-consumer''': goods often obtained for personal use (Food, Textiles, Liquor/Wines, Luxuries, Narcotics, Furs, Gold, Platinum, Gem Stones)<br />
* '''oolite-dangerous''': goods which may be hazardous (Radioactives, Narcotics, Firearms)<br />
* '''oolite-edible''': goods which can be eaten reasonably safely (Food, Liquor/Wines)<br />
* '''oolite-farming''': goods which are produced by farming or similar agricultural processes (Food, Textiles, Liquor/Wines, Furs)<br />
* '''oolite-living''': goods which contain living creatures (Slaves)<br />
* '''oolite-luxury''': goods which are luxuries, usually a subset of oolite-consumer (Luxuries)<br />
* '''oolite-machinery''': goods which are industrial machinery (Machinery)<br />
* '''oolite-medical''': goods which may have a medical purpose (Narcotics)<br />
* '''oolite-metals''': goods which are largely or entirely made of metal (Alloys, Gold, Platinum)<br />
* '''oolite-military''': goods which are of interest to the military (Firearms, Alien Items)<br />
* '''oolite-mining''': goods which are produced by mining operations or similar extraction processes (Radioactives, Minerals, Gold, Platinum, Gem Stones)<br />
* '''oolite-rawmaterials''': goods which are raw materials needing refining to be used further (Minerals)<br />
* '''oolite-restricted''': goods which are subject to restrictions on trade (Slaves, Narcotics, Firearms)<br />
* '''oolite-salvage''': goods which are often retrieved from space battles (Slaves, Alloys)<br />
* '''oolite-shipyard''': goods used in the production of space ships (Computers, Alloys)<br />
* '''oolite-slaves''': goods which are slaves (Slaves)<br />
* '''oolite-technological''': goods requiring a high-tech process to produce (Computers, Machinery)<br />
* '''oolite-thargoid''': goods of Thargoid origin (Alien Items)<br />
* '''oolite-weapons''': goods which are weapons (Firearms)<br />
* '''oolite-wearable''': goods which are or can be used to make clothes (Textiles, Furs)<br />
<br />
=== comment ===<br />
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]<br />
<br />
=== legality_export ===<br />
This number will be multiplied by the number of units carried when leaving a main station (or another station which enforces Cooperative market laws). This value will be ORed with the player's bounty.<br />
<br />
=== legality_import ===<br />
This number will be multiplied by the number of units carried when entering a main station (or another station which enforces Cooperative market laws). This value will be ORed with the player's bounty.<br />
<br />
No core game good is illegal to import.<br />
<br />
=== market_script ===<br />
The name of a Javascript file to use as a [[Oolite_Market_Scripts|market script]] for this trade good when calculating main station quantities and prices.<br />
<br />
=== name ===<br />
A string containing the name of the trade good. This may contain []s for [[descriptions.plist]] expansion.<br />
<br />
=== peak_export ===<br />
A number from 0 to 7 identifying the economy which will give the best price for buying this good. Economies closer to this economy than the peak_import will also have below-average prices.<br />
<br />
=== peak_import ===<br />
A number from 0 to 7 identifying the economy which will give the best price for selling this good. Economies closer to this economy than the peak_export will also have above-average prices.<br />
<br />
=== price_average ===<br />
The average price of this trade good at a main system station which neither imports nor exports, in decicredits.<br />
<br />
=== price_economic ===<br />
The proportion of the price affected by the system economy. A value of 0 means that this good does not change in price depending on system economy. A value of 0.3 means that the good would be 0.7 times price_average in an ideal exporting system, and 1.3 times price_average in an ideal importing system. While values greater than 1 may be used, in general much lower values are better.<br />
<br />
=== price_random ===<br />
The proportion of the price affected by random factors. A value of 0.6 means that the actual price of the good in a system which neither imports nor exports may be between 0.4 and 1.6 times the price_average.<br />
<br />
If this value is larger than price_economic, this means that even an ideal trade run from the best exporter to the best importer is not guaranteed to make a profit.<br />
<br />
=== quantity_average ===<br />
The average quantity of this trade good at a main system station which neither imports nor exports, in decicredits. If the calculated quantity exceeds the capacity, it will be capped.<br />
<br />
=== quantity_economic ===<br />
The proportion of the quantity affected by the system economy. A value of 0 means that this good does not change in quantity depending on system economy. A value of 0.3 means that the good would be 0.7 times as frequent in an ideal importing system, and 1.3 times as frequent in an ideal exporting system. A value of 1 or greater will make the good never or rarely (depending on quantity_random) available in systems which import the good.<br />
<br />
=== quantity_random ===<br />
The proportion of the quantity affected by random factors. A value of 0.6 means that the actual quantity of the good in a system which neither imports nor exports may be between 0.4 and 1.6 times the quantity_average.<br />
<br />
If this value is greater than 1, then systems may often entirely lack this good. If this value is greater than 1 + quantity_economic, then even an ideal exporter may not have any in stock.<br />
<br />
=== quantity_unit ===<br />
The size of container one unit of this good represents. 0 = tonne; 1 = kilogram; 2 = gram. The default is zero.<br />
<br />
=== short_comment ===<br />
A string that will be displayed on the F8 commodity list screen in the optional extra column. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setShortComment()]]. As the meaning of this value will depend on the OXPs installed, it is unlikely to be useful to specify an initial value in the plist.<br />
<br />
=== sort_order ===<br />
A number positioning the item on the F8 screen when goods are sorted in the default order. The core goods have values 100 to 1700 in steps of 100.<br />
<br />
=== trumble_opinion ===<br />
How likely is a hungry trumble to consider eating this good? Goods with a value of 0 for this will never be eaten by trumbles; other goods may be eaten depending on the value of this parameter and the values for other goods on board.<br />
<br />
<br />
== Secondary Market Definitions ==<br />
<br />
Secondary market definitions are entered in the [[shipdata.plist#market_definition|market_definition]] key in shipdata.plist, which is an array of dictionaries, each defining rules which modify the prices and quantities from the main station market, and possibly adjust the market capacity and legality of the good. The following modifications are applied for each trade good, assuming no market_script is defined:<br />
<br />
# The market definition array is searched from top to bottom for the first element matching the trade good<br />
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.<br />
# Otherwise, the price and quantity modifications defined in the plist are used.<br />
<br />
=== Secondary Market Matching ===<br />
<br />
This uses the 'type' and 'name' properties. Type has three possible values<br />
<br />
* type = 'good': the good with the key in trade-goods.plist exactly matching the name property<br />
* type = 'class': any good in trade-goods.plist with an entry in its [[#classes|classes]] list exactly matching the name property<br />
* type = 'default': any good. The name property is ignored if present.<br />
<br />
'default' should generally only be used for the last entry in the market definition.<br />
<br />
=== Secondary Market Modifications ===<br />
<br />
The following keys in the chosen market definition are then used to modify the good<br />
<br />
==== capacity ====<br />
The market capacity for this good or set of goods. If omitted, the [[shipdata.plist#market_capacity|default capacity for the station]] will be used.<br />
<br />
==== legality_import, legality_export ====<br />
If present, these keys override the keys of the same name in the basic trade good definition. If omitted, the station will use the same rules as the main station, provided that [[shipdata.plist#market_monitored|its market is monitored at all]]<br />
<br />
==== price_adder, price_multiplier, price_randomiser ====<br />
These keys modify the price in the secondary market. The formula is (in decicredits):<br />
rnd = -1..1 // random number in range -1 to +1, slightly biased towards zero<br />
secondary_price = MAX(1, (primary_price + price_adder) * (price_multiplier + (price_randomiser * rnd)))<br />
As an exception, if price_adder and price_multiplier are both <= 0, then the result is always 0 regardless of price_random.<br />
<br />
==== quantity_adder, quantity_multiplier, quantity_randomiser ====<br />
These keys together with the capacity modify the quantity in the secondary market. The formula is:<br />
rnd = -1..1 // random number in range -1 to +1, slightly biased towards zero<br />
adjusted_quantity = (local_capacity / primary_capacity) * primary_quantity;<br />
secondary_quantity = (adjusted_quantity + quantity_adder) * (quantity_multiplier + (quantity_randomiser * rnd)))<br />
As an exception, if quantity_adder and quantity_multiplier are both <= 0, then the result is always 0 regardless of quantity_random.<br />
<br />
[[Category:Oolite]]<br />
[[Category:Oolite scripting]]</div>Cimhttps://wiki.alioth.net/index.php?title=Trade-goods.plist&diff=46684Trade-goods.plist2015-01-28T23:13:33Z<p>Cim: /* Secondary Market Matching */ markup fix</p>
<hr />
<div>'''Note: this page describes functionality currently only in the 1.81 development code. It may change further before being part of a stable release.'''<br />
<br />
The trade-goods.plist file replaces and extends the old [[commodities.plist]] and [[illegal_goods.plist]] files from Oolite 1.81 onwards to allow greater flexibility in trade good definitions, including defining entirely new goods.<br />
<br />
The file is a dictionary, with keys as commodity keys, and values defining the quantities, prices and other properties of those commodities.<br />
<br />
{<br />
"food" = {<br />
"name" = "[commodity-name food]";<br />
"classes" = ("oolite-consumer","oolite-edible","oolite-farming");<br />
"quantity_unit" = 0; // 0=t<br />
"peak_export" = 7; // Poor Ag<br />
"peak_import" = 0; // Rich Ind<br />
"price_average" = 50; // decicredits<br />
// fraction of average ~= 2.75 credits<br />
"price_economic" = 0.55;<br />
// fraction of average ~= 0.2 credits<br />
"price_random" = 0.04;<br />
"quantity_average" = 13.5; // gets rounded<br />
"quantity_economic" = 0.52;<br />
"quantity_random" = 0.04;<br />
"legality_export" = 0;<br />
"legality_import" = 0;<br />
"trumble_opinion" = 1.0;<br />
"sort_order" = 100;<br />
};<br />
}<br />
<br />
The following keys are accepted within a commodity definition<br />
<br />
== Property keys ==<br />
<br />
=== capacity ===<br />
The maximum amount of this good which can be held at a main station market. The default is 127 units.<br />
<br />
=== classes ===<br />
An array of good class names. Good classes can be used by secondary stations to set pricing rules for groups of goods.<br />
<br />
The following classes are defined by Oolite, with the core goods in those classes also listed. OXPs should usually add these classes as appropriate to custom trade goods they create, and may also define their own classes (which should be given an OXP-specific prefix). Some built-in classes only contain one built-in good, to allow for easier sub-typing by OXPs.<br />
<br />
* '''oolite-alien''': goods which were not made by a Cooperative species (Alien Items)<br />
* '''oolite-animalproduct''': goods which are obtained from animals but are not themselves animals (Furs)<br />
* '''oolite-business''': goods which are usually obtained for industrial or other corporate use (Computers, Machinery, Alloys, Minerals, Gold, Platinum)<br />
* '''oolite-consumer''': goods often obtained for personal use (Food, Textiles, Liquor/Wines, Luxuries, Narcotics, Furs, Gold, Platinum, Gem Stones)<br />
* '''oolite-dangerous''': goods which may be hazardous (Radioactives, Narcotics, Firearms)<br />
* '''oolite-edible''': goods which can be eaten reasonably safely (Food, Liquor/Wines)<br />
* '''oolite-farming''': goods which are produced by farming or similar agricultural processes (Food, Textiles, Liquor/Wines, Furs)<br />
* '''oolite-living''': goods which contain living creatures (Slaves)<br />
* '''oolite-luxury''': goods which are luxuries, usually a subset of oolite-consumer (Luxuries)<br />
* '''oolite-machinery''': goods which are industrial machinery (Machinery)<br />
* '''oolite-medical''': goods which may have a medical purpose (Narcotics)<br />
* '''oolite-metals''': goods which are largely or entirely made of metal (Alloys, Gold, Platinum)<br />
* '''oolite-military''': goods which are of interest to the military (Firearms, Alien Items)<br />
* '''oolite-mining''': goods which are produced by mining operations or similar extraction processes (Radioactives, Minerals, Gold, Platinum, Gem Stones)<br />
* '''oolite-rawmaterials''': goods which are raw materials needing refining to be used further (Minerals)<br />
* '''oolite-restricted''': goods which are subject to restrictions on trade (Slaves, Narcotics, Firearms)<br />
* '''oolite-salvage''': goods which are often retrieved from space battles (Slaves, Alloys)<br />
* '''oolite-shipyard''': goods used in the production of space ships (Computers, Alloys)<br />
* '''oolite-slaves''': goods which are slaves (Slaves)<br />
* '''oolite-technological''': goods requiring a high-tech process to produce (Computers, Machinery)<br />
* '''oolite-thargoid''': goods of Thargoid origin (Alien Items)<br />
* '''oolite-weapons''': goods which are weapons (Firearms)<br />
* '''oolite-wearable''': goods which are or can be used to make clothes (Textiles, Furs)<br />
<br />
=== comment ===<br />
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]<br />
<br />
=== legality_export ===<br />
This number will be multiplied by the number of units carried when leaving a main station (or another station which enforces Cooperative market laws). This value will be ORed with the player's bounty.<br />
<br />
=== legality_import ===<br />
This number will be multiplied by the number of units carried when entering a main station (or another station which enforces Cooperative market laws). This value will be ORed with the player's bounty.<br />
<br />
No core game good is illegal to import.<br />
<br />
=== market_script ===<br />
The name of a Javascript file to use as a [[Oolite_Market_Scripts|market script]] for this trade good when calculating main station quantities and prices.<br />
<br />
=== name ===<br />
A string containing the name of the trade good. This may contain []s for [[descriptions.plist]] expansion.<br />
<br />
=== peak_export ===<br />
A number from 0 to 7 identifying the economy which will give the best price for buying this good. Economies closer to this economy than the peak_import will also have below-average prices.<br />
<br />
=== peak_import ===<br />
A number from 0 to 7 identifying the economy which will give the best price for selling this good. Economies closer to this economy than the peak_export will also have above-average prices.<br />
<br />
=== price_average ===<br />
The average price of this trade good at a main system station which neither imports nor exports, in decicredits.<br />
<br />
=== price_economic ===<br />
The proportion of the price affected by the system economy. A value of 0 means that this good does not change in price depending on system economy. A value of 0.3 means that the good would be 0.7 times price_average in an ideal exporting system, and 1.3 times price_average in an ideal importing system. While values greater than 1 may be used, in general much lower values are better.<br />
<br />
=== price_random ===<br />
The proportion of the price affected by random factors. A value of 0.6 means that the actual price of the good in a system which neither imports nor exports may be between 0.4 and 1.6 times the price_average.<br />
<br />
If this value is larger than price_economic, this means that even an ideal trade run from the best exporter to the best importer is not guaranteed to make a profit.<br />
<br />
=== quantity_average ===<br />
The average quantity of this trade good at a main system station which neither imports nor exports, in decicredits. If the calculated quantity exceeds the capacity, it will be capped.<br />
<br />
=== quantity_economic ===<br />
The proportion of the quantity affected by the system economy. A value of 0 means that this good does not change in quantity depending on system economy. A value of 0.3 means that the good would be 0.7 times as frequent in an ideal importing system, and 1.3 times as frequent in an ideal exporting system. A value of 1 or greater will make the good never or rarely (depending on quantity_random) available in systems which import the good.<br />
<br />
=== quantity_random ===<br />
The proportion of the quantity affected by random factors. A value of 0.6 means that the actual quantity of the good in a system which neither imports nor exports may be between 0.4 and 1.6 times the quantity_average.<br />
<br />
If this value is greater than 1, then systems may often entirely lack this good. If this value is greater than 1 + quantity_economic, then even an ideal exporter may not have any in stock.<br />
<br />
=== quantity_unit ===<br />
The size of container one unit of this good represents. 0 = tonne; 1 = kilogram; 2 = gram. The default is zero.<br />
<br />
=== short_comment ===<br />
A string that will be displayed on the F8 commodity list screen in the optional extra column. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setShortComment()]]. As the meaning of this value will depend on the OXPs installed, it is unlikely to be useful to specify an initial value in the plist.<br />
<br />
=== sort_order ===<br />
A number positioning the item on the F8 screen when goods are sorted in the default order. The core goods have values 100 to 1700 in steps of 100.<br />
<br />
=== trumble_opinion ===<br />
How likely is a hungry trumble to consider eating this good? Goods with a value of 0 for this will never be eaten by trumbles; other goods may be eaten depending on the value of this parameter and the values for other goods on board.<br />
<br />
<br />
== Secondary Market Definitions ==<br />
<br />
Secondary market definitions are entered in the [[shipdata.plist#market_definition|market_definition]] key in shipdata.plist, which is an array of dictionaries, each defining rules which modify the prices and quantities from the main station market, and possibly adjust the market capacity and legality of the good. The following modifications are applied for each trade good, assuming no market_script is defined:<br />
<br />
# The market definition array is searched from top to bottom for the first element matching the trade good<br />
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.<br />
# Otherwise, the price and quantity modifications defined in the plist are used.<br />
<br />
=== Secondary Market Matching ===<br />
<br />
This uses the 'type' and 'name' properties. Type has three possible values<br />
<br />
* type = 'good': the good with the key in trade-goods.plist exactly matching the name property<br />
* type = 'class': any good in trade-goods.plist with an entry in its [[#classes|classes]] list exactly matching the name property<br />
* type = 'default': any good. The name property is ignored if present.<br />
<br />
'default' should generally only be used for the last entry in the market definition.<br />
<br />
=== Secondary Market Modifications ===<br />
<br />
The following keys in the chosen market definition are then used to modify the good<br />
<br />
==== capacity ====<br />
The market capacity for this good or set of goods. If omitted, the [[shipdata.plist#market_capacity|default capacity for the station]] will be used.<br />
<br />
==== legality_import, legality_export ====<br />
If present, these keys override the keys of the same name in the basic trade good definition. If omitted, the station will use the same rules as the main station, provided that [[shipdata.plist#market_monitored|its market is monitored at all]]<br />
<br />
==== price_adder, price_multiplier, price_random ====<br />
These keys modify the price in the secondary market. The formula is (in decicredits):<br />
rnd = -1..1 // random number in range -1 to +1, slightly biased towards zero<br />
secondary_price = MAX(1, (primary_price + price_adder) * (price_multiplier + (price_random * rnd)))<br />
As an exception, if price_adder and price_multiplier are both <= 0, then the result is always 0 regardless of price_random.<br />
<br />
==== quantity_adder, quantity_multiplier, quantity_random ====<br />
These keys together with the capacity modify the quantity in the secondary market. The formula is:<br />
rnd = -1..1 // random number in range -1 to +1, slightly biased towards zero<br />
adjusted_quantity = (local_capacity / primary_capacity) * primary_quantity;<br />
secondary_quantity = (adjusted_quantity + quantity_adder) * (quantity_multiplier + (quantity_random * rnd)))<br />
As an exception, if quantity_adder and quantity_multiplier are both <= 0, then the result is always 0 regardless of quantity_random.<br />
<br />
[[Category:Oolite]]<br />
[[Category:Oolite scripting]]</div>Cimhttps://wiki.alioth.net/index.php?title=Oolite_Javascript_Reference:_PriorityAI_Documentation&diff=46593Oolite Javascript Reference: PriorityAI Documentation2015-01-24T14:33:54Z<p>Cim: /* behaviourWaitHere */ 1.81</p>
<hr />
<div>This page describes the priority-based Javascript AI system, which allows more flexible behaviour than the old plist-based AIs to be written in fewer lines of code. New programmers may find [[Oolite_PriorityAI_Tutorial|the priority AI tutorial]] to be more useful as an introduction.<br />
<br />
Priority-based Javascript AI is available from Oolite 1.79 onwards.<br />
<br />
== Constructor and general functions ==<br />
<br />
==== Constructor ====<br />
'''new PriorityAIController'''(ship : Ship) : PriorityAIController<br />
Creates a priority AI and attaches it to the specified ship. Using this from anywhere other than that ship's AI script is not recommended.<br />
<br />
var ai = new worldScripts["oolite-libPriorityAI"].PriorityAIController(this.ship);<br />
<br />
=== Properties ===<br />
<br />
==== <code>ship</code> ====<br />
'''ship''' : Ship (read-only)<br />
The ship to which the priority AI is attached.<br />
<br />
=== General Methods ===<br />
<br />
Additional methods are described in later sections, sorted by purpose.<br />
<br />
==== <code>applyHandlers</code> ====<br />
function '''applyHandlers'''(handlers : Object)<br />
Deletes any existing event handlers applied to the ship's AI Script by a previous invocation of <code>applyHandlers</code>, and copies the handlers in the argument object to the AI Script. All handlers applied this way run with '<code>this</code>' equal to the PriorityAIController, not to the AI Script.<br />
<br />
==== <code>clearHandlers</code> ====<br />
function '''clearHandlers'''(handlers : Object)<br />
Deletes any existing event handlers applied to the ship's AI Script by a previous invocation of <code>applyHandlers</code>.<br />
<br />
==== <code>communicate</code> ====<br />
function '''communicate'''(key : String, params : Object, priority : Number)<br />
If the communication "key" has previously been [[#_setCommunication|defined]] for this ship's [[#setCommunicationsRole|communications role]] and [[#setCommunicationsPersonality|personality]], retrieves it, calls <code>expandDescription</code> on it, using the parameters in the object (which can either be a dictionary, or a Ship). This message may then broadcast on the public channel, depending on the priority. If the object is a Ship, it will be converted to a dictionary for expandDescription with the following parameters:<br />
* <code>oolite_entityClass</code> = <code>ship.shipClassName</code><br />
* <code>oolite_entityName</code> = <code>ship.shipUniqueName</code><br />
Other parameters may be added later to this expansion.<br />
<br />
The priority can be a number from 1 to 4<br />
# Always send this message<br />
# Send this message if no messages sent in the last 10 seconds<br />
# Send this message if no messages sent or received in the last 10 seconds<br />
# Send this message if no messages sent or received in the last 60 seconds<br />
This is used to prevent an overwhelming number of comms messages being sent. While priority 1 is necessary for messages which must be heard by the player, care must be taken to ensure by other means that they cannot be sent repeatedly.<br />
<br />
==== <code>communicationsPersonality</code> ====<br />
function '''communicationsPersonality'''() : String<br />
The current communications personality<br />
<br />
==== <code>communicationsRole</code> ====<br />
function '''communicationsRole'''() : String<br />
The current communications role<br />
<br />
==== <code>getParameter</code> ====<br />
function '''getParameter'''(key : String) : Value<br />
If a parameter with that key has previously been set, return its value. Otherwise return null. Note that the return value can be of any type, so you must be careful when setting and retrieving parameters to avoid type errors.<br />
<br />
==== <code>getWaypointGenerator</code> ====<br />
function '''getWaypointGenerator'''() : Function<br />
If a waypoint generation function has previously been set, return it.<br />
<br />
==== <code>noteCommsHeard</code> ====<br />
function '''noteCommsHeard'''()<br />
This function is used to reset the timers for [[#communicate|priority 3 and 4 communications]]. The standard event handlers will call this for you, but you may need to call it manually otherwise.<br />
<br />
==== <code>reconsiderIn</code> ====<br />
function '''reconsiderIn'''(delay : Number)<br />
Force a reconsideration of the AI's priority list ahead of schedule, if no request for sooner reconsideration has already been received. <code>delay</code> must be at least 0.1 seconds.<br />
<br />
==== <code>reconsiderNow</code> ====<br />
function '''reconsiderNow'''()<br />
Force a reconsideration of the AI's priority list ahead of schedule.<br />
<br />
==== <code>setCommunicationsRole</code> ====<br />
function '''setCommunicationsRole'''(role : String)<br />
Sets the ship's communications role to the given value. This is then used to vary the communications messages as defined by [[#_setCommunication|_setCommunication]].<br />
<br />
If personalities have previously been defined for this role, and the ship's current personality is either "generic" or not one defined for this role, then it will also select a new communications personality at this point, based on [[Oolite_JavaScript_Reference:_Ship#entityPersonality|ship.entityPersonality]]. If the "oolite_personalityMatchesLeader" parameter has been set, then this is a 0..1 chance that the ship will instead take the personality of its group leader (if this ship is the group leader, this instead is the chance it will copy its personality to group members)<br />
<br />
==== <code>setCommunicationsPersonality</code> ====<br />
function '''setCommunicationsPersonality'''(role : String)<br />
Sets the ship's communications personality to the given value. This is then used to vary the communications messages as defined by [[#_setCommunication|_setCommunication]].<br />
<br />
==== <code>setParameter</code> ====<br />
function '''setParameter'''(key : String, value : Value)<br />
Set the named parameter to the given value. Values may be of any type. To remove a parameter, use a value of null. See the [[#Parameters|Parameters]] section below for parameter keys used by the core AIs and the standard priority AI library.<br />
<br />
==== <code>setPriorities</code> ====<br />
function '''setPriorities'''(priorities : Array [, delay: Number])<br />
Set the priority list for the AI, and evaluate it. The format of the priority list is described in the next section.<br />
<br />
An optional delay parameter can be set, which will cause evaluation to start only after this many seconds. If it is unset, the AI will start after a random period between 0 and 1 seconds.<br />
<br />
==== <code>setWaypointGenerator</code> ====<br />
function '''setWaypointGenerator'''(generator : Function)<br />
Sets the AI's [[#Waypoint_Generators|Waypoint Generators]] waypoint generator function.<br />
<br />
=== Parameters ===<br />
The following parameters are used by the standard library and accessed using [[#getParameter|getParameter]] and [[#setParameter|setParameter]], but you can also define your own for custom AIs. More detailed documentation will be provided soon.<br />
<br />
As with all custom items, prefixing new parameter names with a key unique to your OXP is strongly advised.<br />
<br />
==== Flag Parameters ====<br />
Flag parameters are intended to be set in the AI initialisation routine to vary the behaviour of the AI.<br />
<br />
oolite_flag_allowPlanetaryLanding<br />
oolite_flag_autoSpreadMissiles<br />
oolite_flag_behaviourLogging<br />
oolite_flag_continueUnlikelyPursuits<br />
oolite_flag_escortsCoverRetreat<br />
oolite_flag_fightsNearHostileStations<br />
oolite_flag_fleesPreemptively<br />
oolite_flag_likesInterstellarSpace<br />
oolite_flag_listenForDistressCall<br />
oolite_flag_markOffenders<br />
oolite_flag_neverFleeToWitchspace<br />
oolite_flag_noDockingUntilDestination<br />
oolite_flag_noSpecialThargoidReaction<br />
oolite_flag_patrolStation<br />
oolite_flag_scanIgnoresUnpowered<br />
oolite_flag_selfDestructAbandonedShip<br />
oolite_flag_sendsDistressCalls<br />
oolite_flag_surrendersEarly<br />
oolite_flag_surrendersLate<br />
oolite_flag_watchForCargo<br />
oolite_flag_witchspacePursuit<br />
<br />
==== Other parameters ====<br />
These parameters are used for storage of long-term state that may need to be kept between runs of the priority tree. In general, Configuration and Response functions set them, and Condition, Behaviour and Response functions read them, but this is only a guideline. Implementors of custom functions may need to get or set these parameters for proper interaction with built-in functions used by the same AI.<br />
<br />
oolite_cargoDropped<br />
oolite_cascadeDetected<br />
oolite_distressAggressor<br />
oolite_distressSender<br />
oolite_distressTimestamp<br />
oolite_dockingStation<br />
oolite_escortRole<br />
oolite_friendlyRoles<br />
oolite_groupPower<br />
oolite_interceptCoordinates<br />
oolite_interceptTarget<br />
oolite_lastAssist<br />
oolite_lastFleeing<br />
oolite_lastPirateVictim<br />
oolite_leaderRole<br />
oolite_personalityMatchesLeader<br />
oolite_pirateLurk<br />
oolite_playerFriendlyFireAlready<br />
oolite_rememberedTarget<br />
oolite_scanResults<br />
oolite_scanResultSpecific<br />
oolite_selectedPlanet<br />
oolite_selectedStation<br />
oolite_stationPatrolRole<br />
oolite_waypoint<br />
oolite_waypointRange<br />
oolite_waypoints<br />
oolite_witchspaceDestination<br />
oolite_witchspaceEntry<br />
oolite_witchspaceWormhole<br />
<br />
== Writing a priority list ==<br />
<br />
The priority list is the core of the priority AI. The list will be reevaluated periodically - either timed, or when events occur - and on each reevaluation it will be searched from top to bottom. When a valid priority is found, searching will stop, and that priority will be executed.<br />
<br />
If the parameter "oolite_flag_behaviourLogging" is set with [[#setParameter|setParameter]] then verbose information will be written to the log file regarding the processing of the priority list. It is generally advisable to use the debug console to do this for one ship at a time, rather than setting it generally!<br />
<br />
=== Basic structure ===<br />
<br />
The priority list is an array of objects. Each object contains a set<br />
of keys and values. The keys are considered in the<br />
following order and are all optional.<br />
* '''preconfiguration''': function run unconditionally if this element of the list is reached.<br />
* '''condition''': function run unconditionally if this element of the list is reached. If it returns false, the remainder of the object is ignored, and consideration moves to the next list element.<br />
* '''notcondition''': function run unconditionally if this element of the list is reached. If it returns true, the remainder of the object is ignored, and consideration moves to the next list element.<br />
If neither '''condition''' nor '''notcondition''' are set, this is treated as if a condition was set and was true.<br />
* '''configuration''': function run if conditions allow<br />
* '''behaviour''': function run if conditions allow. If this exists, no further elements of the priority list will be considered.<br />
* '''reconsider''': A number. If a behaviour is executed, the priority list will next be reconsidered in this many seconds. If this value is absent the priority list will only be considered if an event causes it.<br />
* '''truebranch''': a priority list array. If there was no behaviour, but the conditions allow one to be run, the truebranch will be evaluated as a priority list. If the truebranch causes a behaviour to be executed, consideration will end here. If the truebranch reaches its end without executing a behaviour, consideration will continue with the next element of the main priority list.<br />
* '''falsebranch''': a priority list array. This will be executed if the the conditions caused the previous four elements to be skipped.<br />
<br />
If evaluation reaches the end of the main priority list without finding a behaviour to execute, an error will be noted in the log. In general the last element of the main priority list should always be unconditional (or have a truebranch and a falsebranch, both of which have an unconditional last element).<br />
<br />
Example of simple behaviour: (from thargoid AI)<br />
{<br />
preconfiguration: ai.configurationCheckScanner,<br />
condition: ai.conditionScannerContainsNonThargoid,<br />
configuration: ai.configurationAcquireScannedTarget,<br />
behaviour: ai.behaviourDestroyCurrentTarget,<br />
reconsider: 1<br />
},<br />
<br />
Example of branch usage: (from police AI)<br />
{<br />
/* The group leader leads the patrol */<br />
condition: ai.conditionIsGroupLeader,<br />
truebranch: [<br />
/* Nothing interesting here. Patrol for a bit */<br />
{<br />
condition: ai.conditionHasWaypoint,<br />
configuration: ai.configurationSetDestinationToWaypoint,<br />
behaviour: ai.behaviourApproachDestination,<br />
reconsider: 30<br />
},<br />
/* No patrol route set up. Make one */<br />
{<br />
configuration: ai.configurationSetWaypoint,<br />
behaviour: ai.behaviourApproachDestination,<br />
reconsider: 30<br />
}<br />
],<br />
/* Other ships in the group will set themselves up<br />
* as escorts if possible, or looser followers if<br />
* not */<br />
falsebranch: [<br />
{<br />
preconfiguration: ai.configurationEscortGroupLeader,<br />
condition: ai.conditionIsEscorting,<br />
behaviour: ai.behaviourEscortMothership,<br />
reconsider: 30<br />
},<br />
/* if we can't set up as an escort */<br />
{<br />
behaviour: ai.behaviourFollowGroupLeader,<br />
reconsider: 15<br />
}<br />
]<br />
}<br />
<br />
The AI Library provides a selection of standard condition,<br />
configuration and behaviour functions for us in AIs, but you can also<br />
write your own.<br />
/* Ship is unstable and may explode under stress */<br />
{<br />
condition: function()<br />
{<br />
return Math.random() < 0.01; // 1% chance per evaluation<br />
} <br />
behaviour: function()<br />
{<br />
this.ship.explode();<br />
}<br />
}<br />
<br />
=== Evaluation context ===<br />
<br />
All condition, configuration and behaviour functions are evaluated in the context of the AI object. The '<code>this</code>' variable when one of these functions is run therefore points to the priority AI, '''not''' to the AI Script.<br />
<br />
Note that <code>this.ship</code> is defined and will be equivalent to the this.ship seen by the AI Script. However, if you wish to access properties of the AI Script you must use <code>this.ship.AIScript.''property''</code>. Properties and methods of the priority AI may be accessed directly, e.g. <code>[[#allied|this.allied]](this.ship,this.ship.target)</code>.<br />
<br />
<br />
== Behaviour functions ==<br />
<br />
Behaviour functions determine what the ship will do next. They<br />
generally begin a particular behaviour, and set up event handlers<br />
(generally aided by the response templates) to allow interruption or<br />
modification of that behaviour should anything interesting happen.<br />
<br />
Behaviour functions take no arguments and return nothing.<br />
<br />
=== General behaviours ===<br />
<br />
Behaviours intended for ships in general. These mostly use <code>responsesAddStandard</code>, and occasionally add others.<br />
<br />
==== <code>behaviourApproachDestination</code> ====<br />
function '''behaviourApproachDestination'''()<br />
Travels from the current position to within <code>desiredRange</code> of <code>destination</code>, avoiding obstacles on the way. <br />
<br />
If a waypoint is set in the parameters "oolite_waypoint" and "oolite_waypointRange", it will clear these parameters if when it reaches its destination it is sufficiently close to the waypoint. If the parameter "oolite_flag_patrolStation" is set, and its group leader is a station, it will report in to the station upon reaching the waypoint.<br />
<br />
Temporary waypoints needed to avoid obstacles will be stored in the<br />
"oolite_waypoints" parameter.<br />
<br />
==== <code>behaviourAssassinateCurrentTarget</code> ====<br />
function '''behaviourAssassinateCurrentTarget'''()<br />
This behaviour attacks the current target, only stopping when interrupted or when the target is destroyed. It will potentially send both "oolite_beginningAssassination" and "oolite_beginningFight" communications messages (though if the former is defined, the latter will not be sent due to the communications priority system). This is otherwise identical in behaviour to [[#behaviourCommenceAttackOnCurrentTarget|behaviourCommenceAttackOnCurrentTarget]]<br />
<br />
==== <code>behaviourAvoidCascadeExplosion</code> ====<br />
function '''behaviourAvoidCascadeExplosion'''()<br />
Fly, using injectors if available, to a safe distance from any nearby quirium cascades (or active mines)<br />
<br />
==== <code>behaviourBecomeInactiveThargon</code> ====<br />
function '''behaviourBecomeInactiveThargon'''()<br />
This behaviour is intended to deactivate thargons and should generally only be used for that purpose. It changes the scan class to CLASS_CARGO, clears the ship's targeting information, brings it to a stop, removes it from its ship groups, and removes it from nearby NPCs targeting systems (it can be retargeted). Unlike the equivalent plist AI command, it does not remove it as a player target.<br />
<br />
==== <code>behaviourCollectSalvage</code> ====<br />
function '''behaviourCollectSalvage'''()<br />
This behaviour attempts to scoop the current target. If it is successful, the "oolite_cargoDropped" parameter recording the number of seen cargo pods will be cleared.<br />
<br />
==== <code>behaviourCommenceAttackOnCurrentTarget</code> ====<br />
function '''behaviourCommenceAttackOnCurrentTarget'''()<br />
This behaviour attacks the current target, only stopping when interrupted or when the target is destroyed. Unlike the <code>behaviourDestroyCurrentTarget</code> behaviour, it may first send the "[[#oolite_beginningFight|oolite_beginningFight]]" communications message, so should only be used when starting a fight with a new target/group - not when in the middle of a fight.<br />
<br />
==== <code>behaviourDestroyCurrentTarget</code> ====<br />
function '''behaviourDestroyCurrentTarget'''()<br />
This behaviour attacks the current target, only stopping when interrupted or when the target is destroyed.<br />
<br />
==== <code>behaviourDockWithStation</code> ====<br />
function '''behaviourDockWithStation'''()<br />
This behaviour docks with the station specified in the parameter "oolite_dockingStation". If the target refuses docking or the ship is too big to dock, the parameter will be cleared.<br />
<br />
==== <code>behaviourEnterWitchspace</code> ====<br />
function '''behaviourEnterWitchspace'''()<br />
This behaviour attempts to enter witchspace. It can do this in several ways:<br />
* If the parameter "oolite_witchspaceWormhole" is set to an active wormhole, it will try to fly to and use that wormhole.<br />
* If the parameter "oolite_witchspaceDestination" is set, then it will try to jump to that destination using its own drive. It will wait for its escorts to be launched, and will start spinning up this drive. Calling this behaviour again after 15 seconds will cause it to jump out.<br />
* Otherwise, it will wait for a wormhole to be suggested by another member of its group, or for the player to create one.<br />
<br />
==== <code>behaviourEscortMothership</code> ====<br />
function '''behaviourEscortMothership'''()<br />
This behaviour performs non-combat escorting of the ship's group leader, in the formation requested by the lead ship.<br />
<br />
==== <code>behaviourFineCurrentTarget</code> ====<br />
function '''behaviourFineCurrentTarget'''()<br />
If the ship has scan class "CLASS_POLICE" and a current target, mark that target for fines when it next docks.<br />
<br />
==== <code>behaviourFleeCombat</code> ====<br />
function '''behaviourFleeCombat'''()<br />
The ship will flee from hostility, in the following order:<br />
* Cascade explosions (coordinates from the parameter "oolite_cascadeDetected")<br />
* Its current target, if it can see it<br />
* Its defense targets, if it can see them<br />
<br />
<br />
==== <code>behaviourFollowCurrentTarget</code> ====<br />
function '''behaviourFollowCurrentTarget'''()<br />
The ship will follow the current target, including through a witchspace jump if necessary, and will additionally [[#conditionHasRememberedTarget|remember]] the target.<br />
<br />
==== <code>behaviourFollowGroupLeader</code> ====<br />
function '''behaviourFollowGroupLeader'''()<br />
The ship will follow the group leader if there is one, attempting to remain within a few kilometres of it.<br />
<br />
==== <code>behaviourGuardTarget</code> ====<br />
function '''behaviourGuardTarget'''()<br />
The ship will fly to within a few kilometres of its current target. Similar to <code>behaviourFollowCurrentTarget</code> but will not follow the target into witchspace and will not remember that it was doing so if distracted.<br />
<br />
==== <code>behaviourJoinTargetGroup</code> ====<br />
function '''behaviourJoinTargetGroup'''()<br />
The ship will add itself to its target's ship group. You should previously have used appropriate condition tests to check that this is appropriate behaviour.<br />
<br />
==== <code>behaviourLandOnPlanet</code> ====<br />
function '''behaviourLandOnPlanet'''()<br />
Lands on the nearest planet. Unlike most behaviours, this one does not include the standard responses, so you should generally wait until the ship is only a few hundred metres above the surface before using it.<br />
<br />
==== <code>behaviourLeaveVicinityOfDestination</code> ====<br />
function '''behaviourLeaveVicinityOfDestination'''()<br />
Moves outside scanner range of the current destination coordinates.<br />
<br />
==== <code>behaviourLeaveVicinityOfTarget</code> ====<br />
function '''behaviourLeaveVicinityOfTarget'''()<br />
Moves outside scanner range of the current target. Unlike fleeing, this does not use fuel injectors if they are fitted, and does not cause the ship to appear hostile to its target.<br />
<br />
==== <code>behaviourMineTarget</code> ====<br />
function '''behaviourMineTarget'''()<br />
Attacks the current target with a mining laser to break it into splinters. If the current target is not a rock, this behaviour will be cancelled and the target will be lost.<br />
<br />
==== <code>behaviourOfferToEscort</code> ====<br />
function '''behaviourOfferToEscort'''()<br />
Offers to escort the ship identified by the parameter "oolite_scanResultSpecific". Unless this parameter has been set by the scanner condition [[#conditionScannerContainsShipNeedingEscort|conditionScannerContainsShipNeedingEscort]] this is extremely likely to fail.<br />
<br />
To be accepted as an escort, the ship must have a primary role in the <code>oolite-escorts</code> [[role-categories.plist|role category]].<br />
<br />
==== <code>behaviourPayOffPirates</code> ====<br />
function '''behaviourPayOffPirates'''()<br />
If a pirate demand to dump cargo exists, dump that many cargo canisters (or all of them, if fewer), and then switch to [[#behaviourFleeCombat|behaviourFleeCombat]]<br />
<br />
==== <code>behaviourReconsider</code> ====<br />
function '''behaviourReconsider'''()<br />
Does nothing except schedule a re-evaluation of the priority list.<br />
<br />
==== <code>behaviourRejoinMothership</code> ====<br />
function '''behaviourRejoinMothership'''()<br />
This behaviour flies to rejoin the mothership, and then escorts it as in [[#behaviourEscortMothership|behaviourEscortMothership]].<br />
<br />
==== <code>behaviourRepelCurrentTarget</code> ====<br />
function '''behaviourRepelCurrentTarget'''()<br />
This behaviour attacks the current target, but will break off the attack (and ask its escorts to do the same) if the target starts fleeing.<br />
<br />
==== <code>behaviourRespondToDistressCall</code> ====<br />
function '''behaviourRespondToDistressCall'''()<br />
If the ship has a valid distress call represented by the parameters "oolite_distressAggressor" and "oolite_distressSender" it will attack the aggressor if it can see it. Otherwise it will fly (with injectors if available) to near the sender, attempting to locate the aggressor.<br />
<br />
If the aggressor has a lower bounty than the sender, then the ship will assume that the distress call is "unjust", and attack the sender instead.<br />
<br />
==== <code>behaviourRobTarget</code> ====<br />
function '''behaviourRobTarget'''()<br />
If an existing group demand for cargo is in effect, attack the current target in the hope that it meets it. Demands are stored with the group leader if possible.<br />
<br />
If there is no existing demand for cargo, create one based on the cargo capacity of the target ship, the current system government, the cargo capacity of the group, and other factors.<br />
<br />
==== <code>behaviourSunskim</code> ====<br />
function '''behaviourSunskim'''()<br />
Fly along until fuel tanks are full. In general, this behaviour should not be started until sunskimming height is reached (test with [[#conditionReadyToSunskim|conditionReadyToSunskim]]), and [[#configurationSetDestinationToSunskimEnd|configurationSetDestinationToSunskimEnd]] should be used to set a safe sunskimming direction.<br />
<br />
==== <code>behaviourTumble</code> ====<br />
function '''behaviourTumble'''()<br />
Start tumbling. Unlike most behaviours, this one does not include the standard responses, so you will need to manually request a reconsideration of priorities if one is needed.<br />
<br />
==== <code>behaviourWaitHere</code> ====<br />
{{oolite-method-added|1.81}}<br />
function '''behaviourWaitHere'''()<br />
Stop at (or close to) the current location, and wait for something to happen.<br />
<br />
=== Missile behaviours ===<br />
<br />
Missile behaviours use <code>responsesAddMissile</code>. More discussion of setting missile parameters, ECM response, and detonation can be found there.<br />
<br />
==== <code>behaviourMissileInterceptCoordinates</code> ====<br />
function '''behaviourMissileInterceptCoordinates'''()<br />
Close to the desired missile range (default 25m, or specified by the <code>oolite_missile_proximity</code> key in script info), detonating when reached. The coordinates to close in on are specified in the "oolite_interceptCoordinates". This is used to track missile targets which cloak.<br />
<br />
==== <code>behaviourMissileInterceptTarget</code> ====<br />
function '''behaviourMissileInterceptTarget'''()<br />
Close to the desired missile range (default 25m, or specified by the <code>oolite_missile_proximity</code> key in script info), detonating when reached.<br />
<br />
==== <code>behaviourMissileSelfDestruct</code> ====<br />
function '''behaviourMissileSelfDestruct'''()<br />
Destroys the missile without detonating the payload.<br />
<br />
<br />
=== Station behaviours ===<br />
<br />
Station behaviours use <code>responsesAddStation</code> to set up their general handlers, as most standard behaviours are unnecessary or unhelpful for a stationary station.<br />
<br />
==== <code>behaviourStationLaunchDefenseShips</code> ====<br />
function '''behaviourStationLaunchDefenseShips'''()<br />
If the station has a target and the target is aggressive, launches a defense ship if any remain, increases the alert condition to Red, and requests a group attack on the target. Otherwise does nothing.<br />
<br />
==== <code>behaviourStationLaunchMiner</code> ====<br />
function '''behaviourStationLaunchMiner'''()<br />
If the station does not currently have a miner in its ship group, launches one. Also reduces the alert condition by one step.<br />
<br />
==== <code>behaviourStationLaunchPatrol</code> ====<br />
function '''behaviourStationLaunchPatrol'''()<br />
If the station does not currently have a ship in its ship group with the primary role equal to the parameter "oolite_stationPatrolRole", launches one. Also reduces the alert condition by one step.<br />
<br />
==== <code>behaviourStationLaunchSalvager</code> ====<br />
function '''behaviourStationLaunchMiner'''()<br />
Launches a salvager. Also reduces the alert condition by one step.<br />
<br />
==== <code>behaviourStationManageTraffic</code> ====<br />
function '''behaviourStationManageTraffic'''()<br />
The station idles. If the system repopulator has requested launches that this station can fulfil, it may launch a ship.<br />
<br />
==== <code>behaviourStationRespondToDistressCall</code> ====<br />
function '''behaviourStationRespondToDistressCall'''()<br />
Locates the aggressor and sender in the same way as [[#behaviourRespondToDistressCall|behaviourRespondToDistressCall]. If the aggressor is not visible, does nothing, otherwise sets the aggressor as a target, increases alert condition to Red, and launches a defense ship to attack the aggressor.<br />
<br />
== Condition functions ==<br />
<br />
Condition functions are used to determine whether to execute a<br />
priority AI behaviour. They take no arguments and return a Boolean.<br />
<br />
=== Combat conditions ===<br />
<br />
Conditions related to the ship's performance in combat.<br />
<br />
==== <code>conditionCascadeDetected</code> ====<br />
function '''conditionCascadeDetected'''() : Boolean<br />
Returns true if a cascade explosion has been detected recently (as given by the parameter "oolite_cascadeDetected" containing the explosion coordinates).<br />
<br />
==== <code>conditionCombatOdds*</code> ====<br />
function '''conditionCombatOddsTerrible'''() : Boolean<br />
function '''conditionCombatOddsBad'''() : Boolean<br />
function '''conditionCombatOddsGood'''() : Boolean<br />
function '''conditionCombatOddsExcellent'''() : Boolean<br />
These functions return true if the perceived odds of this ship's group winning a fight against the target ship's group can reasonably be described with the appropriate description. "Good" and "Excellent" require the odds to be better than a particular threshold (so Excellent odds are always also Good), while "Bad" and "Terrible" require the odds to be worse than that threshold.<br />
<br />
==== <code>conditionGroupAttritionReached</code> ====<br />
function '''conditionGroupAttritionReached'''() : Boolean<br />
This condition is true if the ship is in a group and that group has lost more than a quarter of its initial ships.<br />
<br />
==== <code>conditionGroupSuppliesLow</code> ====<br />
function '''conditionGroupSuppliesLow'''() : Boolean<br />
This condition is true if the ship's group is running out of consumables such as missiles or fuel, or has several damaged ships.<br />
<br />
==== <code>conditionInCombat</code> ====<br />
function '''conditionInCombat'''() : Boolean<br />
The ship is currently attacking other ships, or a ship in its group or one of its escorts is.<br />
<br />
==== <code>conditionInCombatWithHostiles</code> ====<br />
function '''conditionInCombat'''() : Boolean<br />
The ship is currently attacking other ships, or a ship in its group or one of its escorts is. Additionally, at least one of the targets of those ships is itself attacking (though not necessarily attacking anything from this ship's group)<br />
<br />
==== <code>conditionLosingCombat</code> ====<br />
function '''conditionLosingCombat'''() : Boolean<br />
The ship is in combat, but is losing. The exact definition of "losing" may vary, and is intended to account for the overall tactical situation.<br />
<br />
==== <code>conditionMothershipInCombat</code> ====<br />
function '''conditionMothershipInCombat'''() : Boolean<br />
This ship's group leader is attacking and/or being attacked. Other ships in the group are not considered. This ship must be able to see its leader's target.<br />
<br />
==== <code>conditionMothershipIsAttacking</code> ====<br />
function '''conditionMothershipIsAttacking'''() : Boolean<br />
This ship's group leader is attacking a target. This ship must be able to see its leader's target.<br />
<br />
==== <code>conditionMothershipIsAttackingHostileTarget</code> ====<br />
function '''conditionMothershipIsAttacking'''() : Boolean<br />
This ship's group leader is attacking a target which is itself attacking something. This ship must be able to see its leader's target.<br />
<br />
==== <code>conditionMothershipUnderAttack</code> ====<br />
function '''conditionMothershipUnderAttack'''() : Boolean<br />
This ship's group leader is currently being targeted. This ship must be able to see the attacker.<br />
<br />
==== <code>conditionSuppliesLow</code> ====<br />
function '''conditionSuppliesLow'''() : Boolean<br />
This condition is true if this ship is personally running out of consumables such as missiles or fuel, or is damaged. This is effectively a wrapper around <code>ship.damageAssessment()</code>.<br />
<br />
=== Navigation conditions ===<br />
<br />
Conditions related to the ship's surroundings and navigation through the system.<br />
<br />
==== <code>conditionCanWitchspaceOnRoute</code> ====<br />
function '''conditionCanWitchspaceOnRoute'''() : Boolean<br />
The ship has a witchspace drive, a witchspace route, and the next system on its [[#setWitchspaceRouteTowitchspace|route]] is within range with the current fuel supply.<br />
<br />
==== <code>conditionCanWitchspaceOut</code> ====<br />
function '''conditionCanWitchspaceOut'''() : Boolean<br />
The ship has a witchspace drive, and at least one other system is within range with the current fuel supply.<br />
<br />
==== <code>conditionFriendlyStationExists</code> ====<br />
function '''conditionFriendlyStationExists'''() : Boolean<br />
There is at least one friendly station in the system.<br />
<br />
==== <code>conditionFriendlyStationNearby</code> ====<br />
function '''conditionFriendlyStationNearby'''() : Boolean<br />
There is at least one friendly station within scanner range<br />
<br />
==== <code>conditionGroupIsSeparated</code> ====<br />
function '''conditionGroupIsSeparated'''() : Boolean<br />
The ship is in a group and has a group leader, and is out of scanner range of that leader (or out of 2x scanner range if the leader is a station)<br />
<br />
==== <code>conditionHasSelectedPlanet</code> ====<br />
function '''conditionHasSelectedPlanet'''() : Boolean<br />
The ship has a valid planet in the "oolite_selectedPlanet" parameter.<br />
<br />
==== <code>conditionHasSelectedStation</code> ====<br />
function '''conditionHasSelectedStation'''() : Boolean<br />
The ship has a valid station in the "oolite_selectedStation" parameter.<br />
<br />
==== <code>conditionHomeStationExists</code> ====<br />
function '''conditionHomeStationExists'''() : Boolean<br />
The ship's home station still exists<br />
<br />
==== <code>conditionHomeStationNearby</code> ====<br />
function '''conditionHomeStationNearby'''() : Boolean<br />
The ship's home station is within scanner range.<br />
<br />
==== <code>conditionHostileStationNearby</code> ====<br />
function '''conditionHostileStationNearby'''() : Boolean<br />
There is at least one hostile station within scanner range<br />
<br />
==== <code>conditionInInterstellarSpace</code> ====<br />
function '''conditionInInterstellarSpace'''() : Boolean<br />
The ship is currently in interstellar space.<br />
<br />
==== <code>conditionMainPlanetNearby</code> ====<br />
function '''conditionMainPlanetNearby'''() : Boolean<br />
The ship is within 3 radii of the surface of the main planet<br />
<br />
==== <code>conditionNearDestination</code> ====<br />
function '''conditionNearDestination'''() : Boolean<br />
The ship is closer than the desired range to its destination<br />
<br />
==== <code>conditionPlayerNearby</code> ====<br />
function '''conditionPlayerNearby'''() : Boolean<br />
The player's ship is within scanner range.<br />
<br />
==== <code>conditionReadyToSunskim</code> ====<br />
function '''conditionReadyToSunskim'''() : Boolean<br />
The ship is close enough to the sun to scoop fuel.<br />
<br />
==== <code>conditionSelectedStationNearby</code> ====<br />
function '''conditionSelectedStationNearby'''() : Boolean<br />
The ship has a selected station in the "oolite_selectedStation" parameter, and it is within scanner range.<br />
<br />
==== <code>conditionSelectedStationNearMainPlanet</code> ====<br />
function '''conditionSelectedStationNearMainPlanet'''() : Boolean<br />
The ship has a selected station in the "oolite_selectedStation" parameter, and it is within 3 radii of the surface of the main planet.<br />
<br />
==== <code>conditionStationNearby</code> ====<br />
function '''conditionStationNearby'''() : Boolean<br />
There is a station within scanner range.<br />
<br />
==== <code>conditionSunskimPossible</code> ====<br />
function '''conditionSunskimPossible'''() : Boolean<br />
There is a sun, it's not going nova, it hasn't gone nova, the ship has a non-full fuel tank and fuel scoops, and the ship has sufficient heat insulation to skim safely.<br />
<br />
==== <code>conditionWormholeNearby</code> ====<br />
function '''conditionWormholeNearby'''() : Boolean<br />
There is an entry wormhole within scanner range.<br />
<br />
=== Piracy-related conditions ===<br />
<br />
Conditions involved in piratical activities.<br />
<br />
==== <code>conditionCargoDemandsMet</code> ====<br />
function '''conditionCargoDemandsMet'''() : Boolean<br />
Since this ship (or an ally) made a cargo demand, this ship has seen enough cargo dropped to meet that demand.<br />
<br />
==== <code>conditionGroupHasEnoughLoot</code> ====<br />
function '''conditionGroupHasEnoughLoot'''() : Boolean<br />
The group this ship belongs to has obtained enough cargo to call it a day. Currently this happens when cargo space usage is above 50%, but more sophisticated checks are planned involving damage or lost ships, expenditure of consumables, and so on.<br />
<br />
==== <code>conditionPiratesCanBePaidOff</code> ====<br />
function '''conditionPiratesCanBePaidOff'''() : Boolean<br />
Pirates have demanded that this ship dump cargo, and it currently has enough cargo on board to meet that demand.<br />
<br />
=== Scanning conditions ===<br />
<br />
These conditions check the ship's latest scan ([[#configurationCheckScanner|configurationCheckScanner]]) for ships meeting particular requirements. If a ship is found, it will be placed in the "oolite_scanResultSpecific" parameter, in addition to the condition returning true.<br />
<br />
==== <code>conditionScannerContainsAssassinationTarget</code> ====<br />
function '''conditionScannerContainsAssassinationTarget'''() : Boolean<br />
The scan contains an assassination target (i.e. an escape capsule)<br />
<br />
==== <code>conditionScannerContainsCleanShip</code> ====<br />
function '''conditionScannerContainsCleanShip'''() : Boolean<br />
The scan contains a clean ship<br />
<br />
==== <code>conditionScannerContainsCourier</code> ====<br />
function '''conditionScannerContainsCourier'''() : Boolean<br />
The scan contains a courier ship<br />
<br />
==== <code>conditionScannerContainsEscapePods</code> ====<br />
function '''conditionScannerContainsEscapePods'''() : Boolean<br />
The scan contains an escape pod travelling slower than this ship's maximum speed, and this ship is able to scoop cargo.<br />
<br />
==== <code>conditionScannerContainsFineableOffender</code> ====<br />
function '''conditionScannerContainsFineableOffender'''() : Boolean<br />
The scan contains a piloted ship with an offender legal status at or below the system threshold (varies with government) that has not already been marked for fines.<br />
<br />
==== <code>conditionScannerContainsFugitive</code> ====<br />
function '''conditionScannerContainsFugitive'''() : Boolean<br />
The scan contains a fugitive ship<br />
<br />
==== <code>conditionScannerContainsHuntableOffender</code> ====<br />
function '''conditionScannerContainsHuntableOffender'''() : Boolean<br />
The scan contains a piloted ship with an offender legal status not too small to bother with (varies with government).<br />
<br />
==== <code>conditionScannerContainsSeriousOffender</code> ====<br />
function '''conditionScannerContainsSeriousOffender'''() : Boolean<br />
The scan contains a piloted ship with an offender legal status at or above the system threshold for fines (varies with government).<br />
<br />
==== <code>conditionScannerContainsHunters</code> ====<br />
function '''conditionScannerContainsHunters'''() : Boolean<br />
The scan contains a ship with role "hunter", or a police ship, or the main station.<br />
<br />
==== <code>conditionScannerContainsLoneVictim</code> ====<br />
function '''conditionScannerContainsLoneVictim'''() : Boolean<br />
The scan contains a single pirate victim and no other unallied ships.<br />
<br />
==== <code>conditionScannerContainsMiningOpportunity</code> ====<br />
function '''conditionScannerContainsMiningOpportunity'''() : Boolean<br />
The scan contains a boulder (preferentially) or an asteroid, and the ship has a mining laser, a fuel scoop, and a non-full hold.<br />
<br />
==== <code>conditionScannerContainsNonThargoid</code> ====<br />
function '''conditionScannerContainsNonThargoid'''() : Boolean<br />
The scan contains a ship which is not a Thargoid ship. Rocks and cargo will only be returned if there is nothing more interesting about.<br />
<br />
==== <code>conditionScannerContainsPirateLeader</code> ====<br />
function '''conditionScannerContainsPirateLeader'''() : Boolean<br />
The scan contains a pirate leader (usually a heavily-armed freighter)<br />
<br />
==== <code>conditionScannerContainsPirateVictims</code> ====<br />
function '''conditionScannerContainsPirateVictims'''() : Boolean<br />
The scan contains a pirate victim (as defined by <code>[[role-categories.plist]]</code>) which is carrying at least some cargo and has not recently been robbed.<br />
<br />
==== <code>conditionScannerContainsReadyThargoidMothership</code> ====<br />
function '''conditionScannerContainsReadyThargoidMothership'''() : Boolean<br />
The scan contains a thargoid mothership which has the capability to control at least one more thargon.<br />
<br />
==== <code>conditionScannerContainsRocks</code> ====<br />
function '''conditionScannerContainsRocks'''() : Boolean<br />
The scan contains boulders (preferentially) or asteroids.<br />
<br />
==== <code>conditionScannerContainsSalvage</code> ====<br />
function '''conditionScannerContainsSalvage'''() : Boolean<br />
The scan contains cargo which could in theory be scooped.<br />
<br />
==== <code>conditionScannerContainsSalvageForGroup</code> ====<br />
function '''conditionScannerContainsSalvageForGroup'''() : Boolean<br />
The scan contains cargo which could in theory be scooped, and it is travelling slowly enough that at least one of the ships in the group with fuel scoops and cargo space can collect it..<br />
<br />
==== <code>conditionScannerContainsSalvageForMe</code> ====<br />
function '''conditionScannerContainsSalvageForMe'''() : Boolean<br />
The scan contains cargo which can be scooped by this ship (travelling slowly enough, and this ship has scoops and space)<br />
<br />
==== <code>conditionScannerContainsShipNeedingEscort</code> ====<br />
function '''conditionScannerContainsShipNeedingEscort'''() : Boolean<br />
The scan contains a ship which has fewer escorts than its maximum. If the ship is clean, this will only detect other clean ships. If the ship is not clean, this will only detect other non-clean ships.<br />
<br />
==== <code>conditionScannerContainsSuspiciousShip</code> ====<br />
function '''conditionScannerContainsSuspiciousShip'''() : Boolean<br />
The scan contains a ship with a criminal reputation (whether or not it currently carries a bounty)<br />
<br />
==== <code>conditionScannerContainsThargoidMothership</code> ====<br />
function '''conditionScannerContainsThargoidMothership'''() : Boolean<br />
The scan contains a thargoid mothership which has the capability to control thargons. The number of thargons currently being controlled is irrelevant to this scan.<br />
<br />
==== <code>conditionScannerContainsUnspreadMissile</code> ====<br />
function '''conditionScannerContainsUnspreadMissile'''() : Boolean<br />
The scan contains a missile which has the same target and owner as this ship, but is closer to the target and within 500 metres of this ship. This is mainly used for "smart" missiles to ensure that impact times for a salvo are spread out.<br />
<br />
=== State querying conditions ===<br />
<br />
Conditions related to the state of the ship<br />
<br />
==== <code>conditionAllEscortsInFlight</code> ====<br />
function '''conditionAllEscortsInFlight'''() : Boolean<br />
If the ship has living escorts, then this function returns <code>true</code> only if they are all in normal flight (and not docked, launching, or in a wormhole). If the ship has no escorts then this function also returns <code>true</code>.<br />
<br />
==== <code>conditionCanScoopCargo</code> ====<br />
function '''conditionCanScoopCargo'''() : Boolean<br />
The ship has a working fuel scoop and at least 1 TC of free space in its hold.<br />
<br />
==== <code>conditionCargoIsProfitableHere</code> ====<br />
function '''conditionCargoIsProfitableHere'''() : Boolean<br />
The current contents of the ship's hold can be sold at an above average price at the main station (this is currently determined very approximately - solely asking "is the current system on the right side of the Ind/Agri divide" - rather than checking station prices.<br />
<br />
==== <code>conditionCoinFlip</code> ====<br />
function '''conditionCoinFlip'''() : Boolean<br />
Returns true half the time.<br />
<br />
==== <code>conditionGroupLeaderIsStation</code> ====<br />
function '''conditionGroupLeaderIsStation'''() : Boolean<br />
The ship has a group leader and the group leader is a station.<br />
<br />
==== <code>conditionHasInterceptCoordinates</code> ====<br />
function '''conditionHasInterceptCoordinates'''() : Boolean<br />
The ship has intercept coordinates set in the parameter "oolite_interceptCoordinates". These are used by missiles to home in on a last-known location if the target cloaks.<br />
<br />
==== <code>conditionHasMothership</code> ====<br />
function '''conditionHasMothership'''() : Boolean<br />
The ship has a group leader which is not itself.<br />
<br />
==== <code>conditionHasNonThargoidTarget</code> ====<br />
function '''conditionHasNonThargoidTarget'''() : Boolean<br />
The ship's target is not null, and is not a thargoid ship (by scan class).<br />
<br />
==== <code>conditionHasReceivedDistressCall</code> ====<br />
function '''conditionHasReceivedDistressCall'''() : Boolean<br />
The ship has recently received a distress call. Distress calls expire after 30 seconds, or if the sender is no longer visible, or if the aggressor is dead.<br />
<br />
==== <code>conditionHasRememberedTarget</code> ====<br />
function '''conditionHasRememberedTarget'''() : Boolean<br />
The ship has a remembered target. This is set by [[#behaviourFollowCurrentTarget|behaviourFollowCurrentTarget]] to allow persistent tracking of a ship.<br />
<br />
==== <code>conditionHasTarget</code> ====<br />
function '''conditionHasTarget'''() : Boolean<br />
The ship's target is not null.<br />
<br />
==== <code>conditionHasWaypoint</code> ====<br />
function '''conditionHasWaypoint'''() : Boolean<br />
The ship has a waypoint set by its [[#|waypoint generator]].<br />
<br />
==== <code>conditionIsActiveThargon</code> ====<br />
function '''conditionIsActiveThargon'''() : Boolean<br />
The ship is a thargon ("EQ_THARGON") and is active.<br />
<br />
==== <code>conditionIsEscorting</code> ====<br />
function '''conditionIsEscorting'''() : Boolean<br />
The ship is currently escorting another ship. Stricter than [[#conditionHasMothership|conditionHasMothership]]: this also requires this ship to be in the group leader's escort group.<br />
<br />
==== <code>conditionIsGroupLeader</code> ====<br />
function '''conditionIsGroupLeader'''() : Boolean<br />
The ship is in a group and is the leader of the group<br />
<br />
==== <code>conditionMissileNeedsLaunchEvasion</code> ====<br />
function '''conditionMissileNeedsLaunchEvasion'''() : Boolean<br />
This function checks if the <code>oolite_flag_launchAdjustMissile</code> parameter is set to a non-null value, and returns true if so.<br />
<br />
Missile AI scripts may find the following code useful to set this flag to avoid collisions with the launching ship.<br />
<br />
this.shipSpawned = function()<br />
{<br />
/* Launch correction when fired at target in aft arc */<br />
var s = this.ship; <br />
if(s.target && s.target.position.subtract(s.position).direction().dot(s.vectorForward) < -0.8)<br />
{<br />
this.oolite_priorityai.setParameter("oolite_flag_launchAdjustMissile",true);<br />
}<br />
}<br />
<br />
See also [[#configurationMissileAdjustLaunch|configurationMissileAdjustLaunch]]<br />
<br />
==== <code>conditionMissileOutOfFuel</code> ====<br />
function '''conditionMissileOutOfFuel'''() : Boolean<br />
The ship has travelled beyond the maximum missile range. The default is 30km, but this may be overridden by the <code>oolite_missile_range</code> parameter in the ship's script info.<br />
<br />
==== <code>conditionPatrolIsOver</code> ====<br />
function '''conditionPatrolIsOver'''() : Boolean<br />
The ship's patrol is over (either due to distance travelled or a need to re-arm and repair). Note that the distance threshold is relatively low, so for ships on long patrol routes between system bodies this function should only be called when reaching appropriate waypoints.<br />
<br />
From Oolite 1.81, the distance threshold can be changed from the default 200km by setting the <code>oolite_patrolLength</code> parameter.<br />
<br />
==== <code>conditionWitchspaceEntryRequested</code> ====<br />
function '''conditionWitchspaceEntryRequested'''() : Boolean<br />
The ship has been requested to enter a wormhole set in the "oolite_witchspaceWormhole" parameter.<br />
<br />
== Configuration functions ==<br />
<br />
Configuration functions are usually used to set up parameters needed for a behaviour, though some may be used at the preconfiguration stage to set up parameters for a condition test. They take no arguments and do not return anything.<br />
<br />
=== Destination configurations ===<br />
<br />
These configurations set a destination, a desired range and a desired speed suitable for use with [[#behaviourApproachDestination|behaviourApproachDestination]]. Unless otherwise stated, [[#cruiseSpeed|cruiseSpeed]] will be used as the desired speed.<br />
<br />
If they are unable to set a destination, they may set the destination to the ship's current position, or may do nothing. Generally a condition should be used to check that the configuration is sensible.<br />
<br />
==== <code>configurationMissileAdjustLaunch</code> ====<br />
function '''configurationMissileAdjustLaunch'''()<br />
This function causes the missile to dive sharply. The intended use is in conjunction with [[#conditionMissileNeedsLaunchEvasion|conditionMissileNeedsLaunchEvasion]] to avoid collisions with the launching ship.<br />
<br />
==== <code>configurationMissileAdjustSpread</code> ====<br />
function '''configurationMissileAdjustSpread'''()<br />
This function sets an intermediate destination for "smart" missiles which are adjusting their flight path to spread out a salvo's impacts on target.<br />
<br />
==== <code>configurationSetDestinationToHomeStation</code> ====<br />
function '''configurationSetDestinationToHomeStation'''()<br />
Locates the home station, sets the destination to its position and the desired range to 15km.<br />
<br />
==== <code>configurationSetDestinationToGroupLeader</code> ====<br />
function '''configurationSetDestinationToGroupLeader'''()<br />
Locates the group leader, sets the destination to its position and the desired range to 15km. Maximum flight speed is used.<br />
<br />
==== <code>configurationSetDestinationToMainPlanet</code> ====<br />
function '''configurationSetDestinationToMainPlanet'''()<br />
Sets the destination to the main planet's position, and the desired range to 3 radii (i.e. 2 radii from the surface).<br />
<br />
==== <code>configurationSetDestinationToMainStation</code> ====<br />
function '''configurationSetDestinationToMainStation'''()<br />
Sets the destination to the main station's position, and the desired range to 15km<br />
<br />
==== <code>configurationSetDestinationToNearestHostileStation</code> ====<br />
function '''configurationSetDestinationToNearestHostileStation'''()<br />
Locates the nearest friendly station, sets the destination to its position and the desired range to 15km.<br />
<br />
==== <code>configurationSetDestinationToNearestFriendlyStation</code> ====<br />
function '''configurationSetDestinationToNearestFriendlyStation'''()<br />
Locates the nearest friendly station, sets the destination to its position and the desired range to 15km.<br />
<br />
==== <code>configurationSetDestinationToNearestStation</code> ====<br />
function '''configurationSetDestinationToNearestStation'''()<br />
Locates the nearest station, sets the destination to its position and the desired range to 15km.<br />
<br />
==== <code>configurationSetDestinationToNearestWormhole</code> ====<br />
function '''configurationSetDestinationToNearestWormhole'''()<br />
Locates the nearest entry wormhole, sets the destination to its position and the desired range to zero.<br />
<br />
==== <code>configurationSetDestinationToPirateLurk</code> ====<br />
function '''configurationSetDestinationToPirateLurk'''()<br />
If the parameter "oolite_pirateLurk" is set, then set the destination to that. If currently on a lane, set the destination to the current position. Otherwise, pick a random point on one of the lanes (strongly preferring witchpoint-planet). Once a destination is selected, store it to the parameter "oolite_pirateLurk".<br />
<br />
The desired range is 1km.<br />
<br />
<br />
==== <code>configurationSetDestinationToScannedTarget</code> ====<br />
function '''configurationSetDestinationToScannedTarget'''()<br />
Sets the destination to the position of the ship in the parameter "oolite_scanResultSpecific", and the desired range to 400m. This can be used to follow a ship without targeting it.<br />
<br />
==== <code>configurationSetDestinationToSelectedPlanet</code> ====<br />
function '''configurationSetDestinationToSelectedPlanet'''()<br />
Sets the destination to the position of the planet in the parameter "oolite_selectedPlanet", and the desired range to 100m from the surface.<br />
<br />
==== <code>configurationSetDestinationToSelectedStation</code> ====<br />
function '''configurationSetDestinationToSelectedStation'''()<br />
Sets the destination to the position of the station in the parameter "oolite_selectedStation", and the desired range to 15km.<br />
<br />
==== <code>configurationSetDestinationToSunskimEnd</code> ====<br />
function '''configurationSetDestinationToSunskimEnd'''()<br />
Sets the destination to a course parallel to the sun's surface, at a range which should allow the fuel tanks to be completely refilled. The desired range is 0, and the desired speed is maximum speed.<br />
<br />
Note: if this function is used above sunskimming height, it will still<br />
move parallel to the sun's surface, but this will not be much use.<br />
<br />
==== <code>configurationSetDestinationToSunskimStart</code> ====<br />
function '''configurationSetDestinationToSunskimStart'''()<br />
Sets the destination to the sun's position, and the desired range to sunskimming height.<br />
<br />
==== <code>configurationSetDestinationToWaypoint</code> ====<br />
function '''configurationSetDestinationToWaypoint'''()<br />
If the parameters "oolite_waypoint" and "oolite_waypointRange" are set, use those as the destination and desired range.<br />
<br />
==== <code>configurationSetDestinationToWitchpoint</code> ====<br />
function '''configurationSetDestinationToWitchpoint'''()<br />
Sets the destination to the witchpoint and the range to 10km<br />
<br />
==== <code>configurationSetWaypoint</code> ====<br />
function '''configurationSetWaypoint'''()<br />
If a waypoint generator function has been registered, runs that function to set the "oolite_waypoint" and "oolite_waypointRange" parameters, then sets the destination from those parameters.<br />
<br />
=== Docking configurations ===<br />
<br />
Each of these configurations sets the "oolite_dockingStation" parameter used by [[#behaviourDockWithStation|behaviourDockWithStation]]<br />
<br />
==== <code>configurationSetNearbyFriendlyStationForDocking</code> ====<br />
function '''configurationSetNearbyFriendlyStationForDocking'''()<br />
Sets the "oolite_dockingStation" parameter to a friendly station in scanner range, if possible.<br />
<br />
==== <code>configurationSetHomeStationForDocking</code> ====<br />
function '''configurationSetHomeStationForDocking'''()<br />
Sets the "oolite_dockingStation" parameter to the ship's home station.<br />
<br />
==== <code>configurationSetSelectedStationForDocking</code> ====<br />
function '''configurationSetHomeStationForDocking'''()<br />
Sets the "oolite_dockingStation" parameter to the station in the parameter "oolite_selectedStation".<br />
<br />
=== Miscellaneous configurations ===<br />
<br />
==== <code>configurationAppointGroupLeader</code> ====<br />
function '''configurationAppointGroupLeader'''()<br />
If the ship is in a group but the group has no leader, set one of the ships in the group to be the leader. Witchspace-capable ships will be preferred over those which are not.<br />
<br />
If the parameter "oolite_leaderRole" is set, the primary role of the new leader will be changed to that role.<br />
<br />
==== <code>configurationEscortGroupLeader</code> ====<br />
function '''configurationEscortGroupLeader'''()<br />
If the ship is in a group and the group has a leader which is not this ship and the ship is not already escorting the group leader, and the parameter "oolite_escortRole" is set, then attempt to escort the group leader. The ship's primary role will be set to "oolite_escortRole" if the escort attempt is successful, and this role must therefore be a valid escort role.<br />
<br />
==== <code>configurationForgetCargoDemand</code> ====<br />
function '''configurationForgetCargoDemand'''()<br />
If the ship has a cargo demand active (the demand must be stored on this ship, not just on a group member), discard it, and reset the "oolite_cargoDropped" parameter of this ship and all group members to zero.<br />
<br />
==== <code>configurationLeaveEscortGroup</code> ====<br />
function '''configurationLeaveEscortGroup'''()<br />
If the ship is currently escorting another ship, leave the escort group.<br />
<br />
==== <code>configurationLightsOff</code> ====<br />
function '''configurationLightsOff'''()<br />
Set the ship's flashers to the 'off' state.<br />
<br />
==== <code>configurationLightsOn</code> ====<br />
function '''configurationLightsOn'''()<br />
Set the ship's flashers to the 'on' state.<br />
<br />
==== <code>configurationSetRemoteControl</code> ====<br />
function '''configurationSetRemoteControl'''()<br />
If the ship has a group leader, set its own accuracy to that ship's accuracy. This is used by thargons when the mothership controlling them is changed.<br />
<br />
=== Navigation configurations ===<br />
<br />
==== <code>configurationSelectPlanet</code> ====<br />
function '''configurationSelectPlanet'''()<br />
This function places a randomly selected planet or moon in the parameter "oolite_selectedPlanet"<br />
<br />
==== <code>configurationSelectRandomTradeStation</code> ====<br />
function '''configurationSelectRandomTradeStation'''()<br />
This function places a suitable station in the parameter "oolite_selectedStation". If the ship is clean, then 90% of the time this will be the main station. If the ship is an offender, but has a bounty not greater than the fine threshold, then 50% of the time this will be the main station.<br />
<br />
If the main station was not selected at the previous step, a random<br />
friendly station will be selected (which may be the main station<br />
anyway)<br />
<br />
==== <code>configurationSelectShuttleDestination</code> ====<br />
function '''configurationSelectShuttleDestination'''()<br />
This function selects a random planet or station. The entity selected must be at least 10km from the ship. If any such entities are within 5 times the radius of the main planet from the ship, more distant entities will be ignored.<br />
<br />
If the selected entity was a planet, it will be stored in "oolite_selectedPlanet". Otherwise, it will be stored in "oolite_selectedStation".<br />
<br />
==== <code>configurationSelectWitchspaceDestination</code> ====<br />
function '''configurationSelectWitchspaceDestination'''()<br />
If the ship has no witchspace drive, unset the "oolite_witchspaceDestination" parameter. If that parameter is already set, and is not the current system, and the ship has enough fuel to reach that system, do nothing. Otherwise, select a random system in range and place its ID in the "oolite_witchspaceDestination" parameter.<br />
<br />
==== <code>configurationSelectWitchspaceDestinationInbound</code> ====<br />
function '''configurationSelectWitchspaceDestination'''()<br />
If the ship has no witchspace drive, unset the "oolite_witchspaceDestination" parameter. If the ship's home system and destination system are unequal, select the next system on the route to the home system. Otherwise, select a random system in range and place its ID in the "oolite_witchspaceDestination" parameter.<br />
<br />
==== <code>configurationSelectWitchspaceDestinationOutbound</code> ====<br />
function '''configurationSelectWitchspaceDestination'''()<br />
If the ship has no witchspace drive, unset the "oolite_witchspaceDestination" parameter. If the ship's home system and destination system are unequal, select the next system on the route to the destination system. Otherwise, select a random system in range and place its ID in the "oolite_witchspaceDestination" parameter.<br />
<br />
=== Station configurations ===<br />
<br />
==== <code>configurationStationReduceAlertLevel</code> ====<br />
function '''configurationStationReduceAlertLevel'''()<br />
Reduce the alert level of the station by one stage if it is not already Green.<br />
<br />
==== <code>configurationStationValidateTarget</code> ====<br />
function '''configurationStationValidateTarget'''()<br />
Check that the station's current target is within scanner range, and discard it if not. This is necessary for stations as unlike ships their low-level behaviour does not generally do this automatically.<br />
<br />
=== Target acquisition configurations ===<br />
<br />
==== <code>configurationAcquireCombatTarget</code> ====<br />
function '''configurationAcquireCombatTarget'''()<br />
If the ship's target is valid, not cargo and not an ally, keep the current target. Otherwise, promote one defense target to a target. If the ship has no defense targets, check to see if any ships in the group or escort group have a combat target (but do not check their defense targets).<br />
<br />
==== <code>configurationAcquireDefensiveEscortTarget</code> ====<br />
function '''configurationAcquireDefensiveEscortTarget'''()<br />
Search the current group leader's target and defense targets for a visible ship attacking the group leader, and target it if one is found. Otherwise, retain current target.<br />
<br />
==== <code>configurationAcquireHostileCombatTarget</code> ====<br />
function '''configurationAcquireHostileCombatTarget'''()<br />
As [[#configurationAcquireCombatTarget|configurationAcquireCombatTarget]] but only targets which are hostile (i.e. would be valid for [[#behaviourRepelTarget|behaviourRepelTarget]]) will be selected.<br />
<br />
==== <code>configurationAcquireOffensiveEscortTarget</code> ====<br />
function '''configurationAcquireOffensiveEscortTarget'''()<br />
If this ship's group leader is attacking a target, and this ship can see that target, acquire that target. Otherwise retain current target.<br />
<br />
==== <code>configurationAcquirePlayerAsTarget</code> ====<br />
function '''configurationAcquirePlayerAsTarget'''()<br />
Set this ship's target to the player.<br />
<br />
==== <code>configurationAcquireScannedTarget</code> ====<br />
function '''configurationAcquireScannedTarget'''()<br />
Set this ship's target to the entity in the parameter "oolite_scanResultSpecific". This parameter is set by the [[#checkScannerWithPredicate|checkScannerWithPredicate]] function, which is usually called from a <code>conditionScannerContains...</code> condition.<br />
<br />
==== <code>configurationCheckScanner</code> ====<br />
function '''configurationCheckScanner'''()<br />
Scans the ship's scanner range, placing a list of detected targets into the "oolite_scanResults" parameter. This is generally called in a preconfiguration before the first use of a <code>conditionScannerContains...</code> condition in the priority list. <br />
<br />
If the scanner is particularly full, the list will not contain all visible objects. The current scan limit is 16.<br />
<br />
== Response definition functions and components ==<br />
<br />
=== Response definition functions ===<br />
<br />
Response definition functions are used to set up event handlers in the AI script. They take an object as an argument, and add event handlers to that object. They do not return anything as such, but modify their argument.<br />
<br />
They are generally used in behaviour functions to set up common responses. <br />
var handlers = {}; // new handler object<br />
this.responsesAddStandard(handlers); // add standard response set<br />
// add a handler for this behaviour<br />
handlers.shipEnteredStationAegis = function(station)<br />
{<br />
this.ship.beaconCode = null; // stop transmitting<br />
}<br />
this.applyHandlers(handlers);<br />
<br />
==== <code>responsesAddDocking</code> ====<br />
function '''responsesAddDocking'''(handlers : Object)<br />
Provides some additional event handlers for use when docking with a station. <br />
<br />
==== <code>responsesAddEscort</code> ====<br />
function '''responsesAddEscort'''(handlers : Object)<br />
Provides some additional event handlers for use when escorting a ship, and changes the response to in-group help requests.<br />
<br />
==== <code>responsesAddMissile</code> ====<br />
function '''responsesAddMissile'''(handlers : Object)<br />
A standard set of event handlers for missiles, which should be used instead of <code>responsesAddStandard</code>.<br />
<br />
A number of script info keys are used to modify the responses.<br />
* oolite_missile_blastPower, oolite_missile_blastRadius, oolite_missile_blastShaping: If oolite_missile_detonation is not set, the default detonation function calls this.ship.dealEnergyDamage with the defined power, radius, and shaping. If these parameters are not set the defaults are power 170, radius 32.5, and shaping 0.25.<br />
* oolite_missile_detonation: names a function in the AI script. This function will be called when the missile reaches the desired range from its target or destination. If this function is not set, the oolite_missile_blast* keys are used to set up an explosion.<br />
* oolite_missile_ecmResponse: names a function in the AI script. This function will be called if the missile detects an ECM pulse. If no function is set, the missile will self destruct.<br />
<br />
==== <code>responsesAddScooping</code> ====<br />
function '''responsesAddScooping'''(handlers : Object)<br />
Provides some additional event handlers for use when scooping fuel.<br />
<br />
==== <code>responsesAddStandard</code> ====<br />
function '''responsesAddStandard'''(handlers : Object)<br />
Sets up standard event handlers to detect and respond to attacks, and to manage other common events. Certain parameter flags are used:<br />
* oolite_flag_allowPlanetaryLanding: if true, the ship will land on a planet if it receives the <code>approachingPlanetSurface</code> event. Otherwise, it will immediately reconsider its behaviour.<br />
* oolite_flag_listenForDistressCall: if true, the ship will set the "oolite_distressAggressor", "oolite_distressSender" and "oolite_distressTimestamp" parameters if it receives a distress call.<br />
* oolite_flag_markOffenders: if true, the ship will apply a small bounty increase to ships it sees committing crimes.<br />
* oolite_flag_sendsDistressCalls: if true, the ship will send distress calls when attacked.<br />
* oolite_flag_watchForCargo: if true, the ship will increment the "oolite_cargoDropped" parameter if cargo is dumped nearby.<br />
<br />
If multiple standard responses are being applied, this one should be the first one applied.<br />
<br />
==== <code>responsesAddStation</code> ====<br />
function '''responsesAddStation'''(handlers : Object)<br />
A standard set of event handlers for stations, which should be used instead of <code>responsesAddStandard</code>. The "oolite_flag_listenForDistressCall" and "oolite_flag_markOffenders" parameters have the same use as in <code>responsesAddStandard</code>.<br />
<br />
=== Response definition components ===<br />
<br />
The components are standard event handlers used by the standard response functions. The following response components are available. Each is named "<code>responseComponent_''responseGroup''_''handlerName''</code>". You can use them in your own handler definition functions for efficiency.<br />
var handlers = {};<br />
handlers.approachingPlanetSurface = this.responseComponent_standard_approachingPlanetSurface;<br />
// .. etc ..<br />
this.applyHandlers(handlers);<br />
<br />
==== Standard components ====<br />
Standard event handlers for normal ships.<br />
responseComponent_standard_approachingPlanetSurface<br />
responseComponent_standard_cargoDumpedNearby<br />
responseComponent_standard_cascadeWeaponDetected<br />
responseComponent_standard_commsMessageReceived<br />
responseComponent_standard_distressMessageReceived<br />
responseComponent_standard_escortAccepted<br />
responseComponent_standard_helpRequestReceived<br />
responseComponent_standard_offenceCommittedNearby<br />
responseComponent_standard_playerWillEnterWitchspace<br />
responseComponent_standard_shipAcceptedEscort<br />
responseComponent_standard_shipAchievedDesiredRange<br />
responseComponent_standard_shipAttackedOther<br />
responseComponent_standard_shipAttackedWithMissile<br />
responseComponent_standard_shipAttackerDistracted<br />
responseComponent_standard_shipBeingAttacked<br />
responseComponent_standard_shipBeingAttackedUnsuccessfully<br />
responseComponent_standard_shipFiredMissile<br />
responseComponent_standard_shipKilledOther<br />
responseComponent_standard_shipLaunchedEscapePod<br />
responseComponent_standard_shipLaunchedFromStation<br />
responseComponent_standard_shipScoopedOther<br />
responseComponent_standard_shipTargetLost<br />
responseComponent_standard_shipWillEnterWormhole<br />
responseComponent_standard_shipWitchspaceBlocked<br />
responseComponent_standard_wormholeSuggested<br />
<br />
==== Missile components ====<br />
Standard event handlers for missiles.<br />
responseComponent_missile_commsMessageReceived<br />
responseComponent_missile_shipHitByECM<br />
responseComponent_missile_shipTargetCloaked<br />
responseComponent_missile_shipTargetLost<br />
responseComponent_missile_shipAchievedDesiredRange<br />
<br />
<br />
==== Station components ====<br />
Standard event handlers for stations.<br />
responseComponent_station_commsMessageReceived<br />
responseComponent_station_cascadeWeaponDetected<br />
responseComponent_station_shipAttackedWithMissile<br />
responseComponent_station_shipBeingAttacked<br />
responseComponent_station_shipAttackedOther<br />
responseComponent_station_shipFiredMissile<br />
responseComponent_station_shipKilledOther<br />
responseComponent_station_shipTargetLost<br />
responseComponent_station_helpRequestReceived<br />
responseComponent_station_distressMessageReceived<br />
responseComponent_station_offenceCommittedNearby<br />
<br />
==== Docking components ====<br />
Alternative event handlers for docking ships.<br />
responseComponent_docking_shipAchievedDesiredRange<br />
responseComponent_docking_stationWithdrewDockingClearance<br />
responseComponent_docking_shipAIFrustrated<br />
<br />
==== Escort components ====<br />
Alternative event handlers for escorts.<br />
responseComponent_escort_escortDock<br />
responseComponent_escort_helpRequestReceived<br />
<br />
==== Expect-witchspace components ====<br />
Alternative event handlers for ships expecting that their target might enter witchspace to escape<br />
responseComponent_expectWitchspace_shipTargetLost<br />
<br />
==== Scooping components ====<br />
Alternative event handlers for ships scooping fuel.<br />
responseComponent_scooping_shipAchievedDesiredRange<br />
responseComponent_scooping_shipScoopedFuel<br />
<br />
==== Track-player components ====<br />
Alternative event handlers for ships following the player.<br />
responseComponent_trackPlayer_playerWillEnterWitchspace<br />
<br />
== Template functions ==<br />
<br />
These functions return standard blocks of priorities for insertion into a priority list. Each of them returns an array, so can be used as a branch in its own right, or concatenated on to an existing array. Remember that unlike a standard priority entry, you need the result of these functions, not a reference to the function.<br />
{<br />
condition: ai.conditionInCombat,<br />
falsebranch: ai.templateReturnToBase()<br />
}<br />
or<br />
priorities.concat(ai.templateReturnToBase());<br />
<br />
==== templateLeadHuntingMission ====<br />
function '''templateLeadHuntingMission'''() : Array<br />
Return the priorities for leading a patrol between waypoints. Setting the waypoint generator and handling fighting and scanning along the course of the patrol should be handled by higher priorities.<br />
<br />
==== templateLeadPirateMission ====<br />
function '''templateLeadPirateMission'''() : Array<br />
Return the priorities for selecting targets to rob if any are about, or moving to a suitable lurk position otherwise.<br />
<br />
==== templateReturnToBase ====<br />
function '''templateReturnToBase'''() : Array<br />
Return the priorities for travelling to and docking with a suitable station.<br />
<br />
==== templateReturnToBaseOrPlanet ====<br />
function '''templateReturnToBaseOrPlanet'''() : Array<br />
Return the priorities for travelling to and docking with a suitable station, or landing on a planet if no suitable stations are found.<br />
<br />
==== templateWitchspaceJumpAnywhere ====<br />
function '''templateWitchspaceJumpAnywhere'''() : Array<br />
Returns priorities for getting the ship out of the current system somehow - either by jumping out, or by finding a wormhole to hitchhike.<br />
<br />
==== templateWitchspaceJumpInbound ====<br />
function '''templateWitchspaceJumpInbound'''() : Array<br />
Returns priorities for jumping closer to the home system, sunskimming if fuel is short. You should previously have checked that the ship is not in the home system.<br />
<br />
==== templateWitchspaceJumpOutbound ====<br />
function '''templateWitchspaceJumpOutbound'''() : Array<br />
Returns priorities for jumping closer to the destination system, sunskimming if fuel is short. You should previously have checked that the ship is not in the destination system.<br />
<br />
== Utility functions ==<br />
<br />
These functions are provided to make standardised checks easier to write and to wrap certain ship methods to make them easier to work with in the AI controller.<br />
<br />
==== <code>allied</code> ====<br />
function '''allied'''(ship1, ship2) : Boolean<br />
Returns <code>true</code> if the two ships are considered allied, false otherwise. Ships are considered allied if they are in the same group, or if they are escorts of ships in the same group.<br />
<br />
==== <code>broadcastDistressMessage</code> ====<br />
function '''broadcastDistressMessage'''()<br />
Broadcasts a distress message, but with a delay to ensure that [[Oolite_JavaScript_Reference:_Ship#broadcastDistressMessage|ship.broadcastDistressMessage()]] is not called too often.<br />
<br />
<br />
==== <code>checkScannerWithPredicate</code> ====<br />
function '''checkScannerWithPredicate'''(function) : Boolean<br />
Called after configurationCheckScanner to locate a ship on the scanner matching a particular predicate. The predicate function must take a Ship, and return a Boolean.<br />
<br />
If the predicate function matches a ship, the first such match will be stored in the parameter <code>"oolite_scanResultSpecific"</code>, and the method will return <code>true</code>. Otherwise the method returns <code>false</code>.<br />
<br />
==== <code>cruiseSpeed</code> ====<br />
function '''cruiseSpeed'''() : Number<br />
Returns a suitable speed for the ship to travel at if it is interested in preserving group or escort coherence. Generally this will be 80% of its maximum speed, but it will be slower if other group members or escorts are slower.<br />
<br />
==== <code>distance</code> ====<br />
function '''distance'''(position : [[Oolite_JavaScript_Reference:_Vector3D#Vector_Expressions|vectorExpression]])<br />
Returns the distance to the given coordinates. This is more efficient than calling <code>this.ship.position.distanceTo(position)</code>.<br />
<br />
==== <code>entityCommsParams</code> ====<br />
function '''entityCommsParams'''(entity : Entity) : Object<br />
Returns an object of communications parameters relating to the given entity. Used internally by [[#communicate|communicate()]] but may be of use elsewhere.<br />
<br />
==== <code>fineThreshold</code> ====<br />
function '''fineThreshold'''() : Number<br />
The maximum bounty at which an offender should be fined rather than attacked by police ships. (Ships caught redhanded may be attacked regardless of bounty) Varies from system to system.<br />
<br />
==== <code>friendlyStation</code> ====<br />
function '''friendlyStation'''(station) : Boolean<br />
Returns <code>true</code> if the station is friendly to the current ship, false otherwise. The main station is unfriendly to Fugitive ships and Offenders above the current [[#fineThreshold|fineThreshold]]. Other stations are only considered unfriendly to their current combat target.<br />
<br />
==== <code>homeStation</code> ====<br />
function '''homeStation'''() : Boolean<br />
Returns the home station of this ship. If the ship has an owner, and<br />
the owner is a station, then that is the home station. Otherwise, the<br />
first station in the ship's group is returned.<br />
<br />
If no home station can be found, returns <code>null</code>.<br />
<br />
==== <code>ignorePlayerFriendlyFire</code> ====<br />
function '''ignorePlayerFriendlyFire'''() : Boolean<br />
Returns <code>true</code> if this ship should ignore friendly fire from the player as they would for a known ally. Note that this function's results will change if called repeatedly, so you should only call it once per instance of friendly fire, and never call it speculatively. <br />
<br />
==== <code>isAggressive</code> ====<br />
function '''isAggressive'''() : Boolean<br />
Returns <code>true</code> if the ship is an active danger to its current target (approximately: it is in a combat behaviour other than fleeing)<br />
<br />
==== <code>isEscaping</code> ====<br />
function '''isEscaping'''() : Boolean<br />
Returns <code>true</code> if the ship is successfully running away from this ship (i.e. it is not attacking, it is travelling faster than this ship can, and it is already outside effective weapons range.<br />
<br />
==== <code>isFighting</code> ====<br />
function '''isAggressive'''() : Boolean<br />
Returns <code>true</code> if the ship is in combat (including fleeing). Similar to <code>ship.hasHostileTarget</code> but works for stations as well.<br />
<br />
==== <code>noteDistraction</code> ====<br />
function '''noteDistraction'''(whom : Entity)<br />
If this ship is switching combat targets because another ship distracted it, then call this function just before switching. <code>whom</code> is the entity that this ship will soon switch to attacking. This calls the <code>shipAttackerDistracted</code> event handler on the current target.<br />
<br />
==== <code>oddsAssessment</code> ====<br />
function '''oddsAssessment'''() : Number<br />
Carry out an odds assessment of this ship's group versus the target ship's group. This will return a positive number of the ratio between the two values, with a number greater than 1 implying that this ship's group is stronger, and a number less than 1 implying the target's group is stronger. The odds assessment of the target group will omit certain information unless the target is currently in combat. Ships outside of scanner range, whether friendly or hostile, will also be ignored in the assessment.<br />
<br />
==== <code>playerRoleAssessment</code> ====<br />
function '''playerRoleAssessment'''() : String<br />
Determines a single perceived role for the player based on [[Oolite_JavaScript_Reference:_Player#roleWeights|player.roleWeights]]. In general, the perception will be the same for all ships in a group. This can then be used with [[Oolite_JavaScript_Reference:_Ship#roleIsInCategory|Ship.roleIsInCategory]] to determine the appropriate response.<br />
<br />
==== <code>respondToThargoids</code> ====<br />
function '''respondToThargoids'''(whom : Ship, passon : Boolean) : Boolean<br />
This function causes the ship (and if the <code>passon</code> parameter is set, its group members) to respond to the appearance of the Thargoid ship <code>whom</code>. It will return <code>true</code> if this ship responds, or <code>false</code> if not.<br />
<br />
You must ensure that ships responding to a Thargoid as a result of a notification by a group member do not themselves set <code>passon</code> as this may cause an infinite loop.<br />
<br />
==== <code>setWitchspaceRouteTo</code> ====<br />
function '''setWitchspaceRouteTo'''(dest : Number)<br />
This function sets the <code>oolite_witchspaceDestination</code> parameter according to the needs of reaching the system with the system ID equal to <code>dest</code>. As this function involves route planning, which is relatively slow, it should be called only rarely. This can then be used to determine whether to refuel or attempt to jump.<br />
<br />
==== <code>shipHasRiskyContracts</code> ====<br />
function '''shipHasRiskyContracts'''(ship : Ship) : Boolean<br />
Sometimes returns <code>true</code> (non-deterministically) if the target ship is carrying contracts that someone might want assassinated or destroyed. The chance of returning <code>true</code> increases with the number of risky contracts carried. Currently this will always return <code>false</code> for a non-player ship: you can check these with the <code>oolite-courier</code> role category instead.<br />
<br />
==== <code>shipInRoleCategory</code> ====<br />
function '''shipInRoleCategory'''(ship : Ship, category : String) : Boolean<br />
This is a wrapper around <code>Ship.roleIsInCategory</code> which accounts for the player's effective role not being the same as <code>player.ship.primaryRole</code>. You should generally call this instead of calling <code>Ship.roleIsInCategory</code> directly.<br />
<br />
==== <code>stationAllegiance</code> ====<br />
function '''stationAllegiance'''(station : Station) : String<br />
Returns <code>station.allegiance</code> for the given station, but if this is null (as it will be for pre-1.79 stations), first sets it using a heuristic calculation.<br />
<br />
==== <code>threatAssessment</code> ====<br />
function '''threatAssessment'''(ship : Ship, full : Boolean) : Number<br />
This is a wrapper around <code>[[#_threatAssessment|_threatAssessment]]</code> which is itself a wrapper around <code>[[Oolite_JavaScript_Reference:_Ship#threatAssessment|ship.threatAssessment()]]</code>. The combination of the two ensures that the assessment is correct for the relative combat states of this ship and the ship being assessed, as well as including effects of the player's reputation.<br />
<br />
== Waypoint Generators ==<br />
<br />
Waypoint generators are used to set patrol or other multipoint routes. When called, they should consider the ship's current position (and possibly other things), and then set the parameters "oolite_waypoint" and "oolite_waypointRange". These functions have no arguments and no return value.<br />
<br />
In general, you should only call a waypoint generator if a waypoint is not already set.<br />
<br />
==== <code>waypointsSpacelanePatrol</code> ====<br />
function '''waypointsSpacelanePatrol'''()<br />
If the ship is near the main planet, sun, or witchpoint, pick one of the other two points (biased towards the witchpoint-planet route) and set that as the waypoint. Otherwise, if the ship is on a lane already, pick one end of the lane at random. Otherwise, pick the planet.<br />
<br />
Set a waypoint within 7500m of the witchpoint, 2 radii of the centre of the planet, or 2.5 radii of the centre of the sun.<br />
<br />
==== <code>waypointsStationPatrol</code> ====<br />
function '''waypointsStationPatrol'''()<br />
If the ship has a station as its group leader, define waypoints from that station. Otherwise define them from the main station. If there is no main station either, set the witchpoint as the waypoint.<br />
<br />
If there is a station, pick four points describing a square of diagonal length 50km centred on the station and lying in the station's xy plane. If the ship is not within 500 metres of any of these points, select one of the points as the waypoint. Otherwise, select the next point around the list as the waypoint.<br />
<br />
==== <code>waypointsWitchpointPatrol</code> ====<br />
function '''waypointsWitchpointPatrol'''()<br />
<br />
Pick four points describing a square of diagonal length 30km centred on the witchpoint and lying approximately in the system's xy plane. If the ship is not within 500 metres of any of these points, select one of the points as the waypoint. Otherwise, select the next point around the list as the waypoint.<br />
<br />
== Global Configuration ==<br />
All PriorityAIControllers share a single communications message library. This library may be edited using functions in the priority AI worldscript<br />
<br />
=== Usage ===<br />
<br />
When a key is asked for, the communications library will be checked in the following order:<br />
# for a key with the specified role and personality<br />
# if the role does not start with "_", a key with the specified personality and the role "generic"<br />
# if the personality does not start with "_", a key with the specified role and the personality "generic"<br />
# if neither role nor personality start with "_", a key with "generic" role and personality.<br />
In general, setting keys for the generic role (and especially with a generic personality as well) should be used with caution.<br />
<br />
The key's value is then expanded using expandDescription (possibly with added parameters), so entries in [[descriptions.plist]] may be used to add variety to the communications. Alternatively, a static text string also works as the value.<br />
<br />
==== Standard Communications Keys ====<br />
<br />
The following communications keys are currently defined in standard Oolite, but you can define more. Those with a parameter of Ship can have a Ship object passed to them, which will be replaced with definitions for the parameters "oolite_entityClass", "oolite_entityCrew" and "oolite_entityName".<br />
<br />
===== oolite_agreeingToDumpCargo =====<br />
Parameter: "oolite_demandSize" (size of demand in TC)<br />
Priority: 1<br />
Used when a ship dumps cargo to satisfy a pirate demand<br />
<br />
===== oolite_attackLowEnergy =====<br />
Parameter: Ship,<br />
Priority: 2<br />
Used when requesting help as under attack and close to death<br />
<br />
===== oolite_beginningAssassination =====<br />
Parameter: Ship, plus "oolite_entityContracts" parameter<br />
Priority: 3<br />
Used when commencing a fight with the Ship defined in the parameter, like [[#oolite_beginningFight|oolite_beginningFight]], but specifically for an assassination target. The extra communications parameter contains the name of a passenger (or parcel owner) relevant to this ship (for the player, this may intentionally be someone for whom delivery has been completed - either it's a revenge hit, or they're just working from outdated intelligence)<br />
<br />
===== oolite_beginningAttack =====<br />
Parameter: Ship<br />
Priority: 3<br />
Used when commencing an attack on the Ship defined in the parameter.<br />
<br />
===== oolite_beginningAttackInanimate =====<br />
Parameter: Ship<br />
Priority: 3<br />
Used when commencing an attack on the Ship (expected to be an uncrewed object like an asteroid, cargo pod, etc.) defined in the parameter.<br />
<br />
===== oolite_beginningAttackThargoid =====<br />
Parameter: Ship<br />
Priority: 3<br />
Used when commencing an attack on the Ship (expected to be a Thargoid ship) defined in the parameter.<br />
<br />
===== oolite_beginningFight =====<br />
Parameter: Ship<br />
Priority: 3<br />
Used when commencing a fight with the Ship defined in the parameter. (Beginning Attack means attacking a target previously not under attack but which there may have been a reason to fight from previous combats; Beginning Fight is stronger - this ship is initiating hostilities)<br />
<br />
===== oolite_continueFleeing =====<br />
Parameter: Ship<br />
Priority: 4<br />
Used when the ship has been unable to reach safety from its attacker.<br />
<br />
===== oolite_continuingAttack =====<br />
Parameter: Ship<br />
Priority: 4<br />
Used when continuing an attack on the Ship defined in the parameter (the low priority means this is relatively rarely used, of course)<br />
<br />
===== oolite_continuingAttackInanimate =====<br />
Parameter: Ship<br />
Priority: 4<br />
Used when continuing an attack on the Ship (if likely to be uncrewed) defined in the parameter (the low priority means this is relatively rarely used, of course)<br />
<br />
===== oolite_continuingAttackThargoid =====<br />
Parameter: Ship<br />
Priority: 4<br />
Used when continuing an attack on the Ship (if Thargoid) defined in the parameter (the low priority means this is relatively rarely used, of course)<br />
<br />
===== oolite_distressResponseAggressor =====<br />
Parameter: Ship<br />
Priority: 2<br />
Used to threaten the ship a distress call has been sent about.<br />
<br />
===== oolite_distressResponseSender =====<br />
Parameter: Ship<br />
Priority: 2 or 3<br />
Used to reassure a ship sending a distress call that help is on the way. [[#oolite_distressResponseAggressor|oolite_distressResponseAggressor]] is preferred - this will only be used if the ship sending the message is near the sender but not the aggressor.<br />
<br />
===== oolite_dockingWait =====<br />
Parameter: none<br />
Priority: 4<br />
Used when a ship is waiting in a docking queue.<br />
<br />
===== oolite_eject =====<br />
Parameter: none<br />
Priority: 1<br />
Used when a ship launches an escape pod (the communication comes from the ship, not the pod, as the pod is being launched)<br />
<br />
===== oolite_engageWitchspaceDrive =====<br />
Parameter: none<br />
Priority: 4<br />
Used when a lone ship is beginning its witchspace entry sequence, and is expected to enter witchspace in around 15 seconds.<br />
<br />
===== oolite_engageWitchspaceDriveFlee =====<br />
Parameter: none<br />
Priority: 2<br />
Used when a ship is preparing to escape from a fight by making a witchspace jump<br />
<br />
===== oolite_engageWitchspaceDriveGroup =====<br />
Parameter: none<br />
Priority: 4<br />
Used when a grouped ship is beginning its witchspace entry sequence, and is expected to enter witchspace in around 15 seconds.<br />
<br />
===== oolite_escortAccepted =====<br />
Parameter: Ship<br />
Priority: 2<br />
Used when a ship accepts a new escort. The new escort will be passed as the parameter.<br />
<br />
===== oolite_escortFormation =====<br />
Parameter: Ship<br />
Priority: 4<br />
Used when a ship is entering or maintaining escort formation. The mothership will be passed as the parameter.<br />
<br />
===== oolite_escortMotherAccepted =====<br />
Parameter: Ship<br />
Priority: 2<br />
Used when a ship is accepted as a new escort. The ship being escorted will be passed as the parameter.<br />
<br />
===== oolite_firedMissile =====<br />
Parameter: Ship<br />
Priority: 4<br />
Used when firing a missile. The target of the missile will be passed as the parameter.<br />
<br />
===== oolite_friendlyFire =====<br />
Parameter: Ship<br />
Priority: 2, 3 or 4 depending on circumstances<br />
Used when a ship is hit by weapons fire from another ship it considers "on its side" either because of common group or because of similar roles.<br />
<br />
===== oolite_groupIsOutnumbered =====<br />
Parameter: none<br />
Priority: 2 if group leader, 4 otherwise<br />
Used when a ship realises it is in a fight with a group which seriously outclasses it, and therefore should flee.<br />
<br />
===== oolite_hitTarget =====<br />
Parameter: Ship<br />
Priority: 4<br />
Used when the ship hits its target. The target is passed as the parameter.<br />
<br />
===== oolite_incomingMissile =====<br />
Parameter: Ship<br />
Priority: 3<br />
Used when the ship has had a missile launched at it and is unable to use ECM. The missile is passed as the parameter.<br />
<br />
===== oolite_killedAlly =====<br />
Parameter: Ship<br />
Priority: 3<br />
Used when the ship destroys an allied ship. The target is passed as the parameter.<br />
<br />
===== oolite_killedTarget =====<br />
Parameter: Ship<br />
Priority: 2 (3 for stations)<br />
Used when the ship destroys its current target. The target is passed as the parameter.<br />
<br />
===== oolite_killedNonTarget =====<br />
Parameter: Ship<br />
Priority: 3<br />
Used when the ship destroys something other than its current target. The target is passed as the parameter.<br />
<br />
===== oolite_killedUncrewedTarget =====<br />
Parameter: Ship<br />
Priority: 3 (4 for stations)<br />
Used when the ship destroys an uncrewed object which is its current target. The target is passed as the parameter.<br />
<br />
===== oolite_killedUncrewedNonTarget =====<br />
Parameter: Ship<br />
Priority: 3 (4 for stations)<br />
Used when the ship destroys an uncrewed object other than its current target. The target is passed as the parameter.<br />
<br />
===== oolite_landingOnPlanet =====<br />
Parameter: none<br />
Priority: 4<br />
Used when beginning final landing approach to a planet.<br />
<br />
===== oolite_launchDefenseShips, oolite_launchMiner, oolite_launchPatrol, oolite_launchSalvager =====<br />
Parameter: Ship<br />
Priority: 3<br />
Used when a station launches a ship of a particular type. The parameter is the station's current target.<br />
<br />
===== oolite_leaveVicinity =====<br />
Parameter: Ship<br />
Priority: 3<br />
Used when a ship is executing [[#behaviourLeaveVicinityOfDestination|behaviourLeaveVicinityOfDestination]]. The parameter is the current target.<br />
<br />
===== oolite_makeDistressCall =====<br />
Parameter: Ship<br />
Priority: 2<br />
Used as the message when a distress call is sent. The parameter is the ship's primary aggressor.<br />
<br />
===== oolite_makePirateDemand =====<br />
Parameter: Ship and "oolite_demandSize"<br />
Priority: 1<br />
Used when making a piracy demand on a ship. The Ship parameters are from the ship being robbed.<br />
<br />
===== oolite_markForFines =====<br />
Parameter: Ship<br />
Priority: 1<br />
Used when a police ship is marking another ship for fines on docking. The parameter is the ship being marked.<br />
<br />
===== oolite_mining =====<br />
Parameter: none<br />
Priority: 4<br />
Used when carrying out mining activity<br />
<br />
===== oolite_newAssailiant =====<br />
Parameter: Ship<br />
Priority: 3<br />
Used when the ship is attacked by someone not previously considered hostile. The attacker is the parameter.<br />
<br />
===== oolite_offenceDetected =====<br />
Parameter: Ship<br />
Priority: 3 if this increases the aggressor's bounty, 4 otherwise<br />
Used when a police ship detects illegal hostilities. The parameter is the aggressor.<br />
<br />
===== oolite_patrolReportIn =====<br />
Parameter: Ship<br />
Priority: 4<br />
Used when a station patrol ship reaches a waypoint. The parameter is its parent station.<br />
<br />
===== oolite_quiriumCascade =====<br />
Parameter: none<br />
Priority: 3<br />
Used when a quirium cascade or an imminent cascade is detected.<br />
<br />
===== oolite_scoopedCargo =====<br />
Parameter: "oolite_goodsDescription" is a description of the cargo commodity<br />
Priority: 4<br />
Used when this ship scoops cargo.<br />
<br />
===== oolite_selectedStation =====<br />
Parameter: Ship<br />
Priority: 4<br />
Used when a ship selects a station to navigate to (e.g. traders, shuttles). The parameter is the selected station.<br />
<br />
===== oolite_selectedWitchspaceDestination =====<br />
Parameter: "oolite_witchspaceDestination" is the name of the destination system<br />
Priority: 4<br />
Used when a ship selects its witchspace destination.<br />
<br />
===== oolite_startFleeing =====<br />
Parameter: Ship<br />
Priority: 3<br />
Used when a ship begins fleeing combat, with the parameter being the ship's current target.<br />
<br />
===== oolite_startHelping =====<br />
Parameter: Ship<br />
Priority: 4<br />
Used when a ship responds to a request for help from another grouped ship by changing its target. The parameter is the new target.<br />
<br />
===== oolite_surrender =====<br />
Parameter: none<br />
Priority: 3<br />
Messages sent by fleeing ships still being fired upon, in attempt to beg for mercy. [[#oolite_agreeingToDumpCargo|oolite_agreeingToDumpCargo]] is used instead in the one case in the core game where an attacker might accept a surrender (as opposed to breaking off an attack on a fleeing ship to attack a non-fleeing one)<br />
<br />
===== oolite_thanksForHelp =====<br />
Parameter: Ship<br />
Priority: 1 if thanking the player, 3 otherwise<br />
This message is sent if an attack on this ship's aggressor causes it to break off its own attack. The parameter is the ship helping out.<br />
<br />
===== oolite_thargoidAttack =====<br />
Parameter: Ship<br />
Priority: 2<br />
This message is sent if the ship is attacked by a Thargoid ship while not previously fighting Thargoids. The parameter is the Thargoid ship. This is generally accompanied by a quick cessation of hostilities between Cooperative vessels for a short-term truce against the invaders.<br />
<br />
===== oolite_waypointReached =====<br />
Parameter: none<br />
Priority: 3<br />
This message is sent when a ship reaches a waypoint set with the waypoint generator function.<br />
<br />
===== oolite_witchspaceBlocked =====<br />
Parameter: Ship<br />
Priority: 3<br />
This message is sent when a large nearby mass (usually a station or asteroid) prevents witchspace entry. The parameter is the blocking mass.<br />
<br />
==== Standard Communications Roles ====<br />
<br />
The following communications roles are used by the standard Oolite AIs. Some of the roles have fallback roles used by the standard AIs, noted below. If the fallback role does not exist, or is not specified, it will fall back to using "generic" as usual.<br />
<br />
Note that OXP AIs might not specify the same fallback roles. OXP AIs wishing to can use code like<br />
<br />
if (worldScripts["oolite-libPriorityAI"]._getCommunicationPersonalities("hermit").length > 0)<br />
{<br />
ai.setCommunicationsRole("hermit");<br />
}<br />
else<br />
{<br />
ai.setCommunicationsRole("station");<br />
}<br />
<br />
* '''assassin''' - assassins<br />
* '''defenseShip''' - defense ships<br />
* '''escapepod''' - escape pods<br />
* '''escort''' - escorts<br />
* '''hermit''' - rock hermits. If no personalities are defined for this role, "station" will be used instead.<br />
* '''hunter''' - bounty hunters<br />
* '''pirate''' - pirates<br />
* '''pirate-aegis-raider''' - pirates showing off by attacking the main station. If no personalities are defined for this role, "pirate" will be used instead.<br />
* '''pirate-freighter''' - pirate freighters leading a pack. If no personalities are defined for this role, "pirate" will be used instead.<br />
* '''pirate-interceptor''' - pirates assigned to distract police and hunters. If no personalities are defined for this role, "pirate" will be used instead.<br />
* '''police''' - police ships<br />
* '''scavenger''' - scavengers and miners.<br />
* '''shuttle''' - orbital shuttles (usually unarmed)<br />
* '''station''' - stations.<br />
* '''trader''' - traders<br />
* '''trader-courier''' - couriers. If no personalities are defined for this role, "trader" will be used instead.<br />
* '''trader-opportunist''' - opportunistic traders. If no personalities are defined for this role, "trader" will be used instead.<br />
* '''trader-smuggler''' - smugglers. If no personalities are defined for this role, "trader" will be used instead.<br />
<br />
Thargoids are set slightly differently: all the core game ones get the "_thargoid" role, with the warships getting the "thargoid" personality, and the drones getting the "tharglet" personality, even if those personalities are not otherwise defined. Note that the underscore in the role prevents fallback to "generic" messages here.<br />
<br />
=== Methods ===<br />
<br />
==== _getCommunication ====<br />
function '''_getCommunication'''(role : String, personality : String, key : String) : StringOrFunction<br />
This function returns either a string suitable for passing to <code>expandDescription</code> containing the communications for the specified key, or a function called with key and parameters returning a communications string, if a ship of the specified role and personality is speaking.<br />
<br />
==== _getCommunicationPersonalities ====<br />
function '''_getCommunicationPersonalities'''(role : String) : Array<br />
Returns the personalities which have at least one communication key defined for the given role.<br />
<br />
==== _setCommunication ====<br />
function '''_setCommunication'''(role : String, personality : String, key : String, value : StringOrFunction)<br />
This function sets the communications values returned by [[#_getCommunication|getCommunication]]. The value may either be:<br />
* a String, which will be passed to expandDescription<br />
* a Function, which will be called with two parameters: the key, and the parameters object.<br />
<br />
For example<br />
worldScripts["oolite-libPriorityAI"]._setCommunication("myoxp_role","generic",<br />
"oolite_continuingAttack","[myoxp_role_continuesAttack]");<br />
worldScripts["oolite-libPriorityAI"]._setCommunication("myoxp_role","generic",<br />
"oolite_continuingAttack",function(k,p) { return "Targeting the "+p.oolite_entityName+". Cover me."; });<br />
<br />
==== _setCommunications ====<br />
function '''_setCommunications'''(comms : Object)<br />
This function can be used to set multiple communications keys at once. The format of the object is<br />
comms[role][personality][key] = value;<br />
<br />
[[Category:Oolite JavaScript Reference]]</div>Cimhttps://wiki.alioth.net/index.php?title=Hud.plist&diff=46567Hud.plist2015-01-19T21:31:36Z<p>Cim: /* data_source */ More notes</p>
<hr />
<div>'''hud.[[plist]]''' and '''hud-small.[[plist]]''' are two different HUDs used by Oolite. They provide Oolite with the information necessary to display the players hud. The 'hud-small' is used on ships like the Cobra MkI and the Adder, while the 'hud.plist' is the standard default Cobra MkIII hud. The main difference lies in their width. 'hud-small' is smaller (narrower) than 'hud', to help you imagine a smaller cockpit in a smaller ship.<br />
<br />
== allow_big_gui ==<br />
In Oolite 1.81 and onwards this is a statement that there is nothing in the lower part of the screen (-256 <= x <= -160 , -256 <= y <= 256) when GUI screens are being displayed. Currently this allows the mission screen to take up 27 text rows instead of 21, which previously required the HUD to be hidden entirely.<br />
<br />
This setting is not validated by the game. Setting this to 'yes' when the HUD does in fact use that space may end up looking very messy.<br />
<br />
The default value is no.<br />
<br />
Example:<br />
allow_big_gui = yes;<br />
<br />
== cloak_indicator_on_status_light ==<br />
This key determines if the statuslight also should show the cloaked status.<br />
<br />
Example:<br />
cloak_indicator_on_status_light = yes;<br />
<br />
== crosshair_scale ==<br />
Affects the size of the crosshair. (default 32.0)<br />
<br />
Example:<br />
crosshair_scale = 32.0;<br />
<br />
== crosshair_width ==<br />
Affects the width of the crosshair. (default 1.5)<br />
<br />
Example:<br />
crosshair_width = 1.5;<br />
<br />
== crosshair_color ==<br />
Affects the color of the crosshair. color can be a [[Materials_in_Oolite#Named_colours|named color]] or any of the other [[Materials_in_Oolite#Colour_specifiers|Colour_specifiers]]. (Default is greenColor)<br />
<br />
Example:<br />
crosshair_color= "greenColor";<br />
<br />
== crosshairs ==<br />
This entry contains a directory with crosshairs that overrides those defined in the internal [[crosshairs.plist]]<br />
<br />
Example:<br />
crosshairs = {<br />
WEAPON_BEAM_LASER =<br />
(<br />
(0.25, 0.25, 1.0, 0.75, 0.0, 0.50),<br />
(0.25, 0.25, -1.0, 0.75, 0.0, -0.50),<br />
(0.25, 1.0, 0.25, 0.75, 0.50, 0.0),<br />
(0.25, -1.0, 0.25, 0.75, -0.50, 0.0),<br />
(0.25, -0.25, 1.0, 0.75, 0.0, 0.50),<br />
(0.25, -0.25, -1.0, 0.75, 0.0, -0.50),<br />
(0.25, 1.0, -0.25, 0.75, 0.50, 0.0),<br />
(0.25, -1.0, -0.25, 0.75, -0.50, 0.0)<br />
);<br />
}<br />
<br />
== crosshair_file ==<br />
(Oolite 1.77 or later)<br />
This entry names an external crosshairs plist file that defines the default crosshairs for this HUD. If this is specified at the same time as the <code>crosshairs</code> property, then <code>crosshair_file</code> takes precedence.<br />
<br />
== dials ==<br />
The dials are listed here as an array of individual dials. Each dial is a separate directory. Some examples are:<br />
{<br />
"equipment_required" = "EQ_SCANNER_SHOW_MISSILE_TARGET";<br />
selector = "drawTargetReticle:";<br />
},<br />
{ // scanner<br />
selector = "drawScanner:";<br />
alpha = 1.0;<br />
x = 0;<br />
y = 60;<br />
y_origin = -1;<br />
height = 72.0;<br />
width = 288.0;<br />
rgb_color = (1.0, 0.0, 0.0);<br />
},<br />
{ // energy bars<br />
"draw_surround" = yes;<br />
height = 48;<br />
selector = "drawEnergyGauge:";<br />
width = 80;<br />
x = 200;<br />
y = 35;<br />
"y_origin" = "-1";<br />
labelled = yes;<br />
n_bars = 3;<br />
}<br />
<br />
=== selector ===<br />
The selector is a hardcoded name, like: drawTargetReticle:, drawScanner:, drawScannerZoomIndicator:, drawStickSensitivityIndicator:, drawCompass:, drawAegis:, drawScoopStatus:, drawSpeedBar:, drawRollBar:, drawPitchBar:, drawYawBar:, drawEnergyGauge:, drawForwardShieldBar:, drawAftShieldBar:, drawYellowSurround:, drawGreenSurround:, drawFuelBar:, drawCabinTempBar:, drawWeaponTempBar:, drawAltitudeBar:, drawMissileDisplay:, drawStatusLight:, drawClock:, drawWeaponsOfflineText: or drawFPSInfoCounter:<br />
<br />
1.79 also adds:<br />
drawWaypoints:, drawPrimedEquipment:, drawASCTarget:, drawWitchspaceDestination:<br />
<br />
1.81 also adds:<br />
drawSurround: (like drawYellowSurround: but allows a "color" attribute to be specified),<br />
drawCustomBar:, drawCustomIndicator:, drawCustomText:, drawCustomLight:, drawCustomImage:<br />
<br />
=== align ===<br />
In 1.79, for the "drawASCTarget:" selector, right-aligns the text to the X coordinate rather than the standard left alignment.<br />
<br />
=== alpha ===<br />
alpha is the transpacency of the dial ranging from 0 to 1.<br />
<br />
=== alert_conditions ===<br />
In Oolite 1.79 or later, this controls which alert conditions the dial appears at. It is a number from 0 to 15, formed by adding together the numbers for the individual alert conditions - 1=docked, 2=green, 4=yellow, 8=red. For example, a dial which only appeared at yellow and red alert condition would have<br />
alert_conditions = 12;<br />
<br />
The default value, which reflects previous behaviour, is 15 (show at all conditions)<br />
<br />
=== color* ===<br />
From Oolite 1.79 there are several color parameters - <code>color, color_low, color_medium, color_high, color_critical, color_surround</code> for influencing the following dials.<br />
* '''drawSpeedBar''': color_low, color_medium, color_high, color_surround<br />
* '''drawRollBar/drawPitchBar/drawYawBar''': color, color_surround<br />
* '''drawEnergyGauge''': color_low, color_medium, color_surround<br />
* '''drawForwardShieldBar/drawAftShieldBar''': color_low, color_medium, color_high, color_surround<br />
* '''drawFuelBar''': color_low, color_medium, color_high, color_surround<br />
* '''drawCabinTempBar''': color_low, color_medium, color_high, color_critical, color_surround<br />
* '''drawAltitudeBar''': color_low, color_medium, color_high, color_critical, color_surround<br />
* '''drawCustomBar''': color_low, color_medium, color_high, color_surround<br />
In general, low, medium and high represent ranges of the size of the bar (with critical for particularly dangerous levels on some dials). On the fuel bar, 'medium' is used for the bar itself, while 'high' and 'low' are used for the distance marker for the current destination system.<br />
<br />
All of these parameters accept any standard format of color specifier.<br />
<br />
=== data_source ===<br />
(1.81 or later)<br />
<br />
The data key set with [[Oolite_JavaScript_Reference:_PlayerShip#setCustomHUDDial|player.ship.setCustomHUDDial]]. Different custom selectors expect different values:<br />
* drawCustomBar: - a number between 0 and 1<br />
* drawCustomIndicator: - a number between -1 and 1<br />
* drawCustomLight: - any valid colour specifier (e.g. "greenColor" or [0.0,0.5,1.0,1.0])<br />
* drawCustomText: - a string<br />
* drawCustomImage: - a string, matching the filename of an image in the Images folder. Note that width and height can but do not need to be set on this dial. If they are set, all images will be scaled to that size. If they are not set, images will appear at their natural size. The image, like legend images, will be centred on the x and y coordinates.<br />
<br />
=== draw_surround ===<br />
A box is drawn around the dial when set to 'yes'.<br />
<br />
=== equipment_required ===<br />
The dials is only drawn if the required equipment is present.<br />
<br />
=== height ===<br />
The height of the dial.<br />
<br />
=== labeled ===<br />
Adds bank numbers to the energy banks. Does nothing for other dials.<br />
<br />
=== n_bars ===<br />
For "drawEnergyGauge:", determines how many energy banks are drawn. Without this key, the system chops the total energy in banks with a minimum of 64 units for each bank. (more precisely: n_bars = integer(maxEnergy/64) )<br />
<br />
For "drawPrimedEquipment:", if this is set to >1 (odd numbers may be better than even) also shows some previous and next primable equipment in the cycle.<br />
<br />
Ignored for other dials.<br />
<br />
=== rgb_color ===<br />
Determines the color of some dials.<br />
Example:<br />
rgb_color = (1.0, 0.0, 0.0);<br />
<br />
=== reticle_scale ===<br />
(1.79 or later)<br />
<br />
Determines the minimum proportion of the screen taken up by the targeting reticle in 'drawTargetReticle' and the waypoint indicator in 'drawWaypoints'. Does nothing for other dials<br />
<br />
=== spacing ===<br />
Determines spacing between the missile icons in the 'drawMissileDisplay'. Does nothing for other dials.<br />
<br />
=== viewscreen_only ===<br />
(1.81 or later)<br />
<br />
If this is set to true, then the HUD dial will only be displayed when looking at space (internal or external view) and not on GUI screens such as the market or the charts. This should generally be set for any dial positioned with 'x' between -256 and +256 and 'y' between -160 and +256, as otherwise they will overlap the GUI text.<br />
<br />
=== x ===<br />
x is the x-position of the dial on screen.<br />
<br />
=== y ===<br />
y is the y-position of the dial on screen. <br />
<br />
=== x_origin ===<br />
x_origin = 1.0 means that the x co-ordinate is interpreted relative to the right hand side of the screen. If x_origin is set to 0 or unspecified, then x is interpreted relative to the middle of the screen. x_origin = -1.0 means that the x co-ordinate is interpreted relative to the left hand side of the screen.<br />
N.B. it is preferable to define hud elements relative to the screen borders, so that hud elements fit better on all height/width ratio screens. <br />
<br />
=== y_origin ===<br />
y_origin = -1.0 means that y is relative to the screen bottom. If y_origin is set to 0 or unspecified, then y is interpreted relative to the middle of the screen , and similarly for y_origin. y_origin = 1.0 means that the y co-ordinate is interpreted relative to the top of the screen.<br />
<br />
=== width ===<br />
The width of the dial.<br />
<br />
== legends ==<br />
The legends are listed here as an array of individual legends. Each legends is a separate directory. The legends looks for example like:<br />
legends = (<br />
{<br />
text = "FWD";<br />
align = 1;<br />
x = -245;<br />
y = 86;<br />
y_origin = -1;<br />
height = 12;<br />
width = 12;<br />
with_dial = "drawForwardShieldBar:";<br />
}, <br />
{<br />
image = "myImage.png";<br />
x = -164;<br />
y = 72;<br />
y_origin = 1;<br />
height = 40;<br />
width = 40;<br />
alpha = 0.5;<br />
}<br />
)<br />
<br />
"text" is the text to be displayed, while "image" is a texture file to be shown. If both are specified, "image" is used.<br />
<br />
"alpha", "viewscreen_only" (1.81 onwards), "x", "y", "x_origin" and "y_origin" have the same meaning as on the dials. "height" and "width" control the height and width of the text characters (and should generally be the same number). "align", on a text dial, can be set to 1 to right-align the text (as with the "drawASCTarget:" dial) from 1.79 onwards.<br />
<br />
"with_dial" in 1.79 onwards indicates that this legend should only be shown if the corresponding dial is [[Oolite_JavaScript_Reference:_PlayerShip#hideHUDSelector|visible]]<br />
<br />
In 1.81, the "color" property of a legend may be set. In previous versions text legends are always green.<br />
<br />
== multi_function_displays ==<br />
In 1.79 or later the multi-function displays are listed here as an array. Each entry is a dictionary of parameters<br />
multi_function_displays = (<br />
{<br />
width = 198;<br />
height = 132;<br />
x = -156;<br />
y = -72;<br />
y_origin = 1;<br />
},<br />
{<br />
width = 198;<br />
height = 132;<br />
x = 156;<br />
y = -72;<br />
y_origin = 1;<br />
}<br />
);<br />
<br />
In 1.81 or later the "color" property is also available to change them from green if this suits the HUD better.<br />
<br />
== overall_alpha ==<br />
The overall tranparency of the hud can be set with overall_alpha.<br />
<br />
Example:<br />
overall_alpha = 0.75;<br />
<br />
== reticle_target_sensitive ==<br />
This key determines if the reticle should become red when on-target.<br />
<br />
Example:<br />
reticle_target_sensitive = no;<br />
<br />
== comm_log_gui ==<br />
Determines the location and the specifications of the comm_log_gui and contains a directory of keys.<br />
<br />
Example:<br />
<br />
"comm_log_gui" = {<br />
alpha = "0.75";<br />
width = 360;<br />
height = 100;<br />
x = 0;<br />
y = 180;<br />
row_height = 12;<br />
permanent = no;<br />
automatic = yes;<br />
background_rgba = "0.0 0.05 0.45 0.5"; // = default color<br />
};<br />
<br />
== message_gui ==<br />
Determines the location and the specifications of the message_gui and contains a directory of keys.<br />
<br />
Example:<br />
<br />
"message_gui" = {<br />
alpha = "0.75";<br />
width = 480;<br />
height = 160;<br />
x = 0;<br />
y = "-40";<br />
"row_height" = 16;<br />
};<br />
<br />
<br />
--------------------------------------------------------------------------------<br />
[[Category:Oolite]]<br />
[[Category:Oolite scripting]]</div>Cim