Elite Wiki - User contributions [en]

File:LitF+v0.06.oxz

2022-12-15T18:30:33Z

Massively Locked: dev ver 0.06

== Summary ==
dev ver 0.06

User talk:Massively Locked

2022-11-29T22:41:06Z

Massively Locked: /* The Programming Pages (General) */ reply

I wuz told to come here to tawk. Why the hell is it so dark in here? 
<Stumbles around. Stubs toe on a wiki> 
'''Ouch! Damn it!''' People shouldn't leave ''wikis'' just lying around... 
<Click> 
Much better. Wow- very roomy. Let's see what I can fill this with...
==In the beginning...==
And so it begins. But then that should go without saying considering the headline... 
Ahem... To be, or... Damn it- line? 
----
Thank you.
 

== Requests ==
=== setShipInfoForKey ===
Just came across this:
[http://www.aegidian.org/bb/viewtopic.php?p=274534#p274534 setShipInfoForKey] which Tsoj added to Oolite v.1.91 many months ago. His discussion seems to start [http://www.aegidian.org/bb/viewtopic.php?p=274524#p274524 8 posts earlier]

It's not yet on the wiki...

:''Cholmondeley 19:56, 18 October 2022 (BST)''

[[Oolite JavaScript Reference: Ship#setShipDataForKey|Just posted]]. Took me a little while to verify & play around with it.

:[[User:Massively Locked|Massively Locked]] ([[User talk:Massively Locked|talk]]) 04:03, 19 October 2022 (BST)

Thank You!
:''Cholmondeley 10:07, 19 October 2022 (BST)''

=== Escorts ===
I added some gubbins to [[https://wiki.alioth.net/index.php?title=Escort_Instructions&action=history|Escort Instructions]] - my dumb pilot understanding of it is that the page purely deals with ships being protected by escorts, all of which are NPC's.

I added some links to OXP's which allow the player to escort other ships.

Can you please just run your eye over it to see that I didn't get the wrong end of the stick? Thank you!

:''Cholmondeley 17:12, 20 October 2022 (BST)''

OK- here's my suggestion:

For the line: ''Only for ships added with the role 'trader'...''

Change it to something like this: ''Prior to v1.79, for "mother" ships added with the role 'trader'...''

After that sentence, add something like this: ''From v1.79 onwards, Oolite allows more flexibility in the type and number of ships escorting the "mother" ship.''

The '''Escorting ''other'' ships''' section looks good and (to me, at least) is entirely appropriate!
:[[User:Massively Locked|Massively Locked]] ([[User talk:Massively Locked|talk]]) 18:22, 20 October 2022 (BST)

----
== The Programming Pages (General) ==
Just to recap from our conversation last week,

1) I feel that more examples are needed in our programming pages - as proved by your answer to [http://www.aegidian.org/bb/viewtopic.php?p=287634#p287634 Reval on checking ship equipment].

2) I also feel that several worked examples of Javascript code, explaining "which bit of code is what" and commenting on the syntax (,_;==) would be of great use to us dumb pilots. Hence my bizarre pm with all the pictures of medieval commentaries! I'm not sure that one can do this on a wiki page...

Also, I stumbled across [http://www.aegidian.org/bb/viewtopic.php?f=2&t=2619 ''this''] which I've added here ([[The Dark Side]]) under "Understanding what really goes on". I don't know if you might want to refer to it in your essay. This dumb pilot found it most informative. The fourth thing I have found informative (after your essay, Ahruman's essay and LittleBear's piece) was [http://www.aegidian.org/bb/viewtopic.php?p=278061#p278061 this conversation] with phkb.

:''Cholmondeley 09:52, 29 November 2022 (UTC)''

''Hence my bizarre pm with all the pictures of medieval commentaries!''

:LOL! Yes, that did leave me scratching my head.

''this conversation with phkb''

:I just skimmed it, but it looks like a great thread. I never saw it before- will have to give it a careful read-thru.

We also talked about a guide to the JS reference pages. Someone who's completely new to JS in general and Oolite JS in particular would probably get a migraine just blindly wading thru the pages.

:[[User:Massively Locked|Massively Locked]] ([[User talk:Massively Locked|talk]]) 22:41, 29 November 2022 (UTC)

File:LitF+v0.05.oxz

2022-11-29T21:58:19Z

Massively Locked: dev ver 0.05

== Summary ==
dev ver 0.05

File:LitF+v0.04.oxz

2022-11-24T23:25:39Z

Massively Locked: dev ver 0.04

== Summary ==
dev ver 0.04

User talk:Cholmondely

2022-11-19T20:31:52Z

Massively Locked: /* Comms */ added note

[[File:Cholmondeley Avatar.png|left]]
[[File:Nuitstations.jpg|thumb|right|320px|Nuit was built to allow external docking back in 2010, but the game does not yet allow that. If this could be sorted out, we could emulate more scifi scenarios in Oolite - such as the CJ Cherryh novels]]
[[File:Litf stationmap.png|thumb|right|320px|Life in the Frontier really helps bring the stations to life. But every station seems very similar - and has the identical map. I'd love to help develop this, but lack the skills]]
[[File:Sotl-hyperspace.png|thumb|right|320px|The SOTL Exploration scenario oxp rejigs the hyperspace/witchspace jumps so that they need skill to accomplish. As Cody has opined, it would be nice to add this to the game as a non-scenario oxp. It would also impact on trade and travel due to making the jumps much more dangerous (as in Cherryh's books, for example)]]
::::::::*The top half of this page contains my musings about the game.
::::::::*Then a short reminder for myself of projects needing more work
::::::::*The bottom half is a resource for wiki editors
 
----
== Musings about Oolite: What I would like to see changed ==
:''By in large I am extremely happy with Oolite the way that it is. While I find a number of "faults" in the Vanilla game these are almost all fixed by OXPs. My remaining issues are:''
* Oolite only offers '''2-dimensional''' F6 charts with exactly '''256''' systems in each (thanks to Pleb for working on this one). Ahruman started fixing the 2D thing [https://github.com/JensAyton/OoliteGalaxyExtruder back in 2011] - [http://aegidian.org/bb/viewtopic.php?p=191913#p191913 GG Shinobi's collection] of 3D possibilities for an F7F7 screen
* '''Pocket universes''': the inability to travel from one system to another without using a witchdrive jump
* Planet, sun & moon '''surfaces''' to show on the IFF scanner (Quirum Bombs show up, so why not planet surfaces?)
* The overly-simplified '''prices/economics''' system (thanks to Stranger & Phasted for helping improve things)
* The bizarre [[Distance (Oolite)|distance scales]] (thanks to Redspear for working on sorting this one out!)
* More '''NPC interaction''' (family, friends, Academy chums, engineers, lovers ''etc''.)
* More to do '''outside the ship''': [[Life in the Frontier]] starts addressing this, but has a long way to go!
* More realistic '''dockings'''/launches - including mooring ''outside'' the space stations on pylons (as [[Nuit Space Station OXP|Nuit]] theoretically offers on the lower struts)
* More '''control buttons''' for OXP equipment. For OXP equipment we just have Tab/0/N & ctrl-N to select the equipment; n & b to activate; and the four "controlled" colons to operate MFDs. Personally speaking, I really need another 2 equipment priming buttons and for Autolock & ILS to be made primable rather than automatic and suicidal. Thanks to Milo [http://www.aegidian.org/bb/viewtopic.php?f=6&t=20668 (see #13)] & Phkb for working on this one.
* The ability to add a second player helping run one's ship. See the discussion [http://www.aegidian.org/bb/viewtopic.php?p=274564#p274564 here] (uses for a second monitor) and [http://www.aegidian.org/bb/viewtopic.php?p=275198#p275198 here] (things to do en-route from Witchpoint to Station).

== OXP's which ''really'' change the game ==
* Phkb's [[Hermitage]]. Phkb's [[Ship Configuration]]. Phkb's [[Smugglers]]. Phkb's [[Home System]]. Day's [[Diplomancy]]. Redspear's [[Weapon Laws]]. Norby's [[Telescope]]. The [[Strangers World]] suite.

== OXP's needing work ==
Or - what I'd love to do if I had the skills...
=== Minor Tweaks ===
*MFD's which need tagging for HUDSelector so that they are remembered in the save files:
::[[Advanced System Data MFD]] (Strangers World)
::[[Station Dock Control]] MFD
::[[Ship's Library]] MFD
*[[Mining OXP]] - needs debugging (whizzing asteroids emitting sparks which are undockable with) - looks (to this dumb pilot) like a simple fix

=== Major Tweaks ===
*[[Diplomancy]] needs sorting out: generates massively long lists of peace treaties between just two states... '''This oxp has a lot of potential''' - it would give depth to wars
*[[SW Economy]] mislabels mining worlds as agricultural and their markets are identical, the only difference being in quantities for sale. It would be super to see this sorted out.
*[[Real-Life Economics]] (prices move as you watch) is faulty - the dynamic price changes tend towards zero.
*'''Gsagostinho's station experiments''' [http://www.aegidian.org/bb/viewtopic.php?f=4&t=18977 here]: unfinished - need texturing.
*[[Cloud City OXP]] - (for gas giant planets) - needs finishing & updated textures

=== Lots of work ===
*[[Life in the Frontier]] (fleshes out stations) needs adding to to create more differences between the various stations. '''This oxp has a lot of potential'''
*[[Hotrods OXP]] - (gangs) there is only the one real "gang". It would be super to see the others added and gang warfare between them. And a sensible link between the gangs and the vanilla pirates. Also needs new textures.
*[[Refugee Adder]] - (fleeing refugees) Murgh is hopefully still updating this (2022)
*[[Hathor Trade Station]] - beautiful! Just beautiful! But needs finishing (markets ''etc''.)
*[[Colonization]] - (hollow space station activity) needs texturing and a reason for its existence if the original activity is not created
*[[New Deal]] - (4-polar trade model) needs finishing
*[http://aegidian.org/bb/viewtopic.php?p=287021#p287021 Montana's Monumentally Murderous Modification] (War!) - he's hopefully still working on this (2022)
*[[Galactic Misjump OXP]]: needs inspiration (what might happen?) and coding
:'''Missions'''
*[[Amber Moon Chronicles]] - (aliens!) needs finishing
*Svengali's missions: [[Vector]] & [[Localhero OXP]] need updating, as does McLane's mission, [[Cataclysm OXP]]
*[[TheCollector|The Collector]] - needs more missions

=== Done! ===
*[[Useful MFDs]] needed sorting out ([[Solar Wind Flux]] gauge was faulty, and the .oxp itself [http://www.aegidian.org/bb/viewtopic.php?p=280607#p280607 generates too much rubbish]).
:STOP PRESS: '''DONE!''' Thank you, Dybal!
*[[Strangers World]] moves the stations from Commies, Taxi Galactica, ''etc'' to bizarre locations. But not HIMSN's stations.
:STOP PRESS: '''DONE!''' Thank you, Alnivel!
*I'd dearly love to see the spiderweb jump sequence from [[BGS]] v.1.10.9 added in as an option to the newer BGS.
:STOP PRESS: '''DONE!''' Thank you, Tsoj!
 
----

== For Me: List of my Wiki (WIP) pages under construction ==
*[[Immersion]]
*[[Realism]]
=== Other WIP pages ===
*[[Gameplay and Balance Indicator]]
*Various [[Ulite]] pages

 
----
= Cholly's Library of formatting bits & bobs =

== Format for Table Of Contents ==

If you have three or fewer headings but want to have a TOC, write either the magic word __FORCETOC__ anywhere on the page to make it display at the default location, or __TOC__ at the preferred position.

Or use __NOTOC__ Hides the table of contents (TOC).

----
== Format for Broken-OXP banners ==

----
 
{{Broken-OXP}}
 
----

{{Broken-OXP|This OXP is deprecated and buggy, please use the [[Galactic Navy OXP]] instead if you are using a pre-!.82 version of Oolite}}

----

{{OXPNote|This OXP does ''not'' work on AppleMacs: see BB Discussion below for possible tweaks}}

----
== Format for invisible comments ==

<nowiki>  </nowiki> 
Only visible when editing the page

----
== Format for footnotes ==

The Sun is pretty big.<ref>E. Miller, ''The Sun'', (New York: Academic Press, 2005), 23–25.</ref> The Moon, however, is not so big.<ref>R. Smith, "Size of the Moon", ''Scientific American'', 46 (April 1978): 44–46.</ref>

== Notes ==
<references />

=== Notes on Footnotes ===
:I tried the <ref>, </ref> & <references /> tags, but to no avail. None of them seem to do anything. According to Mediawiki, all this should work...

:Footnoting is currently impossible as the necessary add-on for the wiki has not been loaded into it: ...There are no references on Wikipedia. The <code><nowiki><ref></nowiki></code> tags don't work. Apparently the [https://www.mediawiki.org/wiki/Extension:Cite Cite Extension] has not been installed.

----
== Format for Transclusion ==


{{:Asp-X}}{{:Cobra2}}{{:Sidewinder-X}}

----
== Format for Colours ==

Live long and prosper, and may the Great Bird of the Galaxy bless your planet! [[User:Phoenix| —THE PHOENIX ]]'''[[User_talk:Phoenix|{Talk to me!}]] 01:11, 21 February 2010 (UTC)

 ! 
 ! 
''' ! '''
''' ! '''
''' ! '''
''' ! '''

----

== Format for Size ==
 s '''s''' 
 s '''s''' 
 s '''s''' 
 s '''s''' 
 s '''s''' 

----
== Format for different font ==
These three methods all make a difference: 
1) <tt>Different font!</tt> 
2) {{CodeEx|codeex=This sort of thing seems only to have been used for programming code (2022 note)}} 
3) 
This method (introducing one or more spaces at the beginning of the line) also has consequences for formatting.

----

== Format for Equipment Infobox ==

{{Infobox EquipStats Oolite| title = Wine Cooler OXP
|image =
|equipName = Wine Cooler
|equipCost = 10₢
|equipTL = 1
}}

----

== Format for Collapsible whatnots ==
'''initial text''' 

<div class="mw-collapsible mw-collapsed" data-expandtext="Show older" data-collapsetext="Hide older" style="overflow:auto;">

'''later text!'''

</div>
Lifted from Phkb's [[BroadcastComms MFD]] page

== Format for Quotations ==
{{QuoteText|Text=
I don't really see the need for a timeline or a backstory. 
The way things are is just the way things are; I don't need to know where Earth is, or how human beings got from there (if they did) to where they are now. For me, a large part of the appeal of the game is its vagueness. It's as close to a blank slate as we can get, and it's built to be modded all over the shop to everyone's individual preferences. 
Too much backstory just gets in the way.
|Source=([http://aegidian.org/bb/viewtopic.php?p=273999#p273999 Disembodied])}}

----
== Sandbox ==
----
== Knotty's natty gallery ==
[[File:Screen_Shot_2012-11-04_at_21.22.16.png]] 
[[File:Screen_Shot_2012-11-04_at_21.19.59.png]]
[[File:Screen_Shot_2012-11-04_at_21.18.26.png]] 
[[File:Screen_Shot_2012-11-04_at_21.04.50.png]]

----
== Sandbox ==

== Table for HUD page ==

=== List of HUDs ===
1 Aad HUD
2 Another HUD
3 CB-HUD
4 ChupacabraHUD
5 Coluber HUD CH01
6 CombatHUD
7 Compact HUD
8 CRR-HUD
9 Dangerous HUD
10 DeeperSpace HUD
11 Deepspace HUD
12 Deepspace Retro HUD
13 Dr HUD
14 ExtraLarge HUD
15 Fighter HUD
16 G-HUD
17 Isis HUD
18 KeeperHUD
19 Klepto HUD
20 Large HUD
21 Medusa HUD
22 Mega Walnut Dash HUD
23 MilHUD 4000
24 MilHUD (Military Specification HUD)
25 MillHUD Refit
26 Mod HUD
27 Nova Lux HUD
28 Numeric Style HUDs
29 OrangED HUD
30 Pie Chart Style HUDs
31 Small HUD
32 Smart HUD
33 Sniper Camera System HUD
34 Steampunk HUD
35 SW (CAI/DAI) HUD
36 Trek HUD
37 Venom Cockpit HUD
38 Vimana HUD
39 Wide-Screen HUD
40 Wolfwood HUD
41 Xenon HUD
42 Yet Another HUD
43 Z-GrOovY MiLHUD

=== Considerations ===
Date
Author
Actual speed shown?
Actual Torus speed shown?
Different HUDs for different green/yellow/red conditions/alerts?
Range of alerts shown
Docked HUD?
HUD Selector compatible?
# of MFDs?
Extras? (eg Vimana HUD's cornucopia of goodies, DeeperSpace's Risk Assessment, Xenon HUD's sights, Dangerous HUD's noises).
Precision Joystick Indicator?
Glare filter?
Glare contrast? (for reading HUD in Glare - cf Xenon HUD)
Current Location Display & Current Risk Notifier (Deeper Space HUD)
Distance from Compass target?
Weapons Bay Missile identifier? (ChupacabraHUD)
Extra reticles for other lasers (Xenon)
Choice of Colours? (Dangerous HUD & Xenon HUD)
Choice of Cockpits? (Dangerous HUD)
Natural materials? (Mega Walnut Dash)

== Table ==
== Sortable Table ==
{| class="wikitable sortable" border="1" style="border: 1px solid #cfcfbf; background-color: #f0f0ff; color: #000000; vertical-align: top; text-align: left;"
|-valign="top" bgcolor="#e7e7ff"
! valign="center" style="width: 150px;"|[[Alphabetical Ship List (Oolite)|Ship]]
! style="width: 100px;"|[[Fastest Ships (Oolite)|Max Speed]] (LM)
! style="width: 100px;"|[[Largest Ships (Oolite)|Cargo Capacity]] (TC)
! style="width: 100px;"|[[Expensive Ships (Oolite)|Base Cost]] (CR)
! class="unsortable" style="width: 100px;"|OXP or Standard
! class="unsortable" style="width: 100px;"|Available to Player
! class="unsortable" style="width: 150px;"|Size (metres, W×H×L)
! style="width: 150px;"|Cubic Meters
|-
|[[Firefly]]
|0.755
|35
|775k
|OXP
|Yes
|12 x 11 x 22
|2904
|-
|[[Dragster Mk II]]
|0.610
|0
|570k
|OXP
|Yes
|33 x 9 x 83
|24,651
|-
|[[Dragster Mk I]]
|0.601
|0
|560k
|OXP
|Yes
|33 x 9 x 83
|24,651
|-
|[[Constrictor (Oolite)|Constrictor]]
|0.60
|15
|N/A
|Standard
|No
|54 × 10 × 60
|32,400
|-
|[[A-Wing]]
|0.60
|0
|570k
|OXP
|Yes
|79 × 48 × 122
|462,624
|-
|[[Fer de Lance NG]]
|0.60
|2
|585k
|OXP
|Yes
|45 × 20 × 85
|76,500
|-
|[[Generation_Ships_OXP|Generation Ship]]
|0.60
|0
|N/A
|OXP
|No
|6413 x 6416 x 30277
|1,245,771,628,816
|-
|[[Kestrel]]
|0.555
|8
|675k
|OXP
|Yes
|13 x 3 x 12
|468
|}

== Future wiki work ==
=== New Region Page '''The Lizard's Claw''' ===
Need to sort out what on earth the "|XPosRel=13|YPosRel=61" is all about for the map!
:See [http://www.aegidian.org/bb/viewtopic.php?f=2&t=17175 Light year distance calculation] - especially Phantorgorth's key comment

=== Add in Exposure/Gamma Correction for Oolite v.1.91/2 ==
When the details are added to the wiki, this needs to be linked to it:
:[http://oolite.aegidian.org/bb/viewtopic.php?p=284327#p284327 Link] with pretty pictures

=== Add in limits of Oolite game ===
Somewhere on the BB is a thread with my list of 7 or so derived from Phkb's response and with an a_c comment
*[http://aegidian.org/bb/viewtopic.php?f=2&t=13152 Boarding abandoned ships?] 2012

== Comms ==

Hey-

I have a problem. I'm locked out of my BB account. I tried changing my listed e-mail since it's no longer active. That rendered my BB acct inactive (it sent a registration e-mail to my long-dead e-mail). Could you check with Cody or someone to see if anything can be done?

:::[[User:Massively Locked|Massively Locked]] ([[User talk:Massively Locked|talk]]) 16:40, 19 November 2022 (UTC)

BTW, feel free to delete this section. This is a lovely page & I'd hate to spoil it because I tripped over my own shoelaces.

:::[[User:Massively Locked|Massively Locked]] ([[User talk:Massively Locked|talk]]) 20:31, 19 November 2022 (UTC)

User talk:Cholmondely

2022-11-19T16:40:05Z

Massively Locked: /* Comms */ new section

Life in the Frontier

2022-11-19T05:26:08Z

Massively Locked: /* Download */ Oh no- I'm not taking the entire blame for this :-)

{{OXPNote|Initiated by BeeTLe BeTHLeHeM, then tweaked by [[User:Norby|Norby]], this OXP could do with some more work! All the stations have the same map - they should vary... (the encounters ''do'' vary)}}
[[Image:Litf_stationmap.png|300px|right]]

== Description ==

At the moment, players roleplay their game session, depending on the career they choose, and the events in-flight. But, space stations, on the contrary, are still rather static (without considering OXPs) and act more like a transition between two flights.

So I thought to help stations offer more variety, giving a player the chance to encounter random events while docked, an event that could require a player choice and with effects (good and bad) on the player.

[[File:Life in the Frontier (Park).png|thumb|400px|right]]
[[File:Life in the Frontier (Medical Centre).png|thumb|400px|right]]
[[File:Life in the Frontier (Bar).png|thumb|400px|right|Unfortunate blue text thanks to [[Dangerous HUD]] (blue)!]]
== How it works ==
=== Events ===
When the player is docked at a station, he will find in the F4 screen a new item, '''Disembark from your ship'''. If selected, the OXP will choose a random event from a list, and the player will have to confront it. Some events will be a mere description of something that happens in the vicinity of the player, while others will require choices and decisions, and usually offer multiple resolutions.

The events are categorized depending on various factors: the system government, economy and TL, plus one "generic" category for events that can happen anywhere. Instead the specific categories are intended to create a precise atmosphere, so in dictatorial systems there will be a more oppressive feeling, and in low tech worlds it will possible to see more malfunctioning in systems.

Every category has a defined background - I have taken shots from corridors in old sci-fi movies but I don't know if I can use them, so in case I will remove them. For now consider them as placeholders.

The resolution of an event can include: variation in money, in bounty level, in ship fuel or cargo goods. In these case will be displayed a report screen showing what is changed.

Sometimes the eventuation of an event will require a check on one of those properties, for example to avoid the player losing more money than he actually has!

The player can initiate an event by docking, to initiate another event he will need to leave and dock at another (or the same) station - in this way the mechanic shouldn't be abused.

=== The map ===
One can move around and explore the station, and encounter more events as one does so, both during travel and in, say, the bar. There is something to be found at each location (dust in the bookshop...).

== Changelog ==
<div class="mw-collapsible mw-collapsed" data-expandtext="Show details from the Dark Side" data-collapsetext="Hide details" style="overflow:auto;">
0.7.3
-Disembark is possible after load game in additional stations.
-Fixed step back from life status screen in non-galcop stations.
-Fixed mission.screenID error message in non-galcop stations.

0.7.2
- Fixed bounty clearing at galcop terminal (by Norby).
- Non-galcop stations are limited to the hangar.
- HD BackGrounds OXP is used in life status screen and non-galcop hangar.
- Able to use hd background images made in any resolution (fit to height).

0.7.1
- Fixed action on Museum exit.

0.7
- Completed STORAGE, special location on Docks with restricted access:
25 credits or legal stance <= -25 (friendly with criminals)
- Placed PASSENGERS LOUNGE, special location on Concourse-A
- Placed CHURCH OF THE COSMIC WANDERER, special location on Concourse-B
- Placed BOOKSHOP, special location on Concourse-B
- Placed MUSEUM, special location on Delight Avenue
- Placed FIT CENTER, special location on Olympian Square
- Implemented Station Map, visible from every lobby
- Commander stats and OXP flags are stored as a map (string with format name1=value1,name2=value2,name3=value3...)
instead of an array. This should definitely fix every issue with loading and saving data.
- Placed BRIEFING ROOM, special location on Galcop Precinct.
- Placed DETAINMENT ZONE, special location on Galcop Precinct.
- Placed SOCIAL SERVICES, special location on Galcop Precinct.
- Placed PILOT COURSE ROOM, special location on Galcop Precinct.

- Implemented SOCIAL SERVICES mechanics:
* Player can spend 4 hours doing social services. His reputation will increase of a small amount.
His bounty will decrease of an amount. There's a chance of getting hurt during the work.
In this case the time spent and bounty decrease are reduced.

- Implemented FIT CENTER mechanics:
* The first time the commander visits a Fit Center, he must buy an Universal Fitness Badge for 15cr.
This purchase include a month subscription.
* The subscription can be renewed monthly for 10cr.
* Commander mustn't be wounded or sick to enter the gym.
* Every gym session increase commander strength.
* If commander exercise more than once in two days, a chance of getting wounded while exercising increase.
* If the commander get wounded, he'll must get healed before starting a new gym session.
* If the commander get wounded, the maximum strength cap get lowered of a small amount.
If this amount get very low (it requires a lot of accidents, though...) the commander can't access
the gym anymore until he get a recovering therapy from an hi-tech Medical Center.
* If the commander doesn't go to the gym for more than a week, strength will lower of a small amount after every dock.
* If commander can't access the gym because he has endured too much damage, he can go to a hi-tech system
Medical Center and get into a Recovery Therapy for 400cr. This therapy is available only when the player
has sustained a lot of damage (only in the gym for now).
* The status screen (access from the hangar) report the Universal Fitness expiration status, when the player buys it.

0.6.1
- Fixed corridor background name - this should avoid log warning messages about texture files not found.
- Fixed paytreatment action, MedCenter treatment should give no exception now.
- Deleted useless number from OXP versioning - better late then never. (Current model: MajorVersion.MinorVersion.Fix)

0.1.6 (0.6)
- When accessing the OXP from the F4 screen, the player goes directly to the Hangar.
- The player can display the Commander Status screen from the Hangar.
- Station layout updated following forum discussion on the current design.
- Changed some definitions for station locations.
- Lobby indications are more schematic.
- The Storage location has been promoted to special location.
- Implemented Hotel, moved location to Main Concourse-A because Delight Avenue has already 3 planned locations.
- Implemented the Wild Worlds Virtual Tour, on the Delight Avenue (Recreation Bridge).

0.1.5.1 (0.5.1)
- Fixed check on the variables introduced in 0.1.5.
- Fixed check on varStore array items before setting values.

0.1.5 (0.5)
- Added background to Docks Area;
- Add text snippet for drunken status (along with wounds and sickness);
- Implemented event-checks for "government", "tech" and "economy". The government check can take a list of governments,
separated by "-" character. If the system government is in the list, the check is valid;
- Added events: ROBO-BARD, HUNTERS, DELIRIOUS DROID, COMMERCIAL DROID, SUPERCELEBRITY, LIGHTS MALFUNCTION,
WATER MALFUNCTION, AIR MALFUNCTION, DEFACING KIDS
- "her/him/his" not capitalized anymore;
- Commander stats are saved as a string with comma-separated values rather than 5 missionVariables.
- Game flags are saved as a string with comma-separated values rather than 8 missionVariables.
- Variables still not used aren't loaded anymore from the savegame, and are saved with null values to purge them from the file.
- Refactored method for checks on event/choice requirements: it's now possible to interrogate a parameter with operators
=, !=, <, <=, >, >=. The requirement syntax changes. E.g.: no more credits:500, but credits=500, or credits<500 etc.
- Event text can be present as parameter "text" (static text, always displayed) *OR* as indexed parameters
(text0, text1, text2): in the latter case, it's possible to specify display conditions, with syntax
"condition|text to display". If an indexed text has no condition is considered static (always displayed).
The validated indexed text are concatenated.
- Event property "choiceRequires" has been removed. It has been replaced by "r"(+ choice index), that contains
the facultative requirements for the single choice. If a choice has no requirements (no "r" property),
the choice is always displayed.
- I believe I have removed the end-event resume screen at least one release ago, forgot to write it down.
- To avoid confusion, in the event properties requires and r I don't use the ':' char as separator anymore,
but the equal sign '='.
- Refactored action executions when player select an event or a location choice. There are some differences
in some actions, so I had to differentitate: go (random event) and goNav (navigation), end (random event)
and endNav (navigation).
- Implemented condition if to the events action. Now it's possible to define a condition (or multiple conditions,
comma-separated), and to link it to two results: the "valid condition" and the "else".
I'm going to read again the various random events to introduce conditions when necessary, to streamline the event flow.
Syntax is: if:<conditions>?<actions>;<elseActions>
- I've lost some features (the hotel, the wild world virtual tour and the new Medical Center text),
so I'll have to rethink them in the next days. Actually I have changed the Medicla Center concept,
so the options are always displayed but if the player isn't sick or wounded or drunk the receptionist
will refuse to start the treatment.
- Fixed: the Galcop terminal didn't show the price for cleaning the criminal record.
- The DEFACING KIDS event can enable a flag - eventually the consequence will be shown when the player reach the docks area.

0.1.4 (0.4)
- Code optimization and refactoring. Creation of new js files for common methods, for mission-related methods,
and for inside-station navigation methods.
- Restarted from scratch (taking the old code piece for piece).
- The F4 link shows a literal resume of the player. From this screen, the player can "disembark" from the ship
and wander into the space station.
- "Tubes Stop" locations allow player to move across five different levels. Every level has a theme and
several inner locations. The levels are to be intended as concentric.
- Events are not fired by player anymore. But moving into the station there is a 20% chance (not definitive)
of firing a random event. They act like an intermission, basically.
- Added random snippet (from a list of 20) of texts when at a Tube Stop.

- Added all the events already implemented in 0.1.3 (beside the bar ones)
- Added the bar events: the gossip option has been moved to the "talk with bartender one".
Bartender doesn't give hints about contractors anymore.
- It's possible to clean own criminal record at the Galcop termminal (in the Galcop precinct)
paying a fine of (500cr x current bounty).
- Added the Art Gallery and the art genre random generator.
- Added the Opera House and the music genre random generator.
- Added the Cinema Hall and the movie genre random generator.
- If player is wounded or sick, randomly add short descriptive snippet of text while moving around the station.
- Added a short single-row-status text to show on top of the locations screens.
- Added two backgrounds for the "Tubes".
- Changed "Tube Stop" to "Lift Station", and "Tubes" to "Lift".
The direction is relative, it's not necessary an up-down transport.

- The property background can contain more background file names separated by comma:
the OXP will choose a random background between those specified.
- Added some more backgrounds, I'm trying to add variety and get an "identity" for the various levels.
- Added medical center location: here the player can cure wounds and sickness for a price.
Price and amount of cure changes in relation to system tech level.
The medical center can also rid of drunken status for free, but with a chance for a slight sickness.

- Added health/sickness management, with the following rules being checked every time the player docks to a station:
1) if sickness > 1, chance 10% of worsening (sickness +1);
2) if sickness = 1, chance 10% of healing (sickness = 0);
3) if health > 1, chance 10% of worsening (health + 1);
4) if health = 1, chance 10% of healing (health = 0);
5) if health > 2 and sickness < 2, chance 10% of infection (sickness +1);
6) if health > 2 or sickness > 2, chance 10% of physical shape reduction
- If player has health or sickness in critical conditions (>= 5), has a 50% of pass-out.
In this case he will be automatically transported to the station Medical Center and cured (with system TL limitations).
Player will receive a decrease in reputation (for careless behaviour) and the price of the opeation
will be automatically withdrawn from his account - if he has't enough money his bounty will be
slightly increased (for debt insolvency).

0.1.3 (0.3)
- implemented a time variable for events. It's now possible to define how much time will be spent when executing an event.
Instead of creating a separate property, the variabile is set in the "end:x" command, where x is the time spent
in seconds. So "end:600" means "terminate the event and go forward 10 minutes in time".
Use "end:0" to avoid spending game-time;
- As a general rule for numeric command parameters, two values comma-separated will be interpreted as a range,
and a random number between the specified values will be extracted. This applies even to the time variable above;
- Added a new resolution to the "elixir peddler" event, that use the time variable above;

- implemented the constants $SPECIES_S$ (singular) and $SPECIES_P$ (plural), that set a random species
if requested by the event text. The species value remain fixed until the end of the event;
- implemented the constants $GENDERSUBJ$ (he/she), $GENDEROBJ$ (him/her), $GENDERPOSS$ (his/her).
The random chosen gender remain fixed untile the end of the event.
The gender-values are correlated to maintain coherence throughout the text;
- fixed the text of all the events implemented until now;
- added five "no-events";

- added a new script file (LITF_RPGElements.js) to keep together the RPG-lite functions;
- changed the F4 link in "Visit the station hub": it show a main screen with player current RPG-lite status
(reputation, health, sickness, strength), the link to the random event and something more...;
- added description for all the status variables;
- added arrays of "minor" cargo types to be inserted in missions text: these aren't new cargo types,
they will only be treated as random labels to differentiate the text depending on player reputation;

- The link on the F4 page has been changed to "Visit the station hub" and if selected shows the "main screen";
- The "main screen" displays the player status (a literal description for the LITF variables);
- Added variables: reputation, health (wounds, bruises etc.), sickness, strength (physical shape);
- Added variable: stance. Positive stance = the law; negative stance = the criminals.
Similar to reputation, but to be considered more like "word on the street is";
- Available choices for the "main screen";
* "Take a walk to the Main Concourse". This fires a random event, as before;

- The player won't find the locations (bar, fit center, church, med center) on every system.
I wrote a basic rule to distribute their presence in the galaxy.
The rule is mathematical and based on the system ID, so the final results are fixed - for now only the bar is enabled;
- Re-edited the implemented events to use the variables in effects and requirements;
- Added constant $LIQUORS$ (with an array of 20 liquor random names), $SYSTEM$ (get random system name),
$COMMODITY$ (get random vanilla commodity name), $GOSSIP$ (get a random gossip),
$NAME$ (for random NPC name), $MINORCARGO$ (for transport missions);
- Added flag management (not mission flags), checks and manipulation;
- Added command "time:x", if you don't want to end the events but only to spend time;

- Implemented first version mission generation. It works in two steps. First step: an NPC
(in this case, the bartender) tells the player that another NPC has a job available:
I store data about the NPC name, the system where he is, the type of mission and a
generous time limite to reach him. When the player docks to a station I check if it's
the right station and if the NPC hasn't expired: if everything's good, when the player
enter the main concourse I switch to an alternate event: meeting the NPC, that introduce
the job (a cargo transport), with a destination, a time limit and a type of "minor cargo"
(see above). If the player accepts, I use this data to generate a real mission.
- Removed sickness effect when getting drunk, it's counter-productive.
When I'll implement medical centers, player have the chance to pay to get sober.
For now he can leave the station and dock to another station to rid of the drunkenness.

- Modified the cargo mission management: I don't use specialCargo or awardContract,
but the OXP do the checks and display the page for completing a contract (always from the Main Concourse).
It's not definitive, but it seems to work.
- Added events: CHARMING PARTNER, MUGGING, THE LOST DRUNKARD, MEDICAL CAMP

0.1.2 (0.2)
- enabled the one-event-for-dock flag (it was disabled for showing various events without leaving a station).
- changed the event management, I moved the events data from missionscript.plist to
LITF_ActionsCatalog.js (renamed in LITF_EventsCatalog.js).
In this way I can group everything related to an event in one object
(text, requirements, choices and actions), and eventually I can make them more dynamic;
- renamed property "check" (property-checks that allow the event to happens) in "requires";
- added property "choiceRequires", contains pipe-concatenated string with checks for every event choice
(see check property list) for selecting choices to display under particular circumstances;
use "valid:1" for always display a choice, and "valid:0" to always hide it;
- added events:
GENERIC: charity
GENERIC: alien discussion
- implemented code for replace constants in event/choice text with a random element
from a related array: actually used in the charity event, constant $CHARITY$.

0.1.1 (0.1)
- events category list:
"generic" category
station allegiance (disabled)
system government (gov_0 - gov_7)
system tech level (ltech, htech), values 5-9 are converted to "generic"
system economy (ind, agri), values 3-4 are converted to "generic"
OXP choose a value from an array with the values [ generic, gov_x, tl_x, eco_x]
Maybe in the future I could add as new categories ranges for player rank or player bounty
- specific background picture depending on event category: system government, tech level
(low tech, high tech) and economy (industrial, agricolture). "Generic" events will show
the related system government background;
- event one-click for docking disabled for testing and showing OXP workings;
- passing time for events temporarily disabled: to be reintroduced it as an event property;
- event effects list:
mt_[name]:[value] add [value] to the player ship manifest good identified by [name].
bounty:[value] add [value] to the current player bounty.
fuel:[value] add [value] to the current player ship fuel amount.
credits[value] add [value] to the current player credits.
go:[label] fire the event identified by [label]
end:0 end the event
[value] can be positive or negative. There are checks to avoid negative results or values exceeding cargo space.
- check property list:
mt[name]:[value] check for player ship manifest good identified by [name] >= [value]
mt<[name]:[value] check for player ship manifest good identified by [name] < [value]
fuel:[value] check for player ship fuel amount >= [value]
fuel<:[value] check for player ship fuel amount < [value]
bounty:[value] check for current player bounty >= [value]
bounty<:[value] check for current player bounty < [value]
credits:[value] check for current player credits >= [value]
credits<:[value] check for current player credits < [value]
- added events:
GENERIC: beggar
GENERIC: weird password guy
GENERIC: fire
GENERIC: fire + gossip
GENERIC: shady seller
GENERIC: partygoers
GENERIC: running fugitive
GENERIC: thief
GENERIC: stranded crew (2 variants)
</div>
== License ==
This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License version 4.0.

If you are re-using any piece of this OXP, please let me know by sending an e-mail to norbylite at gmail.com.

Author: BeeTLe BeTHLeHeM

[[File:Life in the Frontier - Revival.png|thumb|right|400px|Life in the Frontier - Revival (BeeTLe BeTHLeHeM's second OXP)]]

== Musings ==
*These stations are massive! There should be many more facilities - restaurants, many more bars, more hotels, ''etc''.
*There should be different maps for different stations (Coriolis, Dodo, Ico ''etc'').
*Might one be able to sit in a bar and watch the planet and local ships move beneath on a screen or even through a window! And watch [[GNN]] on another screen!
*Could be combined with the bar in [[Hints]], with the bar and trade floor ''etc''. in [[New Cargoes]], the Embassy district in [[Diplomancy]], the Guild of Elite Traders in [[Elite Trader OXZ]], a Lave First Finance Corp office for [[First Finance OXP]], the Black Market, bribeable station officials' offices and the dock master's office for [[Smugglers - The Galactic Underworld]], GalCop security offices/kiosks for [[Bounty System]] and the storage facility for [[Equipment Storage OXP]]. And [[Hermitage]] could do with a Rock Hermit equivalent!
*Since one can become meaningfully sick, a meaningful link with plague systems would be a nice addition (determined ''eg'' by [[GNN]]).

== Download ==
*Download from the in-game [[Expansions Manager]]!
*[[Media:Life_In_The_Frontier_0.7.3.oxz|Life_In_The_Frontier_0.7.3.oxz]] (downloaded {{#downloads:Life_In_The_Frontier_0.7.3.oxz}} times).
*[[Media:Life_In_The_Frontier_0.7.1.oxz|Life_In_The_Frontier_0.7.1.oxz]] (downloaded {{#downloads:Life_In_The_Frontier_0.7.1.oxz}} times).

*Massively Locked's & Cholmondely's updates (experimental). Note that these are development versions and not recommended for regular play-throughs.
:[[File:LitF+v0.03.oxz]] - adds fledgling rock hermit layout
:[[File:LitF+v0.02.oxz]] - adds temples, govt section, RH bookshop
:[[File:LitF+v0.01.oxz]] - more bookshops, names your ship

== Links ==
*[http://www.aegidian.org/bb/viewtopic.php?t=17181 BB Thread] (2015-16)
*[https://www.youtube.com/watch?v=TZx59ShaVtw YouTube film] (2018) - this now seems to link to a film of the second OXP, below.
*[https://pioneerspacesim.net/forum/viewtopic.php?f=3&t=454 My dream for entering stations / cities] Pioneer's discussion on this (2016-date)

*[[Life In The Frontier - Revival OXP]] - a second, clashing OXP, also by BeeTLe BeTHLeHeM, which creates a message board with things to do...

== Quick Facts ==
{{OXPLevel|0}}{{Infobox OXPb| title = Life In The Frontier
|version = 0.7.3
|release = 2015.07.12
|features = Walk around in the station
|license = CC BY-NC-SA 4
|category = Activities OXPs
|author = [http://aegidian.org/bb/memberlist.php?mode=viewprofile&u=28786 BeeTLe BeTHLeHeM]
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=17181 BB-Link]
}}

{{Dockables-OXP}}

Life in the Frontier

2022-11-18T19:07:02Z

Massively Locked: added note

{{OXPNote|Initiated by BeeTLe BeTHLeHeM, then tweaked by [[User:Norby|Norby]], this OXP could do with some more work! All the stations have the same map - they should vary... (the encounters ''do'' vary)}}
[[Image:Litf_stationmap.png|300px|right]]

== Description ==

At the moment, players roleplay their game session, depending on the career they choose, and the events in-flight. But, space stations, on the contrary, are still rather static (without considering OXPs) and act more like a transition between two flights.

So I thought to help stations offer more variety, giving a player the chance to encounter random events while docked, an event that could require a player choice and with effects (good and bad) on the player.

[[File:Life in the Frontier (Park).png|thumb|400px|right]]
[[File:Life in the Frontier (Medical Centre).png|thumb|400px|right]]
[[File:Life in the Frontier (Bar).png|thumb|400px|right|Unfortunate blue text thanks to [[Dangerous HUD]] (blue)!]]
== How it works ==
=== Events ===
When the player is docked at a station, he will find in the F4 screen a new item, '''Disembark from your ship'''. If selected, the OXP will choose a random event from a list, and the player will have to confront it. Some events will be a mere description of something that happens in the vicinity of the player, while others will require choices and decisions, and usually offer multiple resolutions.

The events are categorized depending on various factors: the system government, economy and TL, plus one "generic" category for events that can happen anywhere. Instead the specific categories are intended to create a precise atmosphere, so in dictatorial systems there will be a more oppressive feeling, and in low tech worlds it will possible to see more malfunctioning in systems.

Every category has a defined background - I have taken shots from corridors in old sci-fi movies but I don't know if I can use them, so in case I will remove them. For now consider them as placeholders.

The resolution of an event can include: variation in money, in bounty level, in ship fuel or cargo goods. In these case will be displayed a report screen showing what is changed.

Sometimes the eventuation of an event will require a check on one of those properties, for example to avoid the player losing more money than he actually has!

The player can initiate an event by docking, to initiate another event he will need to leave and dock at another (or the same) station - in this way the mechanic shouldn't be abused.

=== The map ===
One can move around and explore the station, and encounter more events as one does so, both during travel and in, say, the bar. There is something to be found at each location (dust in the bookshop...).

== Changelog ==
<div class="mw-collapsible mw-collapsed" data-expandtext="Show details from the Dark Side" data-collapsetext="Hide details" style="overflow:auto;">
0.7.3
-Disembark is possible after load game in additional stations.
-Fixed step back from life status screen in non-galcop stations.
-Fixed mission.screenID error message in non-galcop stations.

0.7.2
- Fixed bounty clearing at galcop terminal (by Norby).
- Non-galcop stations are limited to the hangar.
- HD BackGrounds OXP is used in life status screen and non-galcop hangar.
- Able to use hd background images made in any resolution (fit to height).

0.7.1
- Fixed action on Museum exit.

0.7
- Completed STORAGE, special location on Docks with restricted access:
25 credits or legal stance <= -25 (friendly with criminals)
- Placed PASSENGERS LOUNGE, special location on Concourse-A
- Placed CHURCH OF THE COSMIC WANDERER, special location on Concourse-B
- Placed BOOKSHOP, special location on Concourse-B
- Placed MUSEUM, special location on Delight Avenue
- Placed FIT CENTER, special location on Olympian Square
- Implemented Station Map, visible from every lobby
- Commander stats and OXP flags are stored as a map (string with format name1=value1,name2=value2,name3=value3...)
instead of an array. This should definitely fix every issue with loading and saving data.
- Placed BRIEFING ROOM, special location on Galcop Precinct.
- Placed DETAINMENT ZONE, special location on Galcop Precinct.
- Placed SOCIAL SERVICES, special location on Galcop Precinct.
- Placed PILOT COURSE ROOM, special location on Galcop Precinct.

- Implemented SOCIAL SERVICES mechanics:
* Player can spend 4 hours doing social services. His reputation will increase of a small amount.
His bounty will decrease of an amount. There's a chance of getting hurt during the work.
In this case the time spent and bounty decrease are reduced.

- Implemented FIT CENTER mechanics:
* The first time the commander visits a Fit Center, he must buy an Universal Fitness Badge for 15cr.
This purchase include a month subscription.
* The subscription can be renewed monthly for 10cr.
* Commander mustn't be wounded or sick to enter the gym.
* Every gym session increase commander strength.
* If commander exercise more than once in two days, a chance of getting wounded while exercising increase.
* If the commander get wounded, he'll must get healed before starting a new gym session.
* If the commander get wounded, the maximum strength cap get lowered of a small amount.
If this amount get very low (it requires a lot of accidents, though...) the commander can't access
the gym anymore until he get a recovering therapy from an hi-tech Medical Center.
* If the commander doesn't go to the gym for more than a week, strength will lower of a small amount after every dock.
* If commander can't access the gym because he has endured too much damage, he can go to a hi-tech system
Medical Center and get into a Recovery Therapy for 400cr. This therapy is available only when the player
has sustained a lot of damage (only in the gym for now).
* The status screen (access from the hangar) report the Universal Fitness expiration status, when the player buys it.

0.6.1
- Fixed corridor background name - this should avoid log warning messages about texture files not found.
- Fixed paytreatment action, MedCenter treatment should give no exception now.
- Deleted useless number from OXP versioning - better late then never. (Current model: MajorVersion.MinorVersion.Fix)

0.1.6 (0.6)
- When accessing the OXP from the F4 screen, the player goes directly to the Hangar.
- The player can display the Commander Status screen from the Hangar.
- Station layout updated following forum discussion on the current design.
- Changed some definitions for station locations.
- Lobby indications are more schematic.
- The Storage location has been promoted to special location.
- Implemented Hotel, moved location to Main Concourse-A because Delight Avenue has already 3 planned locations.
- Implemented the Wild Worlds Virtual Tour, on the Delight Avenue (Recreation Bridge).

0.1.5.1 (0.5.1)
- Fixed check on the variables introduced in 0.1.5.
- Fixed check on varStore array items before setting values.

0.1.5 (0.5)
- Added background to Docks Area;
- Add text snippet for drunken status (along with wounds and sickness);
- Implemented event-checks for "government", "tech" and "economy". The government check can take a list of governments,
separated by "-" character. If the system government is in the list, the check is valid;
- Added events: ROBO-BARD, HUNTERS, DELIRIOUS DROID, COMMERCIAL DROID, SUPERCELEBRITY, LIGHTS MALFUNCTION,
WATER MALFUNCTION, AIR MALFUNCTION, DEFACING KIDS
- "her/him/his" not capitalized anymore;
- Commander stats are saved as a string with comma-separated values rather than 5 missionVariables.
- Game flags are saved as a string with comma-separated values rather than 8 missionVariables.
- Variables still not used aren't loaded anymore from the savegame, and are saved with null values to purge them from the file.
- Refactored method for checks on event/choice requirements: it's now possible to interrogate a parameter with operators
=, !=, <, <=, >, >=. The requirement syntax changes. E.g.: no more credits:500, but credits=500, or credits<500 etc.
- Event text can be present as parameter "text" (static text, always displayed) *OR* as indexed parameters
(text0, text1, text2): in the latter case, it's possible to specify display conditions, with syntax
"condition|text to display". If an indexed text has no condition is considered static (always displayed).
The validated indexed text are concatenated.
- Event property "choiceRequires" has been removed. It has been replaced by "r"(+ choice index), that contains
the facultative requirements for the single choice. If a choice has no requirements (no "r" property),
the choice is always displayed.
- I believe I have removed the end-event resume screen at least one release ago, forgot to write it down.
- To avoid confusion, in the event properties requires and r I don't use the ':' char as separator anymore,
but the equal sign '='.
- Refactored action executions when player select an event or a location choice. There are some differences
in some actions, so I had to differentitate: go (random event) and goNav (navigation), end (random event)
and endNav (navigation).
- Implemented condition if to the events action. Now it's possible to define a condition (or multiple conditions,
comma-separated), and to link it to two results: the "valid condition" and the "else".
I'm going to read again the various random events to introduce conditions when necessary, to streamline the event flow.
Syntax is: if:<conditions>?<actions>;<elseActions>
- I've lost some features (the hotel, the wild world virtual tour and the new Medical Center text),
so I'll have to rethink them in the next days. Actually I have changed the Medicla Center concept,
so the options are always displayed but if the player isn't sick or wounded or drunk the receptionist
will refuse to start the treatment.
- Fixed: the Galcop terminal didn't show the price for cleaning the criminal record.
- The DEFACING KIDS event can enable a flag - eventually the consequence will be shown when the player reach the docks area.

0.1.4 (0.4)
- Code optimization and refactoring. Creation of new js files for common methods, for mission-related methods,
and for inside-station navigation methods.
- Restarted from scratch (taking the old code piece for piece).
- The F4 link shows a literal resume of the player. From this screen, the player can "disembark" from the ship
and wander into the space station.
- "Tubes Stop" locations allow player to move across five different levels. Every level has a theme and
several inner locations. The levels are to be intended as concentric.
- Events are not fired by player anymore. But moving into the station there is a 20% chance (not definitive)
of firing a random event. They act like an intermission, basically.
- Added random snippet (from a list of 20) of texts when at a Tube Stop.

- Added all the events already implemented in 0.1.3 (beside the bar ones)
- Added the bar events: the gossip option has been moved to the "talk with bartender one".
Bartender doesn't give hints about contractors anymore.
- It's possible to clean own criminal record at the Galcop termminal (in the Galcop precinct)
paying a fine of (500cr x current bounty).
- Added the Art Gallery and the art genre random generator.
- Added the Opera House and the music genre random generator.
- Added the Cinema Hall and the movie genre random generator.
- If player is wounded or sick, randomly add short descriptive snippet of text while moving around the station.
- Added a short single-row-status text to show on top of the locations screens.
- Added two backgrounds for the "Tubes".
- Changed "Tube Stop" to "Lift Station", and "Tubes" to "Lift".
The direction is relative, it's not necessary an up-down transport.

- The property background can contain more background file names separated by comma:
the OXP will choose a random background between those specified.
- Added some more backgrounds, I'm trying to add variety and get an "identity" for the various levels.
- Added medical center location: here the player can cure wounds and sickness for a price.
Price and amount of cure changes in relation to system tech level.
The medical center can also rid of drunken status for free, but with a chance for a slight sickness.

- Added health/sickness management, with the following rules being checked every time the player docks to a station:
1) if sickness > 1, chance 10% of worsening (sickness +1);
2) if sickness = 1, chance 10% of healing (sickness = 0);
3) if health > 1, chance 10% of worsening (health + 1);
4) if health = 1, chance 10% of healing (health = 0);
5) if health > 2 and sickness < 2, chance 10% of infection (sickness +1);
6) if health > 2 or sickness > 2, chance 10% of physical shape reduction
- If player has health or sickness in critical conditions (>= 5), has a 50% of pass-out.
In this case he will be automatically transported to the station Medical Center and cured (with system TL limitations).
Player will receive a decrease in reputation (for careless behaviour) and the price of the opeation
will be automatically withdrawn from his account - if he has't enough money his bounty will be
slightly increased (for debt insolvency).

0.1.3 (0.3)
- implemented a time variable for events. It's now possible to define how much time will be spent when executing an event.
Instead of creating a separate property, the variabile is set in the "end:x" command, where x is the time spent
in seconds. So "end:600" means "terminate the event and go forward 10 minutes in time".
Use "end:0" to avoid spending game-time;
- As a general rule for numeric command parameters, two values comma-separated will be interpreted as a range,
and a random number between the specified values will be extracted. This applies even to the time variable above;
- Added a new resolution to the "elixir peddler" event, that use the time variable above;

- implemented the constants $SPECIES_S$ (singular) and $SPECIES_P$ (plural), that set a random species
if requested by the event text. The species value remain fixed until the end of the event;
- implemented the constants $GENDERSUBJ$ (he/she), $GENDEROBJ$ (him/her), $GENDERPOSS$ (his/her).
The random chosen gender remain fixed untile the end of the event.
The gender-values are correlated to maintain coherence throughout the text;
- fixed the text of all the events implemented until now;
- added five "no-events";

- added a new script file (LITF_RPGElements.js) to keep together the RPG-lite functions;
- changed the F4 link in "Visit the station hub": it show a main screen with player current RPG-lite status
(reputation, health, sickness, strength), the link to the random event and something more...;
- added description for all the status variables;
- added arrays of "minor" cargo types to be inserted in missions text: these aren't new cargo types,
they will only be treated as random labels to differentiate the text depending on player reputation;

- The link on the F4 page has been changed to "Visit the station hub" and if selected shows the "main screen";
- The "main screen" displays the player status (a literal description for the LITF variables);
- Added variables: reputation, health (wounds, bruises etc.), sickness, strength (physical shape);
- Added variable: stance. Positive stance = the law; negative stance = the criminals.
Similar to reputation, but to be considered more like "word on the street is";
- Available choices for the "main screen";
* "Take a walk to the Main Concourse". This fires a random event, as before;

- The player won't find the locations (bar, fit center, church, med center) on every system.
I wrote a basic rule to distribute their presence in the galaxy.
The rule is mathematical and based on the system ID, so the final results are fixed - for now only the bar is enabled;
- Re-edited the implemented events to use the variables in effects and requirements;
- Added constant $LIQUORS$ (with an array of 20 liquor random names), $SYSTEM$ (get random system name),
$COMMODITY$ (get random vanilla commodity name), $GOSSIP$ (get a random gossip),
$NAME$ (for random NPC name), $MINORCARGO$ (for transport missions);
- Added flag management (not mission flags), checks and manipulation;
- Added command "time:x", if you don't want to end the events but only to spend time;

- Implemented first version mission generation. It works in two steps. First step: an NPC
(in this case, the bartender) tells the player that another NPC has a job available:
I store data about the NPC name, the system where he is, the type of mission and a
generous time limite to reach him. When the player docks to a station I check if it's
the right station and if the NPC hasn't expired: if everything's good, when the player
enter the main concourse I switch to an alternate event: meeting the NPC, that introduce
the job (a cargo transport), with a destination, a time limit and a type of "minor cargo"
(see above). If the player accepts, I use this data to generate a real mission.
- Removed sickness effect when getting drunk, it's counter-productive.
When I'll implement medical centers, player have the chance to pay to get sober.
For now he can leave the station and dock to another station to rid of the drunkenness.

- Modified the cargo mission management: I don't use specialCargo or awardContract,
but the OXP do the checks and display the page for completing a contract (always from the Main Concourse).
It's not definitive, but it seems to work.
- Added events: CHARMING PARTNER, MUGGING, THE LOST DRUNKARD, MEDICAL CAMP

0.1.2 (0.2)
- enabled the one-event-for-dock flag (it was disabled for showing various events without leaving a station).
- changed the event management, I moved the events data from missionscript.plist to
LITF_ActionsCatalog.js (renamed in LITF_EventsCatalog.js).
In this way I can group everything related to an event in one object
(text, requirements, choices and actions), and eventually I can make them more dynamic;
- renamed property "check" (property-checks that allow the event to happens) in "requires";
- added property "choiceRequires", contains pipe-concatenated string with checks for every event choice
(see check property list) for selecting choices to display under particular circumstances;
use "valid:1" for always display a choice, and "valid:0" to always hide it;
- added events:
GENERIC: charity
GENERIC: alien discussion
- implemented code for replace constants in event/choice text with a random element
from a related array: actually used in the charity event, constant $CHARITY$.

0.1.1 (0.1)
- events category list:
"generic" category
station allegiance (disabled)
system government (gov_0 - gov_7)
system tech level (ltech, htech), values 5-9 are converted to "generic"
system economy (ind, agri), values 3-4 are converted to "generic"
OXP choose a value from an array with the values [ generic, gov_x, tl_x, eco_x]
Maybe in the future I could add as new categories ranges for player rank or player bounty
- specific background picture depending on event category: system government, tech level
(low tech, high tech) and economy (industrial, agricolture). "Generic" events will show
the related system government background;
- event one-click for docking disabled for testing and showing OXP workings;
- passing time for events temporarily disabled: to be reintroduced it as an event property;
- event effects list:
mt_[name]:[value] add [value] to the player ship manifest good identified by [name].
bounty:[value] add [value] to the current player bounty.
fuel:[value] add [value] to the current player ship fuel amount.
credits[value] add [value] to the current player credits.
go:[label] fire the event identified by [label]
end:0 end the event
[value] can be positive or negative. There are checks to avoid negative results or values exceeding cargo space.
- check property list:
mt[name]:[value] check for player ship manifest good identified by [name] >= [value]
mt<[name]:[value] check for player ship manifest good identified by [name] < [value]
fuel:[value] check for player ship fuel amount >= [value]
fuel<:[value] check for player ship fuel amount < [value]
bounty:[value] check for current player bounty >= [value]
bounty<:[value] check for current player bounty < [value]
credits:[value] check for current player credits >= [value]
credits<:[value] check for current player credits < [value]
- added events:
GENERIC: beggar
GENERIC: weird password guy
GENERIC: fire
GENERIC: fire + gossip
GENERIC: shady seller
GENERIC: partygoers
GENERIC: running fugitive
GENERIC: thief
GENERIC: stranded crew (2 variants)
</div>
== License ==
This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License version 4.0.

If you are re-using any piece of this OXP, please let me know by sending an e-mail to norbylite at gmail.com.

Author: BeeTLe BeTHLeHeM

[[File:Life in the Frontier - Revival.png|thumb|right|400px|Life in the Frontier - Revival (BeeTLe BeTHLeHeM's second OXP)]]

== Musings ==
*These stations are massive! There should be many more facilities - restaurants, many more bars, more hotels, ''etc''.
*There should be different maps for different stations (Coriolis, Dodo, Ico ''etc'').
*Might one be able to sit in a bar and watch the planet and local ships move beneath on a screen or even through a window! And watch [[GNN]] on another screen!
*Could be combined with the bar in [[Hints]], with the bar and trade floor ''etc''. in [[New Cargoes]], the Embassy district in [[Diplomancy]], the Guild of Elite Traders in [[Elite Trader OXZ]], a Lave First Finance Corp office for [[First Finance OXP]], the Black Market, bribeable station officials' offices and the dock master's office for [[Smugglers - The Galactic Underworld]], GalCop security offices/kiosks for [[Bounty System]] and the storage facility for [[Equipment Storage OXP]]. And [[Hermitage]] could do with a Rock Hermit equivalent!
*Since one can become meaningfully sick, a meaningful link with plague systems would be a nice addition (determined ''eg'' by [[GNN]]).

== Download ==
*Download from the in-game [[Expansions Manager]]!
*[[Media:Life_In_The_Frontier_0.7.3.oxz|Life_In_The_Frontier_0.7.3.oxz]] (downloaded {{#downloads:Life_In_The_Frontier_0.7.3.oxz}} times).
*[[Media:Life_In_The_Frontier_0.7.1.oxz|Life_In_The_Frontier_0.7.1.oxz]] (downloaded {{#downloads:Life_In_The_Frontier_0.7.1.oxz}} times).

*Massively Locked's updates (experimental). Note that these are development versions and not recommended for regular play-throughs.
:[[File:LitF+v0.03.oxz]] - adds fledgling rock hermit layout
:[[File:LitF+v0.02.oxz]] - adds temples, govt section, RH bookshop
:[[File:LitF+v0.01.oxz]] - more bookshops, names your ship

== Links ==
*[http://www.aegidian.org/bb/viewtopic.php?t=17181 BB Thread] (2015-16)
*[https://www.youtube.com/watch?v=TZx59ShaVtw YouTube film] (2018) - this now seems to link to a film of the second OXP, below.
*[https://pioneerspacesim.net/forum/viewtopic.php?f=3&t=454 My dream for entering stations / cities] Pioneer's discussion on this (2016-date)

*[[Life In The Frontier - Revival OXP]] - a second, clashing OXP, also by BeeTLe BeTHLeHeM, which creates a message board with things to do...

== Quick Facts ==
{{OXPLevel|0}}{{Infobox OXPb| title = Life In The Frontier
|version = 0.7.3
|release = 2015.07.12
|features = Walk around in the station
|license = CC BY-NC-SA 4
|category = Activities OXPs
|author = [http://aegidian.org/bb/memberlist.php?mode=viewprofile&u=28786 BeeTLe BeTHLeHeM]
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=17181 BB-Link]
}}

{{Dockables-OXP}}

Life in the Frontier

2022-11-18T07:00:23Z

Massively Locked: :-) Reports of my wealth have been greatly exaggerated, reports of my inebriation have not

{{OXPNote|Initiated by BeeTLe BeTHLeHeM, then tweaked by [[User:Norby|Norby]], this OXP could do with some more work! All the stations have the same map - they should vary... (the encounters ''do'' vary)}}
[[Image:Litf_stationmap.png|300px|right]]

== Description ==

At the moment, players roleplay their game session, depending on the career they choose, and the events in-flight. But, space stations, on the contrary, are still rather static (without considering OXPs) and act more like a transition between two flights.

So I thought to help stations offer more variety, giving a player the chance to encounter random events while docked, an event that could require a player choice and with effects (good and bad) on the player.

[[File:Life in the Frontier (Park).png|thumb|400px|right]]
[[File:Life in the Frontier (Medical Centre).png|thumb|400px|right]]
[[File:Life in the Frontier (Bar).png|thumb|400px|right|Unfortunate blue text thanks to [[Dangerous HUD]] (blue)!]]
== How it works ==
=== Events ===
When the player is docked at a station, he will find in the F4 screen a new item, '''Disembark from your ship'''. If selected, the OXP will choose a random event from a list, and the player will have to confront it. Some events will be a mere description of something that happens in the vicinity of the player, while others will require choices and decisions, and usually offer multiple resolutions.

The events are categorized depending on various factors: the system government, economy and TL, plus one "generic" category for events that can happen anywhere. Instead the specific categories are intended to create a precise atmosphere, so in dictatorial systems there will be a more oppressive feeling, and in low tech worlds it will possible to see more malfunctioning in systems.

Every category has a defined background - I have taken shots from corridors in old sci-fi movies but I don't know if I can use them, so in case I will remove them. For now consider them as placeholders.

The resolution of an event can include: variation in money, in bounty level, in ship fuel or cargo goods. In these case will be displayed a report screen showing what is changed.

Sometimes the eventuation of an event will require a check on one of those properties, for example to avoid the player losing more money than he actually has!

The player can initiate an event by docking, to initiate another event he will need to leave and dock at another (or the same) station - in this way the mechanic shouldn't be abused.

=== The map ===
One can move around and explore the station, and encounter more events as one does so, both during travel and in, say, the bar. There is something to be found at each location (dust in the bookshop...).

== Changelog ==
<div class="mw-collapsible mw-collapsed" data-expandtext="Show details from the Dark Side" data-collapsetext="Hide details" style="overflow:auto;">
0.7.3
-Disembark is possible after load game in additional stations.
-Fixed step back from life status screen in non-galcop stations.
-Fixed mission.screenID error message in non-galcop stations.

0.7.2
- Fixed bounty clearing at galcop terminal (by Norby).
- Non-galcop stations are limited to the hangar.
- HD BackGrounds OXP is used in life status screen and non-galcop hangar.
- Able to use hd background images made in any resolution (fit to height).

0.7.1
- Fixed action on Museum exit.

0.7
- Completed STORAGE, special location on Docks with restricted access:
25 credits or legal stance <= -25 (friendly with criminals)
- Placed PASSENGERS LOUNGE, special location on Concourse-A
- Placed CHURCH OF THE COSMIC WANDERER, special location on Concourse-B
- Placed BOOKSHOP, special location on Concourse-B
- Placed MUSEUM, special location on Delight Avenue
- Placed FIT CENTER, special location on Olympian Square
- Implemented Station Map, visible from every lobby
- Commander stats and OXP flags are stored as a map (string with format name1=value1,name2=value2,name3=value3...)
instead of an array. This should definitely fix every issue with loading and saving data.
- Placed BRIEFING ROOM, special location on Galcop Precinct.
- Placed DETAINMENT ZONE, special location on Galcop Precinct.
- Placed SOCIAL SERVICES, special location on Galcop Precinct.
- Placed PILOT COURSE ROOM, special location on Galcop Precinct.

- Implemented SOCIAL SERVICES mechanics:
* Player can spend 4 hours doing social services. His reputation will increase of a small amount.
His bounty will decrease of an amount. There's a chance of getting hurt during the work.
In this case the time spent and bounty decrease are reduced.

- Implemented FIT CENTER mechanics:
* The first time the commander visits a Fit Center, he must buy an Universal Fitness Badge for 15cr.
This purchase include a month subscription.
* The subscription can be renewed monthly for 10cr.
* Commander mustn't be wounded or sick to enter the gym.
* Every gym session increase commander strength.
* If commander exercise more than once in two days, a chance of getting wounded while exercising increase.
* If the commander get wounded, he'll must get healed before starting a new gym session.
* If the commander get wounded, the maximum strength cap get lowered of a small amount.
If this amount get very low (it requires a lot of accidents, though...) the commander can't access
the gym anymore until he get a recovering therapy from an hi-tech Medical Center.
* If the commander doesn't go to the gym for more than a week, strength will lower of a small amount after every dock.
* If commander can't access the gym because he has endured too much damage, he can go to a hi-tech system
Medical Center and get into a Recovery Therapy for 400cr. This therapy is available only when the player
has sustained a lot of damage (only in the gym for now).
* The status screen (access from the hangar) report the Universal Fitness expiration status, when the player buys it.

0.6.1
- Fixed corridor background name - this should avoid log warning messages about texture files not found.
- Fixed paytreatment action, MedCenter treatment should give no exception now.
- Deleted useless number from OXP versioning - better late then never. (Current model: MajorVersion.MinorVersion.Fix)

0.1.6 (0.6)
- When accessing the OXP from the F4 screen, the player goes directly to the Hangar.
- The player can display the Commander Status screen from the Hangar.
- Station layout updated following forum discussion on the current design.
- Changed some definitions for station locations.
- Lobby indications are more schematic.
- The Storage location has been promoted to special location.
- Implemented Hotel, moved location to Main Concourse-A because Delight Avenue has already 3 planned locations.
- Implemented the Wild Worlds Virtual Tour, on the Delight Avenue (Recreation Bridge).

0.1.5.1 (0.5.1)
- Fixed check on the variables introduced in 0.1.5.
- Fixed check on varStore array items before setting values.

0.1.5 (0.5)
- Added background to Docks Area;
- Add text snippet for drunken status (along with wounds and sickness);
- Implemented event-checks for "government", "tech" and "economy". The government check can take a list of governments,
separated by "-" character. If the system government is in the list, the check is valid;
- Added events: ROBO-BARD, HUNTERS, DELIRIOUS DROID, COMMERCIAL DROID, SUPERCELEBRITY, LIGHTS MALFUNCTION,
WATER MALFUNCTION, AIR MALFUNCTION, DEFACING KIDS
- "her/him/his" not capitalized anymore;
- Commander stats are saved as a string with comma-separated values rather than 5 missionVariables.
- Game flags are saved as a string with comma-separated values rather than 8 missionVariables.
- Variables still not used aren't loaded anymore from the savegame, and are saved with null values to purge them from the file.
- Refactored method for checks on event/choice requirements: it's now possible to interrogate a parameter with operators
=, !=, <, <=, >, >=. The requirement syntax changes. E.g.: no more credits:500, but credits=500, or credits<500 etc.
- Event text can be present as parameter "text" (static text, always displayed) *OR* as indexed parameters
(text0, text1, text2): in the latter case, it's possible to specify display conditions, with syntax
"condition|text to display". If an indexed text has no condition is considered static (always displayed).
The validated indexed text are concatenated.
- Event property "choiceRequires" has been removed. It has been replaced by "r"(+ choice index), that contains
the facultative requirements for the single choice. If a choice has no requirements (no "r" property),
the choice is always displayed.
- I believe I have removed the end-event resume screen at least one release ago, forgot to write it down.
- To avoid confusion, in the event properties requires and r I don't use the ':' char as separator anymore,
but the equal sign '='.
- Refactored action executions when player select an event or a location choice. There are some differences
in some actions, so I had to differentitate: go (random event) and goNav (navigation), end (random event)
and endNav (navigation).
- Implemented condition if to the events action. Now it's possible to define a condition (or multiple conditions,
comma-separated), and to link it to two results: the "valid condition" and the "else".
I'm going to read again the various random events to introduce conditions when necessary, to streamline the event flow.
Syntax is: if:<conditions>?<actions>;<elseActions>
- I've lost some features (the hotel, the wild world virtual tour and the new Medical Center text),
so I'll have to rethink them in the next days. Actually I have changed the Medicla Center concept,
so the options are always displayed but if the player isn't sick or wounded or drunk the receptionist
will refuse to start the treatment.
- Fixed: the Galcop terminal didn't show the price for cleaning the criminal record.
- The DEFACING KIDS event can enable a flag - eventually the consequence will be shown when the player reach the docks area.

0.1.4 (0.4)
- Code optimization and refactoring. Creation of new js files for common methods, for mission-related methods,
and for inside-station navigation methods.
- Restarted from scratch (taking the old code piece for piece).
- The F4 link shows a literal resume of the player. From this screen, the player can "disembark" from the ship
and wander into the space station.
- "Tubes Stop" locations allow player to move across five different levels. Every level has a theme and
several inner locations. The levels are to be intended as concentric.
- Events are not fired by player anymore. But moving into the station there is a 20% chance (not definitive)
of firing a random event. They act like an intermission, basically.
- Added random snippet (from a list of 20) of texts when at a Tube Stop.

- Added all the events already implemented in 0.1.3 (beside the bar ones)
- Added the bar events: the gossip option has been moved to the "talk with bartender one".
Bartender doesn't give hints about contractors anymore.
- It's possible to clean own criminal record at the Galcop termminal (in the Galcop precinct)
paying a fine of (500cr x current bounty).
- Added the Art Gallery and the art genre random generator.
- Added the Opera House and the music genre random generator.
- Added the Cinema Hall and the movie genre random generator.
- If player is wounded or sick, randomly add short descriptive snippet of text while moving around the station.
- Added a short single-row-status text to show on top of the locations screens.
- Added two backgrounds for the "Tubes".
- Changed "Tube Stop" to "Lift Station", and "Tubes" to "Lift".
The direction is relative, it's not necessary an up-down transport.

- The property background can contain more background file names separated by comma:
the OXP will choose a random background between those specified.
- Added some more backgrounds, I'm trying to add variety and get an "identity" for the various levels.
- Added medical center location: here the player can cure wounds and sickness for a price.
Price and amount of cure changes in relation to system tech level.
The medical center can also rid of drunken status for free, but with a chance for a slight sickness.

- Added health/sickness management, with the following rules being checked every time the player docks to a station:
1) if sickness > 1, chance 10% of worsening (sickness +1);
2) if sickness = 1, chance 10% of healing (sickness = 0);
3) if health > 1, chance 10% of worsening (health + 1);
4) if health = 1, chance 10% of healing (health = 0);
5) if health > 2 and sickness < 2, chance 10% of infection (sickness +1);
6) if health > 2 or sickness > 2, chance 10% of physical shape reduction
- If player has health or sickness in critical conditions (>= 5), has a 50% of pass-out.
In this case he will be automatically transported to the station Medical Center and cured (with system TL limitations).
Player will receive a decrease in reputation (for careless behaviour) and the price of the opeation
will be automatically withdrawn from his account - if he has't enough money his bounty will be
slightly increased (for debt insolvency).

0.1.3 (0.3)
- implemented a time variable for events. It's now possible to define how much time will be spent when executing an event.
Instead of creating a separate property, the variabile is set in the "end:x" command, where x is the time spent
in seconds. So "end:600" means "terminate the event and go forward 10 minutes in time".
Use "end:0" to avoid spending game-time;
- As a general rule for numeric command parameters, two values comma-separated will be interpreted as a range,
and a random number between the specified values will be extracted. This applies even to the time variable above;
- Added a new resolution to the "elixir peddler" event, that use the time variable above;

- implemented the constants $SPECIES_S$ (singular) and $SPECIES_P$ (plural), that set a random species
if requested by the event text. The species value remain fixed until the end of the event;
- implemented the constants $GENDERSUBJ$ (he/she), $GENDEROBJ$ (him/her), $GENDERPOSS$ (his/her).
The random chosen gender remain fixed untile the end of the event.
The gender-values are correlated to maintain coherence throughout the text;
- fixed the text of all the events implemented until now;
- added five "no-events";

- added a new script file (LITF_RPGElements.js) to keep together the RPG-lite functions;
- changed the F4 link in "Visit the station hub": it show a main screen with player current RPG-lite status
(reputation, health, sickness, strength), the link to the random event and something more...;
- added description for all the status variables;
- added arrays of "minor" cargo types to be inserted in missions text: these aren't new cargo types,
they will only be treated as random labels to differentiate the text depending on player reputation;

- The link on the F4 page has been changed to "Visit the station hub" and if selected shows the "main screen";
- The "main screen" displays the player status (a literal description for the LITF variables);
- Added variables: reputation, health (wounds, bruises etc.), sickness, strength (physical shape);
- Added variable: stance. Positive stance = the law; negative stance = the criminals.
Similar to reputation, but to be considered more like "word on the street is";
- Available choices for the "main screen";
* "Take a walk to the Main Concourse". This fires a random event, as before;

- The player won't find the locations (bar, fit center, church, med center) on every system.
I wrote a basic rule to distribute their presence in the galaxy.
The rule is mathematical and based on the system ID, so the final results are fixed - for now only the bar is enabled;
- Re-edited the implemented events to use the variables in effects and requirements;
- Added constant $LIQUORS$ (with an array of 20 liquor random names), $SYSTEM$ (get random system name),
$COMMODITY$ (get random vanilla commodity name), $GOSSIP$ (get a random gossip),
$NAME$ (for random NPC name), $MINORCARGO$ (for transport missions);
- Added flag management (not mission flags), checks and manipulation;
- Added command "time:x", if you don't want to end the events but only to spend time;

- Implemented first version mission generation. It works in two steps. First step: an NPC
(in this case, the bartender) tells the player that another NPC has a job available:
I store data about the NPC name, the system where he is, the type of mission and a
generous time limite to reach him. When the player docks to a station I check if it's
the right station and if the NPC hasn't expired: if everything's good, when the player
enter the main concourse I switch to an alternate event: meeting the NPC, that introduce
the job (a cargo transport), with a destination, a time limit and a type of "minor cargo"
(see above). If the player accepts, I use this data to generate a real mission.
- Removed sickness effect when getting drunk, it's counter-productive.
When I'll implement medical centers, player have the chance to pay to get sober.
For now he can leave the station and dock to another station to rid of the drunkenness.

- Modified the cargo mission management: I don't use specialCargo or awardContract,
but the OXP do the checks and display the page for completing a contract (always from the Main Concourse).
It's not definitive, but it seems to work.
- Added events: CHARMING PARTNER, MUGGING, THE LOST DRUNKARD, MEDICAL CAMP

0.1.2 (0.2)
- enabled the one-event-for-dock flag (it was disabled for showing various events without leaving a station).
- changed the event management, I moved the events data from missionscript.plist to
LITF_ActionsCatalog.js (renamed in LITF_EventsCatalog.js).
In this way I can group everything related to an event in one object
(text, requirements, choices and actions), and eventually I can make them more dynamic;
- renamed property "check" (property-checks that allow the event to happens) in "requires";
- added property "choiceRequires", contains pipe-concatenated string with checks for every event choice
(see check property list) for selecting choices to display under particular circumstances;
use "valid:1" for always display a choice, and "valid:0" to always hide it;
- added events:
GENERIC: charity
GENERIC: alien discussion
- implemented code for replace constants in event/choice text with a random element
from a related array: actually used in the charity event, constant $CHARITY$.

0.1.1 (0.1)
- events category list:
"generic" category
station allegiance (disabled)
system government (gov_0 - gov_7)
system tech level (ltech, htech), values 5-9 are converted to "generic"
system economy (ind, agri), values 3-4 are converted to "generic"
OXP choose a value from an array with the values [ generic, gov_x, tl_x, eco_x]
Maybe in the future I could add as new categories ranges for player rank or player bounty
- specific background picture depending on event category: system government, tech level
(low tech, high tech) and economy (industrial, agricolture). "Generic" events will show
the related system government background;
- event one-click for docking disabled for testing and showing OXP workings;
- passing time for events temporarily disabled: to be reintroduced it as an event property;
- event effects list:
mt_[name]:[value] add [value] to the player ship manifest good identified by [name].
bounty:[value] add [value] to the current player bounty.
fuel:[value] add [value] to the current player ship fuel amount.
credits[value] add [value] to the current player credits.
go:[label] fire the event identified by [label]
end:0 end the event
[value] can be positive or negative. There are checks to avoid negative results or values exceeding cargo space.
- check property list:
mt[name]:[value] check for player ship manifest good identified by [name] >= [value]
mt<[name]:[value] check for player ship manifest good identified by [name] < [value]
fuel:[value] check for player ship fuel amount >= [value]
fuel<:[value] check for player ship fuel amount < [value]
bounty:[value] check for current player bounty >= [value]
bounty<:[value] check for current player bounty < [value]
credits:[value] check for current player credits >= [value]
credits<:[value] check for current player credits < [value]
- added events:
GENERIC: beggar
GENERIC: weird password guy
GENERIC: fire
GENERIC: fire + gossip
GENERIC: shady seller
GENERIC: partygoers
GENERIC: running fugitive
GENERIC: thief
GENERIC: stranded crew (2 variants)
</div>
== License ==
This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License version 4.0.

If you are re-using any piece of this OXP, please let me know by sending an e-mail to norbylite at gmail.com.

Author: BeeTLe BeTHLeHeM

[[File:Life in the Frontier - Revival.png|thumb|right|400px|Life in the Frontier - Revival (BeeTLe BeTHLeHeM's second OXP)]]

== Musings ==
*These stations are massive! There should be many more facilities - restaurants, many more bars, more hotels, ''etc''.
*There should be different maps for different stations (Coriolis, Dodo, Ico ''etc'').
*Might one be able to sit in a bar and watch the planet and local ships move beneath on a screen or even through a window! And watch [[GNN]] on another screen!
*Could be combined with the bar in [[Hints]], with the bar and trade floor ''etc''. in [[New Cargoes]], the Embassy district in [[Diplomancy]], the Guild of Elite Traders in [[Elite Trader OXZ]], a Lave First Finance Corp office for [[First Finance OXP]], the Black Market, bribeable station officials' offices and the dock master's office for [[Smugglers - The Galactic Underworld]], GalCop security offices/kiosks for [[Bounty System]] and the storage facility for [[Equipment Storage OXP]]. And [[Hermitage]] could do with a Rock Hermit equivalent!
*Since one can become meaningfully sick, a meaningful link with plague systems would be a nice addition (determined ''eg'' by [[GNN]]).

== Download ==
*Download from the in-game [[Expansions Manager]]!
*[[Media:Life_In_The_Frontier_0.7.3.oxz|Life_In_The_Frontier_0.7.3.oxz]] (downloaded {{#downloads:Life_In_The_Frontier_0.7.3.oxz}} times).
*[[Media:Life_In_The_Frontier_0.7.1.oxz|Life_In_The_Frontier_0.7.1.oxz]] (downloaded {{#downloads:Life_In_The_Frontier_0.7.1.oxz}} times).

*Massively Locked's updates (experimental)
:[[File:LitF+v0.03.oxz]] - adds fledgling rock hermit layout
:[[File:LitF+v0.02.oxz]] - adds temples, govt section, RH bookshop
:[[File:LitF+v0.01.oxz]] - more bookshops, names your ship

== Links ==
*[http://www.aegidian.org/bb/viewtopic.php?t=17181 BB Thread] (2015-16)
*[https://www.youtube.com/watch?v=TZx59ShaVtw YouTube film] (2018) - this now seems to link to a film of the second OXP, below.
*[https://pioneerspacesim.net/forum/viewtopic.php?f=3&t=454 My dream for entering stations / cities] Pioneer's discussion on this (2016-date)

*[[Life In The Frontier - Revival OXP]] - a second, clashing OXP, also by BeeTLe BeTHLeHeM, which creates a message board with things to do...

== Quick Facts ==
{{OXPLevel|0}}{{Infobox OXPb| title = Life In The Frontier
|version = 0.7.3
|release = 2015.07.12
|features = Walk around in the station
|license = CC BY-NC-SA 4
|category = Activities OXPs
|author = [http://aegidian.org/bb/memberlist.php?mode=viewprofile&u=28786 BeeTLe BeTHLeHeM]
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=17181 BB-Link]
}}

{{Dockables-OXP}}

File:LitF+v0.03.oxz

2022-11-17T23:01:01Z

Massively Locked: dev ver 0.03

== Summary ==
dev ver 0.03

Misc plists

2022-11-12T13:10:44Z

Massively Locked: /* Structure */ fixed typo & cleared up wording

=crosshairs.[[plist]]=

== Structure ==

The file is organized as a dictionary of crosshairs with the weapon name as its key. The key 'OTHER' can be used for weapons not otherwise defined by the crosshairs dictionary. Each weapon crosshair itself consists of an array of line segments. Each line segment is represented by an array of 6 numbers.
Example of a line segment:
(W1, X1, Y1, W2, X2, Y2)
The line will start at X1,Y1 with a relative width W1 and ends at X2, Y2 with relative width W2.
All coordinates must lie between -1 and +1, while the widths are between 0 and 1

Example:
WEAPON_NONE =
(
(0.25, 0.75, 0.0, 0.75, 0.50, 0.0),
(0.25, -0.75, 0.0, 0.75, -0.50, 0.0)
);
The crosshairs.plist is not intended to be changed by an OXP. For custom crosshairs it is intended to add a <code>crosshair</code> entry in the custom HUD definition itself. This will then override the default crosshairs for that HUD. (See [[hud.plist]]).

In 1.77 or later, custom crosshairs files may be defined. These have the same syntax as crosshairs.plist, but should have a different unique name (e.g. <code>oxpname_crosshairs1.plist</code>). Crosshairs may be included by a HUD definition, or switched in and out by [[Oolite_JavaScript_Reference:_PlayerShip#crosshairs|scripting]].

=descriptions.[[plist]]=

== Structure ==

The file is organized as a dictionary with pairs of key and value (string or array).
It has the same structure as the [[missiontext.plist]] and it also resides in the config folder inside the OXP.

Example XML:
<dict>
<key>parcelnumbers</key>
<array>
<string>two</string>
<string>three</string>
<string>four</string>
<string>five</string>
<string>six</string>
</array>
</dict>

Example OpenStep:
{
parcelnumbers = ("two", "three", "four", "five", "six");
}

== Use ==

Its use must be seen as a kind of variable. The key part is the variable name and the string part is the content of the variable. If you use an array of strings the variable will return a random choice of one of the strings. And this is the main use of the descriptions.plist: creation of text with variable content. See also [[string expansion]]. Note that for compatibility, the random number used to determine which choice to use from an array is only 1 byte long. Therefore if the array has more than 256 entries there will be some entries which can never be picked, and if it has a number of entries which is not a power of two the entries will not have equal chances of being picked (though if the number of entries is small, the difference in chances is not significant)

The text itself is invoked by using the key-word between square brackets, like:

You have to pick up [parcelnumbers] parcels.

Whenever Oolite reads in a scriptline, missiontext or description, it first looks for something between brackets. If it finds something it looks to see if it is a mission_variable. If yes, it replaces the name of the variable with its content. Then it looks in the descriptions.plist. If it finds a key, it replaces the name with the string content. If it is an array it picks at random one of the strings.

Be aware that Oolite reads in all descriptions.plist lines on startup in one big file. This means that you can use keywords from other OXPs or from Oolite itself. If there are some keys with duplicate names, it uses the last. This means that you must use [[OXP Distribution#General|unique keywords]].

=== Example ===
First adding categories to the Ship Library/View Ship specifications screen; ''then'' adding a missile icon; and ''finally'' adding mission text: this is the entire descriptions.plist

{
"oolite-ship-library-category-black_mamba" = "Black Mamba";
"oolite-ship-library-category-plural-black_mamba" = "Black Mambas";

"EQ_X_SWORD_MISSILE" =
(
2, 2,
2, 1,
1, 0,
2, -1,
2, -2,
1, -2,
0, 0,
-1, -2,
-2, -2,
-2, -1,
-1, 0,
-2, 1,
-2, 2,
-1, 2,
0, 0,
1, 2
);
"XS_MI_STAGE_245" = "The Murderer is at Digebiti.";
"XS_MI_STAGE_G7_1" = "Just in time, Commander. I could use a little help here!";
}

=demoships.[[plist]]=

In 1.79 and following this is superseded by [[Shiplibrary.plist]] and should no longer be used for OXPs. It was used to project the ship on the new commander screen at game start. Its replacement adds the ship/station ''etc'' to the ship information on the "View Ship Library" page when Oolite starts up (and to the "View ship specifications" page on the docked F4 screen)

==Structure==
The file is organized as an array. Every entry consists of a string, with the name of a ship. The shipname must correspond with a key inside the [[shipdata.plist]]. It resides in the config folder inside the OXP.

Example XML:
<array>
<string>my_ship1</string>
<string>my_ship2</string>
</array>

Example OpenStep:
(
"my_ship1",
"my_ship2"
)

==Use==
Its function is to select which ships to show on the startup screen when a new commander is chosen.

=illegal_goods.[[plist]]=
'''Note: The commodities.plist file is no longer used from Oolite 1.82 and following.''' It has been superseded by the [[Trade-goods.plist]]

==Structure==
The file is organized as a dictionary. Every entry consists of a key and a number. The key says which goods are illegal, and the number how illegal the goods are.

Example OpenStep:
{
Firearms = 1;
Narcotics = 2;
Slaves = 1;
}

==Use==
Better never use this as it might change the game to much.

=pirate-victim-roles.[[plist]]=

In 1.79 this is superseded by [[role-categories.plist]] and should no longer be used for new OXPs. Existing files will continue to have the effect documented below.

==Structure==
The file is organized as an array. Every entry consists of a string, with the name of a shiprole. This plist is introduced with Oolite version 1.70

Example XML:
<array>
<string>my_shiprole1</string>
<string>my_shiprole2</string>
</array>

Example OpenStep:
(
"my_shiprole1",
"my_shiprole2"
)

==Use==
Pirates use the function '''scanForNearestMerchantman''' and '''scanForRandomMerchantman'''. With pre 1.70 versions this function only finds ships with role '''trader''' and '''player'''. Starting with 1.70 these two functions finds all ships that are included in the pirate-victim-roles.plist. This makes it possible to add ships in their own role that are recognized by pirates as traders. Ship designers are encouraged to use this pirate-victim-roles.plist and add all private roles that should act trader like for better interaction with pirate groups.

[[Media:pirate-victim-roles.zip|''Download a custom pirate-victim-roles.plist'']]

=OXPMessages.[[plist]]=

==Structure==
The file is organized as an array of strings. When the plist is present, the content of the strings is written to the log on start-up and the player sees a message on the start-up screen that the oxp "foo" contains a message. This plist is introduced with Oolite version 1.74. It should be placed directly in the main directory level of the oxp where the 'requires.plist' is also situated.

Example OpenStep:
(
"This is a copy of my own test version of the oxp: "foo". This oxp is intended for personal use only, don't spread."
)

==Use==
Only useful for test versions to make the user constantly aware that he is using a test version of the oxp.

=world-scripts.[[plist]]=

==Structure==
The file is organized as an array. Every entry consists of a string, with the name of a script. The name must correspond with a file inside the Scripts folder inside the OXP.

Example:
(
"my_script1.js",
"my_script2.js",
"my_script3.plist"
)

==Use==
Its function is to attach more than one wordScript to an oxp. On startup, Oolite looks first if there is a worldScripts.plist file. When present the scripts inside are used as world scripts. These scripts can be both js script files or legacy script plist files. Even a mix is allowed. Only when the worldScripts.plist is not present, Oolite looks for a file with the name "script.js" in the Config folder. And when that is not present it looks for the file "script.plist".

=whitelist.[[plist]]=

==Structure==
The file is organized as a dictionary of keys with the values being themselves either arrays of strings or dictionaries of key-value pairs.

==Use==
The file is included with Oolite. OXPs are restricted from using legacy features that are not included in the whitelist. As of Oolite 1.89, the file starts with the following comment:
<pre>
/* Methods that may be used from old-style script actions or conditions.

This plist cannot be extended or overriden by OXPs.

action_methods Commands permitted in world scripts.
ai_methods Commands permitted in AIs.
ai_and_action_methods Commands permitted in world scripts and AIs.
query_methods Values that may be queried in script conditions.
action_method_aliases Mappings from script commands (left) to internal names (right).
ai_method_aliases Mappings from AI commands (left) to internal names (right).
query_method_aliases Mappings from script queries (left) to internal names (right).
shader_*_binding_methods Values that may be queried through shader bindings.

Most other types of legacy script - ship actions, character scripts,
scriptActionOnTarget: - can use both action_methods and ai_methods. The exception is
systeminfo scripts, which can't use ai_methods as they aren't run with a ship target.
*/
</pre>

[[Category:Oolite scripting]]

=See also=
* [[OXP howto]]

File:LitF+v0.02.oxz

2022-11-11T19:56:04Z

Massively Locked: dev ver 0.02

== Summary ==
dev ver 0.02

Oolite JavaScript Reference: System

2022-11-11T00:16:59Z

Massively Locked: /* government */ added link

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

The '''<code>System</code>''' class represents the current star system. There is always one <code>System</code> object, available through the global property <code>system</code>.

Attempts to change system properties are ignored in interstellar space (i.e., the place you end up in after a witchspace malfunction).

== Properties ==
=== <code>allShips</code> ===
'''allShips''' : Array (read-only)
A list of the ships in the system.

'''See Also:''' <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>, <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>

=== <code>allVisualEffects</code> ===
{{oolite-prop-added|1.77}}
'''allVisualEffects''' : Array (read-only)
A list of the [[Oolite_JavaScript_Reference:_VisualEffect|visual effects]] in the system.

=== <code>ambientLevel</code> ===
{{oolite-prop-added|1.81}}
'''ambientLevel''' : float (read/write)
Adjusts the level of ambient light in the current system. Values should typically be between 0.0 and 1.0 (1.0 is the default) but can be higher for a flat lit, cartoon-like effect. This is will override the "ambient_level" setting defined in [[Planetinfo.plist]]. The change is not permanent and will be reset when the system is reloaded.

=== <code>breakPattern</code> ===
{{oolite-prop-added|1.77}}
'''breakPattern''' : Boolean (read/write)
If <code>true</code> (the default state set on entry to a new system), the break pattern will be shown to the player as they exit witchspace. While this property may be set from places other than the <code>shipWillExitWitchspace</code> world script event, it is pointless to do so.

Unlike all other system properties, this one may be changed on entry to interstellar space.

=== <code>description</code> ===
'''description''' : String (read/write)
The description of the current system, as seen on the planet info screen.

=== <code>economy</code> ===
'''economy''' : Number (integer, read/write)
The type of economy in the current system, ranging from 0 (Rich Industrial) to 7 (Poor Agricultural).

'''See Also:''' [[Planetinfo.plist#Economy|Planetinfo.plist]], <code>[[#economyDescription|economyDescription]]</code>

=== <code>economyDescription</code> ===
'''economyDescription''' : String (read-only)
A localized description of the economy type, for example, <code>"Mostly Industrial"</code>. Since this string is localized, it should only be used for display purposes.

'''See Also:''' <code>[[#economy|economy]]</code>

=== <code>government</code> ===
'''government''' : Number (read/write, integer)
The type of government in the current system, ranging from 0 (Anarchy) to 7 (Corporate State).

'''See Also:''' [[Planetinfo.plist#Government|Planetinfo.plist]], <code>[[#governmentDescription|governmentDescription]]</code>

=== <code>governmentDescription</code> ===
'''governmentDescription''' : String (read-only)
A localized description of the government type, for example, <code>"Democracy"</code>. Since this string is localized, it should only be used for display purposes.

'''See Also:''' <code>[[#government|government]]</code>

=== <code>ID</code> ===
'''ID''' : Number (integer, read-only)
A number identifying the system. 0 to 255, or -1 for interstellar space.

=== <code>info</code> ===
'''info''' : [[Oolite JavaScript Reference: SystemInfo|SystemInfo]] (read/write)
Allows access to system properties, using the same keys as [[planetinfo.plist]].

'''Example:'''
system.info.description = "This is a dull planet.";

=== <code>inhabitantsDescription</code> ===
'''inhabitantsDescription''' : String (read/write)
The description of the inhabitants of the current system, such as <code>"Slimy Blue Frogs"</code>.

=== <code>isInterstellarSpace</code> ===
'''isInterstellarSpace''' : Boolean (read-only)
<code>true</code> if the current system is in interstellar space, <code>false</code> otherwise.

=== <code>mainPlanet</code> ===
'''mainPlanet''' : {{oojsclass|Planet}} (read-only)
The system’s main planet, or <code>null</code> if there is none.

'''See also''': <code>[[Oolite JavaScript Reference: Planet#isMainPlanet|planet.isMainPlanet]]</code>

=== <code>mainStation</code> ===
'''mainStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only)
The system’s main station or <code>null</code> if there is none.

'''See also''': <code>[[Oolite JavaScript Reference: Station#isMainStation|station.isMainStation]]</code>

=== <code>name</code> ===
'''name''' : String (read/write)
The name of the system.

=== <code>planets</code> ===
'''planets''' : Array (read-only)
A list of the planets in the system.

=== <code>population</code> ===
'''population''' : Number (integer, read/write)
The population of the current system.

=== <code>populatorSettings</code> ===
{{oolite-prop-added|1.79}}
'''populatorSettings''' : Dictionary (read-only)
The current [[Oolite_System_Populator|populator settings]]. This is only useful to read while the system population is being prepared. After that point, further changes are meaningless.

'''See Also:''' <code>[[#setPopulator|setPopulator]]</code>

=== <code>productivity</code> ===
'''productivity''' : Number (integer, read/write)
The productivity of the current system.

=== <code>pseudoRandom100</code> ===
'''pseudoRandom100''' : Number (integer, read-only)
A random number between 0 and 99 that is always the same for a given system. '''Important:''' this method has the undesirable side effect of resetting the system random number generator. It should only be used for backwards-compatibility. For new development, use <code>[[#scrambledPseudoRandomNumber|scrambledPseudoRandomNumber]]()</code> or <code>[[#pseudoRandomNumber|pseudoRandomNumber]]</code>.

=== <code>pseudoRandom256</code> ===
'''pseudoRandom256''' : Number (integer, read-only)
A random number between 0 and 255 that is always the same for a given system. '''Important:''' this method has the undesirable side effect of resetting the system random number generator. It should only be used for backwards-compatibility. For new development, use <code>[[#scrambledPseudoRandomNumber|scrambledPseudoRandomNumber]]()</code> or <code>[[#pseudoRandomNumber|pseudoRandomNumber]]</code>.

=== <code>pseudoRandomNumber</code> ===
'''pseudoRandomNumber''' : Number (read-only)
A random number between 0 and 1 that is always the same for a given system. In general, you should avoid using this number directly and call <code>[[#scrambledPseudoRandomNumber|scrambledPseudoRandomNumber]]()</code> instead.

=== <code>stations</code> ===
{{oolite-prop-added|1.79}}
'''stations''' : Array (read-only)
A list of the stations in the system.

=== <code>sun</code> ===
'''sun''' : [[Oolite JavaScript Reference: Sun|Sun]] (read-only)
The system’s sun, or <code>null</code> if there is none.

=== <code>techLevel</code> ===
'''techLevel''' : Number (integer, read/write)
The technology level of the current system, ranging from 0 to 15.

=== <code>wormholes</code> ===
{{oolite-prop-added|1.79}}
'''wormholes''' : Array (read-only)
A list of the [[Oolite_JavaScript_Reference:_Wormhole|wormholes]] in the system.

=== <code>waypoints</code> ===
{{oolite-prop-added|1.79}}
'''waypoints''' : Array (read-only)
A dictionary of the [[Oolite_JavaScript_Reference:_Waypoint|waypoints]] in the system by key and value.

'''See Also:''' <code>[[#setWaypoint|setWaypoint()]]</code>

== Methods ==
=== <code>addGroup</code> ===
function '''addGroup'''(role : String, count : Number [, position: {{oojsvecexpr}}] [, radius: Number]) : {{oojsclass|ShipGroup}}
Like <code>[[#addShips|addShips()]]</code>, but puts the ships in a group and returns the group.

'''See Also:''' <code>[[#addGroupToRoute|addGroupToRoute()]]</code>, <code>[[#addShips|addShips()]]</code>

=== <code>addGroupToRoute</code> ===
function '''addGroupToRoute'''(role : String, count : Number [, fraction: Number] [, route: String]) : {{oojsclass|ShipGroup}}
Like <code>[[#addShipsToRoute|addShipsToRoute()]]</code>, but puts the ships in a group and returns the group.

'''See Also:''' <code>[[#addGroup|addGroup()]]</code>, <code>[[#addShipsToRoute|addShipsToRoute()]]</code>

=== <code>addMoon</code> ===
function '''addMoon'''(planetInfoKey : String) : {{oojsclass|Planet}}
Adds a moon to the system, using the specified entry in ''[[planetinfo.plist]]''. A moon is the same as a planet, except that it has no atmosphere.

'''See Also:''' <code>[[#addPlanet|addPlanet()]]</code>

=== <code>addPlanet</code> ===
function '''addPlanet'''(planetInfoKey : String) : {{oojsclass|Planet}}
Adds a planet to the system, using the specified entry in ''[[planetinfo.plist]]''.

'''See Also:''' <code>[[#addMoon|addMoon()]]</code>

=== <code>addShips</code> ===
function '''addShips'''(role : String, count : Number [, position: {{oojsvecexpr}}] [, radius: Number]) : Array
Adds ships to the system and returns the added ships in an array. Position is in absolute coordinates. When no position is given, the witchpoint is assumed. When no radius is given, the maximum scanner range is used. Ships added in range of the witchpoint automatically create a witchpoint entry cloud.

When you want to use coordinates from the legacy "pwp" system, you can use the [[Oolite_JavaScript_Reference:_Vector3D#fromCoordinateSystem|fromCoordinateSystem]] method to convert legacy type coordinates to absolute coordinates.

If you wish to add ships of a specific shipdata key, pass the key as the "role" parameter, enclosed in square brackets.

'''See Also:''' <code>[[#addGroup|addGroup()]]</code>, <code>[[#addShipsToRoute|addShipsToRoute()]]</code>

=== <code>addShipsToRoute</code> ===
function '''addShipsToRoute'''(role : String, count : Number [, fraction: Number] [, route: String]) : Array
Adds ships to the system on certain common routes and returns the added ships as an array. The routes are the two character codes <code>"wp"</code>, <code>"pw"</code>, <code>"ws"</code>, <code>"sw"</code>, <code>"sp"</code>, and <code>"ps"</code>, where <code>"w"</code> stands for the witchpoint, <code>"p"</code> for the planet and <code>"s"</code> for the sun.

When no route is defined, the route witchpoint → main station is assumed.

The position is a fraction of the route and must be between 0 and 1. Unlike the legacy commands the fraction takes planetary radii in account, so it does not start counting in the centre of sun/planet but from its surface. When no fraction is defined, a random fraction is chosen. Ships are added within scanner range of this position. Ships added in range of the witchpoint automatically create a witchpoint entry cloud.

'''Example''':
var ships = system.addShipsToRoute("myShips", 2, 0.7, "sw")
var pirates = system.addShipsToRoute("pirate", 3, Math.random(), "sp")
The first line adds 2 ships near each-other on the route from sun to witchpoint and puts the added ship in the array <code>ships</code>, and the second line adds a group of 3 pirates at a random position along the sun to planet route and returns the array <code>pirates</code>.

'''Note:''' this method will fail and return <code>null</code> if either of the route end points doesn’t exist. No valid routes exist in interstellar space.

'''See Also:''' <code>[[#addGroupToRoute|addGroupToRoute()]]</code>, <code>[[#addShips|addShips()]]</code>

=== <code>addVisualEffect</code> ===
{{oolite-method-added|1.77}}
function '''addVisualEffect'''(effectKey : String, position: {{oojsvecexpr}}) : VisualEffect
Adds a new visual effect with the effectKey in effectdata to the system, at the specified position, and returns the added effect. If the effectKey does not exist, or creation was otherwise impossible, this method will fail and return <code>null</code>.

Note that unlike the methods for adding ships, <code>addVisualEffect</code> returns a single entity, not an array.

=== <code>countEntitiesWithScanClass</code> ===
function '''countEntitiesWithScanClass'''(scanClass : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Number (integer)
Returns the number of ships with the specified ScanClass in the system.

=== <code>countShipsWithPrimaryRole</code> ===
function '''countShipsWithPrimaryRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Number (integer)
Returns the number of ships with the specified primary role in the system.

=== <code>countShipsWithRole</code> ===
function '''countShipsWithRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Number (integer)
Returns the number of ships with the specified role in the system. Counts not only the primary role the ship is added with but all roles a ship can have.

=== <code>entitiesWithScanClass</code> ===
function '''entitiesWithScanClass'''(scanClass : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
A list of the entities in the system whose scan class is <code>scanClass</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.

'''See Also:''' <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.

=== <code>filteredEntities</code> ===
function '''filteredEntities'''(this : Object, predicate : Function [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
A list of the entities for which <code>predicate</code> returns <code>true</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.

'''Example:'''
this.findIdlePoliceInScannerRange = function()
{
function $isIdlePolice(entity)
{
return entity.isShip && entity.isPolice && !entity.target
}

return system.filteredEntities(this, $isIdlePolice, player.ship, 25600);
}

'''See Also:''' <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>.

=== <code>legacy_addShips etc.</code> ===
function '''legacy_addShips'''(role : String, count : Number)
function '''legacy_addSystemShips'''(role : String, count : Number, position : Number)
function '''legacy_addShipsAt'''(role : String, count : Number, coordscheme : String, where : {{oojsvecexpr}})
function '''legacy_addShipsAtPrecisely'''(role : String, count : Number, coordscheme : String, where : {{oojsclass|Planet}})
function '''legacy_addShipsWithinRadius'''(role : String, count : Number, coordScheme : String, where : {{oojsclass|Planet}}, radius : Number)
function '''legacy_spawnShip'''(shipDataKey : String)
Various ways of causing ships to appear. Each of these corresponds to a legacy scripting method. For more info about the <code>coordScheme</code>, look at [[Oolite coordinate systems]]. These methods are kept for backwards-compatibility; for new development, <code>[[#addShips|addShips()]]</code> is preferred.

'''Important:''' <code>legacy_spawn</code>, previously listed here, never worked as intended and has been replaced with <code>Ship.[[Oolite JavaScript Reference: Ship#spawn|spawn]]()</code>.

=== <code>locationFromCode</code> ===
{{oolite-method-added|1.79}}
function '''locationFromCode'''(code) : Vector
Returns a random location in the region specified by the code string. The code strings are the same as used by the [[Oolite_System_Populator|Oolite populator]]

=== <code>scrambledPseudoRandomNumber</code>===
function '''scrambledPseudoRandomNumber'''(salt : Number (integer)) : Number
Returns a number that’s greater than or equal to zero and less than one. It will always return the same value for a given <code>salt</code> value and system. Crucially, the relationship between systems and numbers is effectively completely different for each salt value, so scripts making similar decisions based on <code>scrambledPseudoRandomNumber()</code> but using different salts will get uncorrelated results. For example, if two different OXPs add a certain type of station to 25% of systems using <code>if (system.pseudoRandomNumber < 0.25)</code>, the two station types will always be found in the same system; using <code>scrambledPseudoRandomNumber()</code> with different salts avoids this.

{{QuoteText|Text=scrambledPseudoRandomNumber, was invented to generate 'random' numbers that are always the same for a given system. Useful to only add stations in certain systems and consistently over time. The salt was added to prevent all oxp's selecting the same 'random' choice for a given system. |Source=([http://oolite.aegidian.org/bb/viewtopic.php?p=193483#p193483 Eric Walch])}}

'''See also''': <code>[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random math.random]</code>

=== <code>sendAllShipsAway</code> ===
function '''sendAllShipsAway'''()
Makes all ships hyperspace out of the system.

=== <code>setPopulator</code> ===
{{oolite-method-added|1.79}}
function '''setPopulator'''(key : String, definition : Object)
Sets the [[Oolite_System_Populator|populator settings]] for the specified key to the given definition, or deletes them if the definition is <code>null</code>. Calling this outside of the system population set up is possible but useless. See the populator settings page for more information on the format of the <code>definition</code> object.

'''See Also:''' <code>[[#populatorSettings|populatorSettings]]</code>

=== <code>setWaypoint</code> ===
{{oolite-method-added|1.79}}
function '''setWaypoint'''(key : String, position : VectorExpression, orientation : QuaternionExpression, parameters : Object)
Adds a [[Oolite_JavaScript_Reference:_Waypoint|waypoint]] to the system with the given <code>key</code>, placed at the specified <code>position</code> and <code>orientation</code>. <code>parameter</code> is an object with the following optional keys:
* '''size''': the radius of the waypoint in metres
* '''beaconCode''': the beacon code (default "W")
* '''beaconLabel''': the beacon label (default "Waypoint")
Waypoints will be visible only when the player has a working Advanced Space Compass.

'''setWaypoint'''(key : String)
Removes the waypoint with the specified <code>key</code>, if it exists.

In Oolite 1.81, waypoints can either be oriented (the 1.80 default) or unoriented. Unoriented waypoints do not display the directional arrows. To create an unoriented waypoint, set its orientation to the zero quaternion (0,0,0,0) either on creation or later.

'''See Also:''' <code>[[#waypoints|waypoints]]</code>

=== <code>shipsWithPrimaryRole</code> ===
function '''shipsWithPrimaryRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
A list of the entities in the system whose [[Oolite JavaScript Reference: Ship#primaryRole|primary role]] is <code>role</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.

'''See Also:''' <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.

=== <code>shipsWithRole</code> ===
function '''shipsWithRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
A list of the entities in the system whose [[Oolite JavaScript Reference: Ship#roles|role set]] contains <code>role</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.

'''See Also:''' <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole()]]</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.

== Static Methods ==
=== <code>infoForSystem</code> ===
function '''infoForSystem'''(galaxyNumber: Integer, systemID : Integer) (write-only)
Overwrites existing info of the given system. As properties it uses the [[planetinfo.plist]] keys. e.g.
System.infoForSystem(0, 55).description = "This is a dull planet."
sets the description of planet nr 55 in galaxy 0 to <code>"This is a dull planet."</code>

Starting from Oolite 1.73, all system Info for the present galaxy is also readable. Even though any galaxy system info property is fully settable, due to engine limitations other galaxies' data is not accessible. In other words
System.infoForSystem(0, 55).description
would return <code>"This is a dull planet."</code> if called from galaxy 0, and throw an exception if called from the other galaxies.

Of particular note the spelling of the '''techlevel''' property when using the infoForSystem method to extract it. While the property of <code>system.'''techLevel'''</code> is spelt using camelCase, <code>System.infoForSystem(0, 55).'''techlevel'''</code> is all lowercase. This is because planetinfo.plist has always had the techlevel key spelt this way.

=== <code>systemIDForName</code> ===
function '''systemIDForName'''(systemName : String) : Integer
Returns the ID number of a system in the current galaxy based on the system name.

'''Note:''' in galaxy 8, there are two systems named <code>"Inzaan"</code>. <code>systemIDForName()</code> will return the lower ID, which is 22.

=== <code>systemNameForID</code> ===
function '''systemNameForID'''(systemID : Integer) : String
Returns the name of a system in the current galaxy based on the given ID number.

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: System

2022-11-11T00:15:29Z

Massively Locked: /* economy */ added link

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

The '''<code>System</code>''' class represents the current star system. There is always one <code>System</code> object, available through the global property <code>system</code>.

Attempts to change system properties are ignored in interstellar space (i.e., the place you end up in after a witchspace malfunction).

== Properties ==
=== <code>allShips</code> ===
'''allShips''' : Array (read-only)
A list of the ships in the system.

'''See Also:''' <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>, <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>

=== <code>allVisualEffects</code> ===
{{oolite-prop-added|1.77}}
'''allVisualEffects''' : Array (read-only)
A list of the [[Oolite_JavaScript_Reference:_VisualEffect|visual effects]] in the system.

=== <code>ambientLevel</code> ===
{{oolite-prop-added|1.81}}
'''ambientLevel''' : float (read/write)
Adjusts the level of ambient light in the current system. Values should typically be between 0.0 and 1.0 (1.0 is the default) but can be higher for a flat lit, cartoon-like effect. This is will override the "ambient_level" setting defined in [[Planetinfo.plist]]. The change is not permanent and will be reset when the system is reloaded.

=== <code>breakPattern</code> ===
{{oolite-prop-added|1.77}}
'''breakPattern''' : Boolean (read/write)
If <code>true</code> (the default state set on entry to a new system), the break pattern will be shown to the player as they exit witchspace. While this property may be set from places other than the <code>shipWillExitWitchspace</code> world script event, it is pointless to do so.

Unlike all other system properties, this one may be changed on entry to interstellar space.

=== <code>description</code> ===
'''description''' : String (read/write)
The description of the current system, as seen on the planet info screen.

=== <code>economy</code> ===
'''economy''' : Number (integer, read/write)
The type of economy in the current system, ranging from 0 (Rich Industrial) to 7 (Poor Agricultural).

'''See Also:''' [[Planetinfo.plist#Economy|Planetinfo.plist]], <code>[[#economyDescription|economyDescription]]</code>

=== <code>economyDescription</code> ===
'''economyDescription''' : String (read-only)
A localized description of the economy type, for example, <code>"Mostly Industrial"</code>. Since this string is localized, it should only be used for display purposes.

'''See Also:''' <code>[[#economy|economy]]</code>

=== <code>government</code> ===
'''government''' : Number (read/write, integer)
The type of government in the current system, ranging from 0 (Anarchy) to 7 (Corporate State).

'''See Also:''' <code>[[#governmentDescription|governmentDescription]]</code>

=== <code>governmentDescription</code> ===
'''governmentDescription''' : String (read-only)
A localized description of the government type, for example, <code>"Democracy"</code>. Since this string is localized, it should only be used for display purposes.

'''See Also:''' <code>[[#government|government]]</code>

=== <code>ID</code> ===
'''ID''' : Number (integer, read-only)
A number identifying the system. 0 to 255, or -1 for interstellar space.

=== <code>info</code> ===
'''info''' : [[Oolite JavaScript Reference: SystemInfo|SystemInfo]] (read/write)
Allows access to system properties, using the same keys as [[planetinfo.plist]].

'''Example:'''
system.info.description = "This is a dull planet.";

=== <code>inhabitantsDescription</code> ===
'''inhabitantsDescription''' : String (read/write)
The description of the inhabitants of the current system, such as <code>"Slimy Blue Frogs"</code>.

=== <code>isInterstellarSpace</code> ===
'''isInterstellarSpace''' : Boolean (read-only)
<code>true</code> if the current system is in interstellar space, <code>false</code> otherwise.

=== <code>mainPlanet</code> ===
'''mainPlanet''' : {{oojsclass|Planet}} (read-only)
The system’s main planet, or <code>null</code> if there is none.

'''See also''': <code>[[Oolite JavaScript Reference: Planet#isMainPlanet|planet.isMainPlanet]]</code>

=== <code>mainStation</code> ===
'''mainStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only)
The system’s main station or <code>null</code> if there is none.

'''See also''': <code>[[Oolite JavaScript Reference: Station#isMainStation|station.isMainStation]]</code>

=== <code>name</code> ===
'''name''' : String (read/write)
The name of the system.

=== <code>planets</code> ===
'''planets''' : Array (read-only)
A list of the planets in the system.

=== <code>population</code> ===
'''population''' : Number (integer, read/write)
The population of the current system.

=== <code>populatorSettings</code> ===
{{oolite-prop-added|1.79}}
'''populatorSettings''' : Dictionary (read-only)
The current [[Oolite_System_Populator|populator settings]]. This is only useful to read while the system population is being prepared. After that point, further changes are meaningless.

'''See Also:''' <code>[[#setPopulator|setPopulator]]</code>

=== <code>productivity</code> ===
'''productivity''' : Number (integer, read/write)
The productivity of the current system.

=== <code>pseudoRandom100</code> ===
'''pseudoRandom100''' : Number (integer, read-only)
A random number between 0 and 99 that is always the same for a given system. '''Important:''' this method has the undesirable side effect of resetting the system random number generator. It should only be used for backwards-compatibility. For new development, use <code>[[#scrambledPseudoRandomNumber|scrambledPseudoRandomNumber]]()</code> or <code>[[#pseudoRandomNumber|pseudoRandomNumber]]</code>.

=== <code>pseudoRandom256</code> ===
'''pseudoRandom256''' : Number (integer, read-only)
A random number between 0 and 255 that is always the same for a given system. '''Important:''' this method has the undesirable side effect of resetting the system random number generator. It should only be used for backwards-compatibility. For new development, use <code>[[#scrambledPseudoRandomNumber|scrambledPseudoRandomNumber]]()</code> or <code>[[#pseudoRandomNumber|pseudoRandomNumber]]</code>.

=== <code>pseudoRandomNumber</code> ===
'''pseudoRandomNumber''' : Number (read-only)
A random number between 0 and 1 that is always the same for a given system. In general, you should avoid using this number directly and call <code>[[#scrambledPseudoRandomNumber|scrambledPseudoRandomNumber]]()</code> instead.

=== <code>stations</code> ===
{{oolite-prop-added|1.79}}
'''stations''' : Array (read-only)
A list of the stations in the system.

=== <code>sun</code> ===
'''sun''' : [[Oolite JavaScript Reference: Sun|Sun]] (read-only)
The system’s sun, or <code>null</code> if there is none.

=== <code>techLevel</code> ===
'''techLevel''' : Number (integer, read/write)
The technology level of the current system, ranging from 0 to 15.

=== <code>wormholes</code> ===
{{oolite-prop-added|1.79}}
'''wormholes''' : Array (read-only)
A list of the [[Oolite_JavaScript_Reference:_Wormhole|wormholes]] in the system.

=== <code>waypoints</code> ===
{{oolite-prop-added|1.79}}
'''waypoints''' : Array (read-only)
A dictionary of the [[Oolite_JavaScript_Reference:_Waypoint|waypoints]] in the system by key and value.

'''See Also:''' <code>[[#setWaypoint|setWaypoint()]]</code>

== Methods ==
=== <code>addGroup</code> ===
function '''addGroup'''(role : String, count : Number [, position: {{oojsvecexpr}}] [, radius: Number]) : {{oojsclass|ShipGroup}}
Like <code>[[#addShips|addShips()]]</code>, but puts the ships in a group and returns the group.

'''See Also:''' <code>[[#addGroupToRoute|addGroupToRoute()]]</code>, <code>[[#addShips|addShips()]]</code>

=== <code>addGroupToRoute</code> ===
function '''addGroupToRoute'''(role : String, count : Number [, fraction: Number] [, route: String]) : {{oojsclass|ShipGroup}}
Like <code>[[#addShipsToRoute|addShipsToRoute()]]</code>, but puts the ships in a group and returns the group.

'''See Also:''' <code>[[#addGroup|addGroup()]]</code>, <code>[[#addShipsToRoute|addShipsToRoute()]]</code>

=== <code>addMoon</code> ===
function '''addMoon'''(planetInfoKey : String) : {{oojsclass|Planet}}
Adds a moon to the system, using the specified entry in ''[[planetinfo.plist]]''. A moon is the same as a planet, except that it has no atmosphere.

'''See Also:''' <code>[[#addPlanet|addPlanet()]]</code>

=== <code>addPlanet</code> ===
function '''addPlanet'''(planetInfoKey : String) : {{oojsclass|Planet}}
Adds a planet to the system, using the specified entry in ''[[planetinfo.plist]]''.

'''See Also:''' <code>[[#addMoon|addMoon()]]</code>

=== <code>addShips</code> ===
function '''addShips'''(role : String, count : Number [, position: {{oojsvecexpr}}] [, radius: Number]) : Array
Adds ships to the system and returns the added ships in an array. Position is in absolute coordinates. When no position is given, the witchpoint is assumed. When no radius is given, the maximum scanner range is used. Ships added in range of the witchpoint automatically create a witchpoint entry cloud.

When you want to use coordinates from the legacy "pwp" system, you can use the [[Oolite_JavaScript_Reference:_Vector3D#fromCoordinateSystem|fromCoordinateSystem]] method to convert legacy type coordinates to absolute coordinates.

If you wish to add ships of a specific shipdata key, pass the key as the "role" parameter, enclosed in square brackets.

'''See Also:''' <code>[[#addGroup|addGroup()]]</code>, <code>[[#addShipsToRoute|addShipsToRoute()]]</code>

=== <code>addShipsToRoute</code> ===
function '''addShipsToRoute'''(role : String, count : Number [, fraction: Number] [, route: String]) : Array
Adds ships to the system on certain common routes and returns the added ships as an array. The routes are the two character codes <code>"wp"</code>, <code>"pw"</code>, <code>"ws"</code>, <code>"sw"</code>, <code>"sp"</code>, and <code>"ps"</code>, where <code>"w"</code> stands for the witchpoint, <code>"p"</code> for the planet and <code>"s"</code> for the sun.

When no route is defined, the route witchpoint → main station is assumed.

The position is a fraction of the route and must be between 0 and 1. Unlike the legacy commands the fraction takes planetary radii in account, so it does not start counting in the centre of sun/planet but from its surface. When no fraction is defined, a random fraction is chosen. Ships are added within scanner range of this position. Ships added in range of the witchpoint automatically create a witchpoint entry cloud.

'''Example''':
var ships = system.addShipsToRoute("myShips", 2, 0.7, "sw")
var pirates = system.addShipsToRoute("pirate", 3, Math.random(), "sp")
The first line adds 2 ships near each-other on the route from sun to witchpoint and puts the added ship in the array <code>ships</code>, and the second line adds a group of 3 pirates at a random position along the sun to planet route and returns the array <code>pirates</code>.

'''Note:''' this method will fail and return <code>null</code> if either of the route end points doesn’t exist. No valid routes exist in interstellar space.

'''See Also:''' <code>[[#addGroupToRoute|addGroupToRoute()]]</code>, <code>[[#addShips|addShips()]]</code>

=== <code>addVisualEffect</code> ===
{{oolite-method-added|1.77}}
function '''addVisualEffect'''(effectKey : String, position: {{oojsvecexpr}}) : VisualEffect
Adds a new visual effect with the effectKey in effectdata to the system, at the specified position, and returns the added effect. If the effectKey does not exist, or creation was otherwise impossible, this method will fail and return <code>null</code>.

Note that unlike the methods for adding ships, <code>addVisualEffect</code> returns a single entity, not an array.

=== <code>countEntitiesWithScanClass</code> ===
function '''countEntitiesWithScanClass'''(scanClass : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Number (integer)
Returns the number of ships with the specified ScanClass in the system.

=== <code>countShipsWithPrimaryRole</code> ===
function '''countShipsWithPrimaryRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Number (integer)
Returns the number of ships with the specified primary role in the system.

=== <code>countShipsWithRole</code> ===
function '''countShipsWithRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Number (integer)
Returns the number of ships with the specified role in the system. Counts not only the primary role the ship is added with but all roles a ship can have.

=== <code>entitiesWithScanClass</code> ===
function '''entitiesWithScanClass'''(scanClass : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
A list of the entities in the system whose scan class is <code>scanClass</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.

'''See Also:''' <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.

=== <code>filteredEntities</code> ===
function '''filteredEntities'''(this : Object, predicate : Function [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
A list of the entities for which <code>predicate</code> returns <code>true</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.

'''Example:'''
this.findIdlePoliceInScannerRange = function()
{
function $isIdlePolice(entity)
{
return entity.isShip && entity.isPolice && !entity.target
}

return system.filteredEntities(this, $isIdlePolice, player.ship, 25600);
}

'''See Also:''' <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>.

=== <code>legacy_addShips etc.</code> ===
function '''legacy_addShips'''(role : String, count : Number)
function '''legacy_addSystemShips'''(role : String, count : Number, position : Number)
function '''legacy_addShipsAt'''(role : String, count : Number, coordscheme : String, where : {{oojsvecexpr}})
function '''legacy_addShipsAtPrecisely'''(role : String, count : Number, coordscheme : String, where : {{oojsclass|Planet}})
function '''legacy_addShipsWithinRadius'''(role : String, count : Number, coordScheme : String, where : {{oojsclass|Planet}}, radius : Number)
function '''legacy_spawnShip'''(shipDataKey : String)
Various ways of causing ships to appear. Each of these corresponds to a legacy scripting method. For more info about the <code>coordScheme</code>, look at [[Oolite coordinate systems]]. These methods are kept for backwards-compatibility; for new development, <code>[[#addShips|addShips()]]</code> is preferred.

'''Important:''' <code>legacy_spawn</code>, previously listed here, never worked as intended and has been replaced with <code>Ship.[[Oolite JavaScript Reference: Ship#spawn|spawn]]()</code>.

=== <code>locationFromCode</code> ===
{{oolite-method-added|1.79}}
function '''locationFromCode'''(code) : Vector
Returns a random location in the region specified by the code string. The code strings are the same as used by the [[Oolite_System_Populator|Oolite populator]]

=== <code>scrambledPseudoRandomNumber</code>===
function '''scrambledPseudoRandomNumber'''(salt : Number (integer)) : Number
Returns a number that’s greater than or equal to zero and less than one. It will always return the same value for a given <code>salt</code> value and system. Crucially, the relationship between systems and numbers is effectively completely different for each salt value, so scripts making similar decisions based on <code>scrambledPseudoRandomNumber()</code> but using different salts will get uncorrelated results. For example, if two different OXPs add a certain type of station to 25% of systems using <code>if (system.pseudoRandomNumber < 0.25)</code>, the two station types will always be found in the same system; using <code>scrambledPseudoRandomNumber()</code> with different salts avoids this.

{{QuoteText|Text=scrambledPseudoRandomNumber, was invented to generate 'random' numbers that are always the same for a given system. Useful to only add stations in certain systems and consistently over time. The salt was added to prevent all oxp's selecting the same 'random' choice for a given system. |Source=([http://oolite.aegidian.org/bb/viewtopic.php?p=193483#p193483 Eric Walch])}}

'''See also''': <code>[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random math.random]</code>

=== <code>sendAllShipsAway</code> ===
function '''sendAllShipsAway'''()
Makes all ships hyperspace out of the system.

=== <code>setPopulator</code> ===
{{oolite-method-added|1.79}}
function '''setPopulator'''(key : String, definition : Object)
Sets the [[Oolite_System_Populator|populator settings]] for the specified key to the given definition, or deletes them if the definition is <code>null</code>. Calling this outside of the system population set up is possible but useless. See the populator settings page for more information on the format of the <code>definition</code> object.

'''See Also:''' <code>[[#populatorSettings|populatorSettings]]</code>

=== <code>setWaypoint</code> ===
{{oolite-method-added|1.79}}
function '''setWaypoint'''(key : String, position : VectorExpression, orientation : QuaternionExpression, parameters : Object)
Adds a [[Oolite_JavaScript_Reference:_Waypoint|waypoint]] to the system with the given <code>key</code>, placed at the specified <code>position</code> and <code>orientation</code>. <code>parameter</code> is an object with the following optional keys:
* '''size''': the radius of the waypoint in metres
* '''beaconCode''': the beacon code (default "W")
* '''beaconLabel''': the beacon label (default "Waypoint")
Waypoints will be visible only when the player has a working Advanced Space Compass.

'''setWaypoint'''(key : String)
Removes the waypoint with the specified <code>key</code>, if it exists.

In Oolite 1.81, waypoints can either be oriented (the 1.80 default) or unoriented. Unoriented waypoints do not display the directional arrows. To create an unoriented waypoint, set its orientation to the zero quaternion (0,0,0,0) either on creation or later.

'''See Also:''' <code>[[#waypoints|waypoints]]</code>

=== <code>shipsWithPrimaryRole</code> ===
function '''shipsWithPrimaryRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
A list of the entities in the system whose [[Oolite JavaScript Reference: Ship#primaryRole|primary role]] is <code>role</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.

'''See Also:''' <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.

=== <code>shipsWithRole</code> ===
function '''shipsWithRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
A list of the entities in the system whose [[Oolite JavaScript Reference: Ship#roles|role set]] contains <code>role</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.

'''See Also:''' <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole()]]</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.

== Static Methods ==
=== <code>infoForSystem</code> ===
function '''infoForSystem'''(galaxyNumber: Integer, systemID : Integer) (write-only)
Overwrites existing info of the given system. As properties it uses the [[planetinfo.plist]] keys. e.g.
System.infoForSystem(0, 55).description = "This is a dull planet."
sets the description of planet nr 55 in galaxy 0 to <code>"This is a dull planet."</code>

Starting from Oolite 1.73, all system Info for the present galaxy is also readable. Even though any galaxy system info property is fully settable, due to engine limitations other galaxies' data is not accessible. In other words
System.infoForSystem(0, 55).description
would return <code>"This is a dull planet."</code> if called from galaxy 0, and throw an exception if called from the other galaxies.

Of particular note the spelling of the '''techlevel''' property when using the infoForSystem method to extract it. While the property of <code>system.'''techLevel'''</code> is spelt using camelCase, <code>System.infoForSystem(0, 55).'''techlevel'''</code> is all lowercase. This is because planetinfo.plist has always had the techlevel key spelt this way.

=== <code>systemIDForName</code> ===
function '''systemIDForName'''(systemName : String) : Integer
Returns the ID number of a system in the current galaxy based on the system name.

'''Note:''' in galaxy 8, there are two systems named <code>"Inzaan"</code>. <code>systemIDForName()</code> will return the lower ID, which is 22.

=== <code>systemNameForID</code> ===
function '''systemNameForID'''(systemID : Integer) : String
Returns the name of a system in the current galaxy based on the given ID number.

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Global

2022-11-08T13:06:41Z

Massively Locked: /* galaxyNumber */ added link

Global variables and functions are visible to all scripts. They are also properties of <code>[[#global|global]]</code>, which is itself a global variable and hence a property of itself.

== Properties ==
=== <code>clock</code> ===
'''clock''' : {{oojsclass|Clock}} (read-only)
This property allows an OXP to access the game clock's properties and methods.

=== <code>defaultFont</code> ===
'''defaultFont''' : Object (read-only)
An object with a single method, <code>measureString(string)</code>, which returns the width of the specified string, as it would be shown on the screen, in '''ems'''. One em is the intrinsic unit size of a font; for example, if a font is rendered at 12 points, 1 em = 12 pt. The mission screen text area is 32 em wide.

=== <code>galaxyNumber</code> ===
'''galaxyNumber''' : Number (read-only)
Returns the number of the galaxy the player is in.

'''See also''': <code>[[Oolite JavaScript Reference: SystemInfo#galaxyID|galaxyID]]</code>

=== <code>global</code> ===
'''global''' : Global (read-only)
All global variables and functions are actually properties of the global object. The global object is a property of itself, and this is it.

=== <code>guiScreen</code> ===
'''guiScreen''' : String (read-only)
Returns the screen the player is looking at. If in flight, this is <code>"GUI_SCREEN_MAIN"</code>. In 1.76, the other possible values are <code>"GUI_SCREEN_INTRO1"</code>, <code>"GUI_SCREEN_INTRO2"</code>, <code>"GUI_SCREEN_STATUS"</code>(F5), <code>"GUI_SCREEN_MANIFEST"</code>(F5F5), <code>"GUI_SCREEN_EQUIP_SHIP"</code>(F3), <code>"GUI_SCREEN_SHIPYARD"</code>(F3F3), <code>"GUI_SCREEN_LONG_RANGE_CHART"</code>(F6F6), <code>"GUI_SCREEN_SHORT_RANGE_CHART"</code>(F6), <code>"GUI_SCREEN_SYSTEM_DATA"</code>(F7), <code>"GUI_SCREEN_MARKET"</code>(F8), <code>"GUI_SCREEN_CONTRACTS"</code>, <code>"GUI_SCREEN_OPTIONS"</code>, <code>"GUI_SCREEN_GAMEOPTIONS"</code>, <code>"GUI_SCREEN_LOAD"</code>, <code>"GUI_SCREEN_SAVE"</code>, <code>"GUI_SCREEN_SAVE_OVERWRITE"</code>, <code>"GUI_SCREEN_STICKMAPPER"</code>, <code>"GUI_SCREEN_MISSION"</code> and <code>"GUI_SCREEN_REPORT"</code>.

In 1.77, <code>"GUI_SCREEN_INTERFACES"</code>(F4) is added, and <code>"GUI_SCREEN_CONTRACTS"</code> is removed.

In 1.81, <code>"GUI_SCREEN_MARKETINFO"</code>(F8F8) is added.

=== <code>manifest</code> ===
'''manifest''' : {{oojsclass|Manifest}} (read-only)
An alias to <code>[[Oolite JavaScript Reference: PlayerShip#manifest|player.ship.manifest]]</code>.

=== <code>mission</code> ===
'''mission''' : {{oojsclass|Mission}} (read-only)
See [[Oolite JavaScript Reference: Mission]].

=== <code>missionVariables</code> ===
'''missionVariables''' : Object (read-only)
The <code>missionVariables</code> object stores values that are stored in saved games. This is the main way for scripts to store information permanently.

Whenever a value is assigned to a property of <code>missionVariables</code>, it is converted to a string object and tracked with the player. When the value is read, it will be converted to a number if possible, otherwise returned as a string. Example:
missionVariables.exampleVar = 42;
let x = missionVariables.exampleVar; // x is now the number 42
Do not use <code>false</code> in missionVariables! It will return <code>true</code> because it will be parsed as a string. Use 0 or 1 to store boolean values.

You can store arrays using [http://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON JSON] stringify and parse methods. For example:
this.$MyArray = [];

this.startUp = function() {
var s = missionVariables.$MyArray;
if( s && s.length > 0 ) this.$MyArray = JSON.parse(s);
}

this.playerWillSaveGame = function(message) {
missionVariables.$MyArray = JSON.stringify(this.$MyArray);
}
Mission variables can also be used in legacy scripts and in [[descriptions.plist]] string expansions, by prefixing the name with <code>"mission_"</code>. Example:
expandDescription("My variable is [mission_exampleVar].")
Setting and retrieving mission variables has a significant overhead'''*'''. If a function needs to use a mission variable value several times, it is strongly recommended that it be copied into a local variable and, if necessary, stored back once. Example:
let x = missionVariables.exampleVar;
if (x < 3) x = processSmallValue(x);
else x = processBigValue(x);
missionVariables.exampleVar = x;
Mission variable names may not begin with an underscore (“_”). Unassigned mission variables are always <code>null</code>.

'''*''' On a computer where the loop <code>for (var i = 0; i < 1000; i++) {}</code> takes just 0.62 msec, the same loop with missionVarriables <code>for (missionVariables.i = 0; missionVariables.i < 1000; missionVariables.i++) {}</code> consumes a full 38 msec. That is 60 times longer.

=== <code>oolite</code> ===
'''oolite''' : {{oojsclass|Oolite}} (read-only)
An object describing properties of the Oolite application; see [[Oolite JavaScript Reference: Oolite]].

=== <code>player</code> ===
'''player''' : {{oojsclass|Player}} (read-only)
This property allows an OXP to access the player object's properties and methods.

=== <code>system</code> ===
'''system''' : {{oojsclass|System}} (read-only)
This property allows an OXP to access the current system's properties and methods.

=== <code>timeAccelerationFactor</code> ===
'''timeAccelerationFactor''' : Number (read/write)
Also known as TAF. Will change the ratio between game real time and actual real time (default is 1). The accepted range is between 0.0625 (1/16) and 16. Attempting to set numbers outside this range will reset the TAF to 1. (In end-user stable builds, this will be a read-only property with the value 1.)

=== <code>worldScriptNames</code> ===
'''worldScriptNames''' : Array of strings (read-only)
A list of the names of world script objects, the keys of <code>[[#worldScripts|worldScripts]]</code>.

=== <code>worldScripts</code> ===
'''worldScripts''' : Object (read-only)
All loaded world script objects. The keys are the <code>name</code> properties of the scripts.

'''Example:'''
log(worldScripts["oolite-nova"].version);

== Methods ==
=== <code>addFrameCallback</code> ===
function '''addFrameCallback'''(callback : Function) : ''TrackingID''
Registers a ''frame callback'' which will be invoked every frame, after entity updates but before rendering. This can be used to implement animations, to apply gradual changes in ship state, to build large data structures without risking reaching processing time limits by trying to do it all at once, or to watch variables which need a same-frame response to changes. The return value is a ''tracking ID'' which may be passed to <code>[[#removeFrameCallback|removeFrameCallback()]]</code>; the type and meaning of the tracking ID is unspecified and may change at any time. Frame callbacks are automatically removed when the game resets (for instance, when the player dies), but not at any other time.

The callback is passed one parameter, <code>delta</code>, which is the time since the last frame (in [[Time_scales in Oolite|game clock time]]). Frame callbacks fire even when the game is paused, in which case <code>delta</code> is 0.

'''Example:'''
var sum = 0;
this.$fcb = addFrameCallback(function (delta)
{
sum += delta;
log("Time elapsed: " + sum + " (delta: " + delta + ")");
});

'''See also:''' <code>[[#removeFrameCallback|removeFrameCallback()]]</code>, <code>[[#isValidFrameCallback|isValidFrameCallback()]]</code>, and for repeated events with a longer repeat interval, use [[Oolite_JavaScript_Reference:_Timer|Timers]] instead.

=== <code>displayNameForCommodity</code> ===
function '''displayNameForCommodity'''(commodityName : String) : String
Returns the display name corresponding to the specified commodity. Useful in conjunction with localisation OXPs, or expansions that rename commodities depending on which station / system the player is at.

=== <code>expandDescription</code> ===
function '''expandDescription'''(description : String [, locals : Object (Dictionary)]) : String
Expands a string, substituting special tokens and any key inside square brackets with the substitution rules for [[Missiontext.plist#Special_Expansions|string expansions]].
When local key/value pairs are provided, they take precedence over any other values.

In Oolite 1.79 or later, this method uses a higher quality random number generator which does not have noticeable correlation problems when used for recursive expansion.

'''Example:'''
expandDescription("My ball is [my_color].", { my_color: "red" });

=== <code>expandMissionText</code> ===
function '''expandMissionText'''(textKey: String [, locals : Object (Dictionary)]) : String
Load a string specified by <code>textKey</code> from [[missiontext.plist]], then perform <code>[[#expandDescription|expandDescription()]]</code>type substitutions on it, and also replace <code>"\n"</code> with line breaks. The <code>local</code> parameter works as with <code>[[#expandDescription|expandDescription()]]</code>.

In Oolite 1.79 or later, this method uses a higher quality random number generator which does not have noticeable correlation problems when used for recursive expansion.

'''Example:'''
expandMissionText("oolite_trumble_title");

=== <code>formatCredits</code> ===
function '''formatCredits'''(value : number, [includeDeciCredits : boolean, [includeCurrencySymbol : boolean]]) : String
Converts the <code>value</code> parameter to a string formatted in a currency friendly manner. If <code>includeDeciCredits</code> is <code>true</code> the string will be formatted to 1 decimal place. If <code>includeCurrencySymbol</code> is <code>true</code> an appropriate currency symbol following any localisation rules is included. The default currency symbol is a terminal ₢.

=== <code>formatInteger</code> ===
function '''formatInteger'''(value : number) : String
Converts the <code>value</code> parameter to a string formatted as an integer following any localisation rules in place.

=== <code>getGuiColorSettingForKey</code> ===
{{oolite-method-added|1.87}}
function '''getGuiColorSettingForKey'''(keyname : string) : Array
Returns the current color for a particular keyname (referenced in the [[gui-settings.plist]] file). Returns an array of RGBA values.

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

=== <code>getScreenBackgroundForKey</code> ===
{{oolite-method-added|1.85}}
function '''getScreenBackgroundForKey'''(keyname : string) : guiTextureSpecifier
Returns the guiTextureSpecifier for a particular keyname (referenced in the screenbackgrounds.plist file).

''guiTextureSpecifier'' can be either a string or an object with the required key <code>name</code> and optional keys <code>width</code> and <code>height</code>. If neither width nor height is specified, the dimensions of the image are used. If only one is specified, the other is calculated such that the image is not distorted. The scale unit is 1/480 of the height of the window; in other words, the window is always considered 480 units high, and the width depends on the aspect ratio of the window.

'''Example:'''
getScreenBackgroundForKey("long_range_chart_mission");

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

=== <code>isValidFrameCallback</code> ===
function '''isValidFrameCallback'''(trackingID: ''TrackingID'') : Boolean
Returns <code>true</code> if <code>trackingID</code> identifies a frame callback which has been registered with <code>[[#addFrameCallback|addFrameCallback()]]</code> and not yet removed. (There should be no need to use this except for debugging and testing.)

'''See also:''' <code>[[#addFrameCallback|addFrameCallback()]]</code>, <code>[[#removeFrameCallback|removeFrameCallback()]]</code>

=== <code>log</code> ===
function '''log'''([messageClass : String ,] message : String)
Writes a message to Oolite's log. The optional messageClass parameter can be used to specify which type of message is written to the log. The default messageClass is <code>script.debug.message</code>. When set to <code>true</code>, the messages will be written to the log file. The classes to be logged are set in the file <code>logcontrol.plist</code>. messageClasses not listed in <code>logcontrol.plist</code> are always logged.

'''Example:'''
log("myOXP.init","MyOXP initialised and ready!");

You can temporarily enable/disable logging the above message by typing in the console:
console.setDisplayMessagesInClass("myOXP.init", true/false)

===<code>pauseGame</code>===
function '''pauseGame'''() : Boolean
Pauses the game. It does not work on screens that cannot be paused by keyboard: mission screens, long range chart, arrival report, save menu. In those cases, the method returns <code>false</code>. Otherwise, it pauses the game and returns <code>true</code>.

This was added in v1.87 (the exact version is unconfirmed)

'''See also:''' [http://aegidian.org/bb/viewtopic.php?f=6&t=18900 Scriptable pause?]

=== <code>randomInhabitantsDescription</code> ===
function '''randomInhabitantsDescription'''([plural : boolean, default true]) : String
Returns a random sentient species name, like <code>"Large Red Fat Insects"</code> or <code>"Human Colonials"</code>, following the same pattern (and probability distribution) as for planet inhabitants.

'''Example:'''
player.consoleMessage("You'll meet a " + randomInhabitantsDescription(false) + ". She'll be with a group of " + randomInhabitantsDescription() + ".");

=== <code>randomName</code> ===
function '''randomName'''() : String
Returns a random capitalised word, suitable for use as name, or indeed surname.

'''Example:'''
player.consoleMessage(randomName() + " " + randomName() + " rules this system with an iron fist.");

=== <code>removeFrameCallback</code> ===
function '''removeFrameCallback'''(trackingID : ''TrackingID'')
Removes a frame callback previously registered with <code>[[#addFrameCallback|addFrameCallback()]]</code>.

'''See also:''' <code>[[#addFrameCallback|addFrameCallback()]]</code>, <code>[[#isValidFrameCallback|isValidFrameCallback()]]</code>

=== <code>setGuiColorSettingForKey</code> ===
{{oolite-method-added|1.87}}
function '''setGuiColorSettingorKey'''(keyname : string , [[Materials_in_Oolite#Colour_specifiers|Colour specifier]] : string)
Override the color setting for a particular keyname (referenced in the [[gui-settings.plist]] file) with the specified color. This override is only for the current play-session and does not get written to [[gui-settings.plist]].

'''Example:'''
setGuiColorSettingForKey("screen_title_color", "whiteColor");

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

=== <code>setScreenBackground</code> ===
function '''setScreenBackground'''(image : ''guiTextureSpecifier'')
Temporary override that sets the background of the current gui screen to the specified image. Override is lost after the player switches screens.

''guiTextureSpecifier'' can be either a string or an object with the required key <code>name</code> and optional keys <code>width</code> and <code>height</code>. If neither width nor height is specified, the dimensions of the image are used. If only one is specified, the other is calculated such that the image is not distorted. The scale unit is 1/480 of the height of the window; in other words, the window is always considered 480 units high, and the width depends on the aspect ratio of the window.

'''Example:'''
setScreenBackground({ name: "oolite-nova-system.png", height: 480 });

=== <code>setScreenBackgroundForKey</code> ===
{{oolite-method-added|1.85}}
function '''setScreenBackgroundForKey'''(keyname : string, image : ''guiTextureSpecifier'')
Override the background for a particular keyname (referenced in the screenbackgrounds.plist file) with the specified image. Override is only for the current play-session only and does not get written out to screenbackgrounds.plist.

''guiTextureSpecifier'' can be either a string or an object with the required key <code>name</code> and optional keys <code>width</code> and <code>height</code>. If neither width nor height is specified, the dimensions of the image are used. If only one is specified, the other is calculated such that the image is not distorted. The scale unit is 1/480 of the height of the window; in other words, the window is always considered 480 units high, and the width depends on the aspect ratio of the window.

'''Example:'''
setScreenBackgroundForKey("long_range_chart_mission", { name: "my_mission_background.png", height: 480 });

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

=== <code>setScreenOverlay</code> ===
function '''setScreenOverlay'''(image : ''guiTextureSpecifier'')
Temporary override that sets the overlay of the current gui screen to the specified image. Override is lost after the player switches screens.

See <code>[[#setScreenBackground|setScreenBackground()]]</code> for a discussion of ''guiTextureSpecifier''.

'''Example:'''
setScreenOverlay('trumblebox.png');

=== <code>takeSnapShot</code> ===
function '''takeSnapShot'''([filename : String]) : Boolean
Saves a snapshot of the current screen to your hard disk. A filename is optional. When a name is used, only alphanumeric values and <code>"-"</code> and <code>"_"</code> are allowed for the filename. The appropriate extension for the used operating system (like .png) is added by Oolite and should not be part of the filename. 
When a filename already exists, it is not overwritten but the string <code>"-xxx"</code> is added, starting with <code>"-001"</code>. 
<code>takeSnapShot()</code> will not be available in the stable release version of Oolite, but will be available in a special OXP developer release.

'''Example:'''
takeSnapShot('mission_target_1');

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: SystemInfo

2022-11-08T13:02:44Z

Massively Locked: /* galaxyID */ added link

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

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

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

== Properties ==
=== <code>coordinates</code> ===
'''coordinates''' : {{oojsclass|Vector3D}} (read-only)
The coordinates of the system in light years. e.g. for Lave: <code>(8, 34.6, 0)</code>. The z component is always zero.

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.

'''Example:'''
System.infoForSystem(galaxyNumber, 7).coordinates
returns the coordinates of the system with an ID number of 7 in the current galaxy. In the first galaxy that would be the coordinates for Lave: <code>(8, 34.6, 0)</code>.

=== <code>galaxyID</code> ===
'''galaxyID''' : Number (read-only nonnegative integer)
The ID number of the galaxy.

'''See also''': <code>[[Oolite JavaScript Reference: Global#galaxyNumber|galaxyNumber]]</code>

=== <code>internalCoordinates</code> ===
'''internalCoordinates''' : {{oojsclass|Vector3D}} (read-only)
'''Discouraged in favour of <code>[[#coordinates|coordinates]]</code>.''' 
The coordinate of the system in the internal coordinate system.

=== <code>systemID</code> ===
'''systemID''' : Number (read-only nonnegative integer)
The ID number of the system.

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

'''Example:'''
<code>system.info.description = "This is a dull planet."</code>
sets the description of the current planet to “This is a dull planet.”

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

== Methods ==
=== <code>distanceToSystem</code> ===
function '''distanceToSystem'''(system : SystemInfo) : Number
Returns the distance in light years to another <code>SystemInfo</code>.

'''Example:'''
System.infoForSystem(galaxyNumber, 7).distanceToSystem(System.infoForSystem(galaxyNumber, 8))
If galaxyNumber is 0, this returns 92.8.

=== <code>routeToSystem</code> ===
function '''routeToSystem'''(system : SystemInfo [, "OPTIMIZED_BY_JUMPS" | "OPTIMIZED_BY_TIME"] ) : Object
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.

'''Example:'''
var myRoute = System.infoForSystem(galaxyNumber, 7).routeToSystem(System.infoForSystem(galaxyNumber, 8))
myRoute.route
myRoute.distance
myRoute.time
returns:
7,129,227,73,89,222,29,42,131,62,150,36,28,16,185,86,138,51,8 (the route)
96.40 (distance of added jumps)
530.40 (travelled time)

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

=== <code>samplePrice</code> ===
{{oolite-method-added|1.81}}
function '''samplePrice'''(commodity : String) : Array
Return a sample main market price in decicredits for the commodity with that key in this system. As this requires reading system information, it will only work for systems in the current galaxy. There is of course no guarantee that the price returned by this method will be anywhere near the actual price when the system is next entered.

=== <code>setProperty</code> ===
{{oolite-method-added|1.81}}
function '''setProperty'''(layer: Number, key : String, value: String [, manifest: String])

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

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

=== <code>systemsInRange</code> ===
function '''systemsInRange'''([range : Number]) : Array
Returns an array of <code>SystemInfo</code>s in range (default: 7) from the given system.

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

'''Example:'''
system.info.systemsInRange(5);

== Static methods ==
=== <code>filteredSystems</code> ===
function '''filteredSystems'''(this : Object, predicate : Function) : Array of SystemInfo
A list of the <code>SystemInfo</code>s for which <code>predicate</code> returns <code>true</code>.

'''Example:'''
// This is the actual implementation of <code>[[#systemsInRange|systemsInRange()]]</code>.
SystemInfo.prototype.systemsInRange = function systemsInRange(range)
{
if (range === undefined)
{
range = 7;
}

return SystemInfo.filteredSystems(this, function(other)
{
return (other.systemID !== this.systemID) && (this.distanceToSystem(other) <= range);
});
}

=== <code>setInterstellarProperty</code> ===
{{oolite-method-added|1.81}}
function '''setInterstellarProperty'''(galaxy : Number, fromsystem : Number, tosystem : Number, layer: Number, key : String, value: String, [, manifest: String])

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

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

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Condition scripts

2022-11-07T18:17:47Z

Massively Locked: uniform string format

== Condition scripts ==
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).

Conditions scripts may define any or all of the following methods. 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>

In 1.81 the scripts are extended slightly to modify ''how'' things may appear as well as whether they may appear.

=== allowAwardEquipment ===
{{oolite-method-added|1.77}}

In order for this method to be called, the <code>condition_script</code> property of an equipment item (as declared in the [[Equipment.plist]] file) must be specified, it must declare the name of the Javascript file where the method exists, and the method must exist in the referenced JavaScript file. The method will only be called for the equipment items which reference the condition script.

This method is called when the game engine needs to know whether a particular ship can have equipment fitted. In other words, it is asking whether to allow equipment to be awarded to a ship. This may be because the player is looking at possible upgrades at a station (on the F3 Equip Ship screen), 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. You would use this method to control if, and under what conditions, a piece of equipment is offered for purchase and installation. Returning a value of <code>true</code> would indicate that the equipment can be installed; returning a value of <code>false</code> indicates the equipment can't be installed and so it won't appear on the F3 Equip Ship screen, and any of the JavaScript methods to add the equipment item would fail. If the method does not exist, or returns a value other than <code>false</code>, then a value of <code>true</code> is assumed and the equipment may be added or offered for sale (subject to other conditions, of course, like TL constraints)

<code>context</code> will be one of:
* <code>"newShip"</code> - equipment for a ship in a station shipyard (F3 F3)
* <code>"npc"</code> - awarding equipment to NPC on ship setup
* <code>"purchase"</code> - equipment for purchase on the F3 screen
* <code>"scripted"</code> - equipment added by JS or legacy scripts
(Context can in theory also be <code>"loading"</code>, <code>"damage"</code> or <code>"portable"</code>, but if you see one of these, it's a bug)

this.allowAwardEquipment = function(eqKey, ship, context)
{
// your code here
return bool;
}

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:

script_info = {
"oolite-barred-equipment" = ("EQ_WEAPON_MILITARY_LASER");
}

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.

=== allowOfferShip ===
{{oolite-method-added|1.77}}

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.

this.allowOfferShip = function(shipKey)
{
// your code here
return bool;
}

=== allowShowLibraryShip ===
{{oolite-method-added|1.81}}

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 <code>true</code>.

this.allowShowLibraryShip = function(shipKey)
{
// your code here
return bool;
}

=== allowSpawnShip ===
{{oolite-method-added|1.77}}

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.

this.allowSpawnShip = function(shipKey)
{
// your code here
return bool;
}

=== updateEquipmentPrice ===
{{oolite-method-added|1.81}}

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.

this.updateEquipmentPrice = function(equipmentKey, currentPrice)
{
// your code here
return newPrice;
}

This method is called before [[Shipdata.plist#equipment_price_factor|equipment_price_factor]] is considered.

== Links ==
There is an extended bulletin board discussion with a couple of examples [http://www.aegidian.org/bb/viewtopic.php?p=286037#p286037 here] (2022).

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Clock

2022-11-07T17:56:41Z

Massively Locked: /* clockString */ uniform string format

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

The '''clock''' global object is used to tell the time. Apart from <code>[[#absoluteSeconds|absoluteSeconds]]</code>, all its properties have to do with [[Time scales in Oolite#Game clock time|game clock time]].

== Properties ==
=== absoluteSeconds ===
'''absoluteSeconds''' : Number (read-only)
The [[Time scales in Oolite#Game real time|game real time]] clock. Roughly speaking, this is the number of seconds since the game was started, not counting time in which it was paused.

=== seconds ===
'''seconds''' : Number (read-only)
The current time in [[Time scales in Oolite#Game clock time|game clock time]], in seconds since the epoch. If the current clock time is 2084004:17:13:42, <code>seconds</code> will be at least 180058007622 and less than 180058007623.

'''See Also:''' <code>[[#secondsComponent|secondsComponent]]</code>

=== minutes ===
'''minutes''' : Number (read-only)
The current time in [[Time scales in Oolite#Game clock time|game clock time]], in integer minutes since the epoch. If the current clock time is 2084004:17:13:42, <code>minutes</code> will be 3000966793.

'''See Also:''' <code>[[#minutesComponent|minutesComponent]]</code>

=== hours ===
'''hours''' : Number (read-only)
The current time in [[Time scales in Oolite#Game clock time|game clock time]], in integer hours since the epoch. If the current clock time is 2084004:17:13:42, <code>hours</code> will be 50016113.

'''See Also:''' <code>[[#hoursComponent|hoursComponent]]</code>

=== days ===
'''days''' : Number (read-only)
The current time in [[Time scales in Oolite#Game clock time|game clock time]], in integer days since the epoch. If the current clock time is 2084004:17:13:42, <code>days</code> will be 2084004.

=== secondsComponent ===
'''secondsComponent''' : Number (read-only)
The second component of the clock time. If the current clock time is 2084004:17:13:42, <code>secondsComponent</code> will be 42.

'''See Also:''' <code>[[#seconds|seconds]]</code>

=== minutesComponent ===
'''minutesComponent''' : Number (read-only)
The minute component of the clock time. If the current clock time is 2084004:17:13:42, <code>minutesComponent</code> will be 13.

'''See Also:''' <code>[[#minutes|minutes]]</code>

=== hoursComponent ===
'''hoursComponent''' : Number (read-only)
The hour component of the clock time. If the current clock time is 2084004:17:13:42, <code>hoursComponent</code> will be 17.

'''See Also:''' <code>[[#hours|hours]]</code>

=== daysComponent ===
'''daysComponent''' : Number (read-only)
Same as <code>[[#days|days]]</code>, included only for completeness.

=== clockString ===
'''clockString''' : String (read-only)
The clock as displayed in the HUD, including <code>"(adjusting)"</code> if appropriate. If the current clock time is 2084004:17:13:42 and the clock is not being adjusted, <code>clockString</code> will be <code>"2084004:17:13:42"</code>.

=== isAdjusting ===
'''isAdjusting''' : Boolean (read-only)
<code>true</code> if the clock is being adjusted, i.e. running faster than real time, as happens after witchspace jumps.

=== adjustedSeconds ===
{{oolite-prop-added|1.77}}
'''adjustedSeconds''' : Number (read-only)
The adjusted current time. If the clock is not being adjusted, this will be equal to [[#seconds|seconds]]. Otherwise, it will be <code>seconds</code> plus the number of seconds remaining of the adjustment.

=== legacy_scriptTimer ===
'''legacy_scriptTimer''' : Number (read-only)
The current value of the legacy scriptTimer.

== Methods ==
=== addSeconds ===
function '''addSeconds'''(timeInSeconds : Number)
Adds "timeInSeconds" to the current time. Value must be positive and no greater than the equivalent of 30 days (60 * 60 * 24 * 30 = 2592000 seconds)

=== clockStringForTime ===
function '''clockStringForTime'''(timeInSeconds : Number) : String
Returns a display string for a given time, specified in seconds, in the same format as <code>[[#clockString|clockString]]</code>. For instance, to specify that something must be done within a day, you might say:
var message = "This task must be completed by " + clock.clockStringForTime(clock.seconds + 24 * 60 * 60) + ", or all will be lost!"
(Whether such a message should be specified with one-second precision is another matter. More flexible tools for date calculations may be added later.)

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Mission

2022-11-07T17:43:00Z

Massively Locked: uniform string format, added links (x3) & anchor

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

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

== Properties ==

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

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

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

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

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

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

If there is currently a mission screen running with a defined [[#scrnID|<code>screenID</code>]], then that <code>screenID</code>. Otherwise, this is <code>null</code>.

== Methods ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

mission.runScreen(parameters, callback);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Known issues ====

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

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

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

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

Note: the <code>"\n"</code> token does not provide a line break (verified in v1.9).

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

In Oolite 1.81 onwards, the following variant is available

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

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

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

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

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

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

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

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

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

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

In 1.77, each marker has a name, and if a system has multiple markers each marker must be removed separately. Parameters in 1.77 may be numbers or objects. Numbers remove the <code>"__oolite_legacy_destinations"</code> 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 method will return <code>true</code> if all requested markers existed and were removed, or <code>false</code> if any of the requested markers did not exist.

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

[[Category:Oolite JavaScript Reference]]

File:LitF+v0.01.oxz

2022-11-06T20:09:26Z

Massively Locked: dev ver 0.01 (from release ver 0.7.3)

== Summary ==
dev ver 0.01 (from release ver 0.7.3)

Oolite JavaScript Reference: Mission

2022-11-03T23:28:20Z

Massively Locked: /* setInstructions */ uniform string format, deleted redundant link

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

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

== Properties ==

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

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

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

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

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

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

If there is currently a mission screen running with a defined [[#scrnID|<code>screenID</code>]], then that <code>screenID</code>. Otherwise, this is <code>null</code>.

== Methods ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

mission.runScreen(parameters, callback);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Known issues ====

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

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

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

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

Note: the <code>"\n"</code> token does not provide a line break (verified in v1.9).

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

In Oolite 1.81 onwards, the following variant is available

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

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

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

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

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

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

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

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

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

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

In 1.77, each marker has a name, and if a system has multiple markers each marker must be removed separately. Parameters in 1.77 may be numbers or objects. Numbers remove the <code>"__oolite_legacy_destinations"</code> 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 method will return <code>true</code> if all requested markers existed and were removed, or <code>false</code> if any of the requested markers did not exist.

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

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Mission

2022-11-03T23:19:33Z

Massively Locked: /* unmarkSystem */ fixed syntax, uniform string format, added link & deleted redundant link

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

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

== Properties ==

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

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

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

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

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

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

If there is currently a mission screen running with a defined [[#scrnID|<code>screenID</code>]], then that <code>screenID</code>. Otherwise, this is <code>null</code>.

== Methods ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

mission.runScreen(parameters, callback);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Known issues ====

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

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

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

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

Note: the "\n" token does not provide a line break (verified in v1.9).

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

In Oolite 1.81 onwards, the following variant is available

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

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

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

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

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

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

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

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

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

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

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

In 1.77, each marker has a name, and if a system has multiple markers each marker must be removed separately. Parameters in 1.77 may be numbers or objects. Numbers remove the <code>"__oolite_legacy_destinations"</code> 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 method will return <code>true</code> if all requested markers existed and were removed, or <code>false</code> if any of the requested markers did not exist.

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

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Mission

2022-11-03T22:41:58Z

Massively Locked: /* markSystem */ uniform string format (x9), added link

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

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

== Properties ==

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

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

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

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

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

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

If there is currently a mission screen running with a defined [[#scrnID|<code>screenID</code>]], then that <code>screenID</code>. Otherwise, this is <code>null</code>.

== Methods ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

mission.runScreen(parameters, callback);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Known issues ====

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

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

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

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

Note: the "\n" token does not provide a line break (verified in v1.9).

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

In Oolite 1.81 onwards, the following variant is available

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

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

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

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

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

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

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

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

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

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

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

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

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

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Mission

2022-11-03T22:28:00Z

Massively Locked: /* markedSystems */ added links (x2)

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

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

== Properties ==

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

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

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

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

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

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

If there is currently a mission screen running with a defined [[#scrnID|<code>screenID</code>]], then that <code>screenID</code>. Otherwise, this is <code>null</code>.

== Methods ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

mission.runScreen(parameters, callback);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Known issues ====

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

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

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

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

Note: the "\n" token does not provide a line break (verified in v1.9).

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

In Oolite 1.81 onwards, the following variant is available

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

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

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

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

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

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

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

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

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

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

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

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

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

[[Category:Oolite JavaScript Reference]]

File:MoarNews.oxz

2022-11-01T01:30:36Z

Massively Locked: WiP for Cholmondely to eval

== Summary ==
WiP for Cholmondely to eval

Oolite JavaScript Reference: Mission

2022-10-30T18:49:09Z

Massively Locked: added anchor & link

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

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

== Properties ==

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

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

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

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

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

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

If there is currently a mission screen running with a defined [[#scrnID|<code>screenID</code>]], then that <code>screenID</code>. Otherwise, this is <code>null</code>.

== Methods ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

mission.runScreen(parameters, callback);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Known issues ====

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

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

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

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

Note: the "\n" token does not provide a line break (verified in v1.9).

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

In Oolite 1.81 onwards, the following variant is available

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

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

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

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

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

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

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

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

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

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

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

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

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

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: EquipmentInfo

2022-10-30T17:49:38Z

Massively Locked: /* Properties */ uniform string format (x2)

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

'''<code>EquipmentInfo</code>''' objects provide information about a type of equipment. To acquire an <code>EquipmentInfo</code> object, use the <code>[[#infoForKey|infoForKey]]()</code> method, as in:
var missileInfo = EquipmentInfo.infoForKey("EQ_MISSILE");

=== Equipment Expressions ===
Many methods can take either an <code>EquipmentInfo</code> or an equipment key. For instance, <code>ship.hasEquipment("EQ_ECM")</code> is equivalent to <code>ship.hasEquipment(EquipmentInfo.infoForKey("EQ_ECM"))</code>. In specifications, this is represented by arguments typed <code>equipmentInfoExpression</code>.

== Properties ==
=== <code>calculatedPrice</code> ===
{{oolite-prop-added|1.89}}
'''calculatedPrice''' : Number (read-only nonnegative integer)
If an equipment item utilises the <code>[[Oolite JavaScript Reference: Condition scripts#updateEquipmentPrice|updateEquipmentPrice()]]</code> condition script, this will be the price as calculated by that script. If no condition script is in use, the value returned will be the same as the <code>[[#price|price]]</code> property. Divide this by ten for the real value in credits.

=== <code>canBeDamaged</code> ===
'''canBeDamaged''' : Boolean (read-only)
<code>true</code> if the equipment type can be damaged (either in combat or using <code>[[Oolite JavaScript Reference: Ship#setEquipmentStatus|Ship.setEquipmentStatus()]]</code>), <code>false</code> otherwise. Currently, this is hard-coded: trumbles, passenger berths, cargo bays and external stores are invulnerable.

=== <code>canCarryMultiple</code> ===
'''canCarryMultiple''' : Boolean (read-only)
<code>true</code> if multiple instances of the equipment type can be used at once, <code>false</code> otherwise. Currently, this is hard-coded to trumbles, passenger berths and external stores.

=== <code>damageProbability</code> ===
{{oolite-prop-added|1.77}}
'''damageProbability''' : Number (read-only nonnegative)
The relative probability of this item of equipment being damaged, as specified by the <code>damage_probability</code> key in [[equipment.plist]]. This is always zero for mines and missiles, and defaults to one for other equipment. The chance of a particular piece of equipment being damaged is its damageProbability divided by the total damageProbability of all remaining undamaged equipment.

=== <code>description</code> ===
'''description''' : String (read-only)
A short description of the equipment, as seen on the Outfitting (F3) screen.

=== <code>displayColor</code> ===
{{oolite-prop-added|1.85}}
'''displayColor''' : Color (read/write)
Gets and sets the color to be used for this item on the Outfitting (F3) and Status (F5) screens. Any valid [[Materials in Oolite#Colour specifiers|color specifier]] can be used. Setting a value of <code>null</code> will reset the color to use the default.

=== <code>effectiveTechLevel</code> ===
'''effectiveTechLevel''' : Number (read/write nonnegative integer)
The effective tech level required to purchase this item. Unlike <code>[[#techLevel|techLevel]]</code>, this takes the special meaning of 99 and <code>TL_FOR_EQ_WHATEVER</code> mission variables into account. If the raw tech level is 99, changing the value of <code>effectiveTechLevel</code> is equivalent to setting the appropriate <code>TL_FOR_EQ_WHATEVER</code> mission variable. If the raw tech level is not 99, changes to <code>effectiveTechLevel</code> are ignored. 
Setting <code>effectiveTechLevel</code> to <code>null</code>, will remove the corresponding <code>TL_FOR_EQ_WHATEVER</code> mission variable.

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

=== <code>equipmentKey</code> ===
'''equipmentKey''' : String (read-only)
The equipment key for the equipment described by this <code>EquipmentInfo</code> object. For EQ_MISSILE, this is <code>"EQ_MISSILE"</code>.

=== <code>fastAffinityDefensive</code> ===
{{oolite-prop-added|1.79}}
'''fastAffinityDefensive''' : Boolean (read-only)
If this is <code>true</code>, the equipment will be preferentially assigned to the "fast activation (defensive)" key for primable equipment. This is always <code>false</code> for non-primable equipment.

=== <code>fastAffinityOffensive</code> ===
{{oolite-prop-added|1.79}}
'''fastAffinityOffensive''' : Boolean (read-only)
If this is <code>true</code>, the equipment will be preferentially assigned to the "fast activation (offensive)" key for primable equipment. This is always <code>false</code> for non-primable equipment.

=== <code>incompatibleEquipment</code> ===
'''incompatibleEquipment''' : Array (read-only)
An array of equipment keys (in arbitrary order). In order to be installed, no item in this array may already be installed.

'''See also:''' <code>[[#requiresAnyEquipment|requiresAnyEquipment]]</code>, <code>[[#requiresEquipment|requiresEquipment]]</code>

=== <code>isAvailableToAll</code> ===
'''isAvailableToAll''' : Boolean (read-only)
<code>true</code> if the equipment type can be used with any ship, regardless of its shipyard settings. It only has effect on player ships. npc ships always can have it, unless they are explicit excluded with the <code>isAvailableToNPCs</code> key.

=== <code>isAvailableToNPCs</code> ===
'''isAvailableToNPCs''' : Boolean (read-only)
<code>true</code> if the equipment type can be used by non-player ships (<code>available_to_NPCs</code> in [[equipment.plist]], default <code>true</code>).

=== <code>isAvailableToPlayer</code> ===
'''isAvailableToPlayer''' : Boolean (read-only)
<code>true</code> if the equipment type can be used by player ships (<code>available_to_player</code> in [[equipment.plist]], default <code>true</code>).

=== <code>isExternalStore</code> ===
'''isExternalStore''' : Boolean (read-only)
The value of the <code>is_external_store</code> equipment.plist key, if specified; otherwise, <code>true</code> for _MISSILE and _MINE equipment types, and <code>false</code> for others.

=== <code>isPortableBetweenShips</code> ===
'''isPortableBetweenShips''' : Boolean (read-only)
<code>true</code> if equipment of this type is kept when buying a new ship.

=== <code>isVisible</code> ===
'''isVisible''' : Boolean (read-only)
<code>true</code> if the equipment type is visible on the Status (F5) screen (<code>visible</code> in [[equipment.plist]], default: <code>true</code>).

=== <code>name</code> ===
'''name''' : String (read-only)
The display name for the equipment described by this <code>EquipmentInfo</code> object. This string is localized. For EQ_MISSILE in English, this is <code>"Missile"</code>.

=== <code>price</code> ===
'''price''' : Number (read-only nonnegative integer)
This is the value as used in the equipment.plist. Divide this by ten for the real value in credits.

=== <code>provides</code> ===
{{oolite-prop-added|1.81}}
'''provides''' : Array (read-only)
Returns an array of equipment keys which define the function(s) this equipment is providing to the ship, as defined in the <code>provides</code> element in [[equipment.plist]].

=== <code>requiredCargoSpace</code> ===
'''requiredCargoSpace''' : Number (read-only nonnegative integer)
Until Oolite 1.76, this was only used to decide '''if''' an item could be displayed on the Outfitting (F3) screen. Starting with 1.77, this key will actually ensure that the equipment uses cargo space when installed.

=== <code>requiresAnyEquipment</code> ===
'''requiresAnyEquipment''' : Array (read-only)
An array of equipment keys (in arbitrary order). In order to be installed, ''at least one'' item in this array must already be installed.

'''See also:''' <code>[[#incompatibleEquipment|incompatibleEquipment]]</code>, <code>[[#requiresEquipment|requiresEquipment]]</code>

=== <code>requiresCleanLegalRecord</code> ===
'''requiresCleanLegalRecord''' : Boolean (read-only)

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

=== <code>requiresEmptyPylon</code> ===
'''requiresEmptyPylon''' : Boolean (read-only)
<code>true</code> for equipment that requires at least one pylon to have nothing on it.

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

=== <code>requiresEquipment</code> ===
'''requiresEquipment''' : Array (read-only)
An array of equipment keys (in arbitrary order). In order to be installed, ''all'' items in this array must already be installed.

'''See also:''' <code>[[#incompatibleEquipment|incompatibleEquipment]]</code>, <code>[[#requiresAnyEquipment|requiresAnyEquipment]]</code>

=== <code>requiresFreePassengerBerth</code> ===
'''requiresFreePassengerBerth''' : Boolean (read-only)

=== <code>requiresFullFuel</code> ===
'''requiresFullFuel''' : Boolean (read-only)

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

=== <code>requiresMountedPylon</code> ===
'''requiresMountedPylon''' : Boolean (read-only)
<code>true</code> for equipment that requires at least one pylon to have a store (missile, mine or equipment) on it.

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

=== <code>requiresNonCleanLegalRecord</code> ===
'''requiresNonCleanLegalRecord''' : Boolean (read-only)

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

=== <code>requiresNonFullFuel</code> ===
'''requiresNonFullFuel''' : Boolean (read-only)

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

=== <code>scriptInfo</code> ===
'''scriptInfo''' : Object (read-only)
The contents of the <code>script_info</code> key in the equipments’s ''[[equipment.plist]]'' entry, if any. This may be any [[property list]] object, but the reccomended 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.

=== <code>scriptName</code> ===
'''scriptName''' : String (read-only)
The name of an attached script.

=== <code>techLevel</code> ===
'''techLevel''' : Number (read-only nonnegative integer)
The raw tech level required to purchase this item. Unlike <code>[[#effectiveTechLevel|effectiveTechLevel]]</code>, this does not take the special meaning of 99 and <code>TL_FOR_EQ_WHATEVER</code> mission variables into account.

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

== Static properties ==
=== <code>allEquipment</code> ===
allEquipment : Array (EquipmentInfos, read-only)
Returns a list of all known equipment types.

== Static methods ==
=== <code>infoForKey</code> ===
function '''infoForKey'''(equipmentKey : String) : EquipmentInfo
Returns the equipment info object for a given type of equipment, or <code>null</code> for an unrecognised key. Example: <code>var missileInfo = EquipmentInfo.infoForKey("EQ_MISSILE");</code>

[[Category:Oolite JavaScript Reference]]

==See also==
* [[Equipment.plist]]

Oolite JavaScript Reference: Player

2022-10-30T17:24:32Z

Massively Locked: /* rank */ cleared up wording

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

The '''<code>Player</code>''' class is represents the player. There is always exactly one <code>Player</code> object in existence, which can be accessed through the <code>player</code> global property.

== Properties ==
=== <code>alertAltitude</code> ===
'''alertAltitude''' : Boolean (read-only)
Whether the player is dangerously close to a planet. (closer than 4000 meter to the surface)

=== <code>alertCondition</code> ===
'''alertCondition''' : Number (read-only, integer)
Returns the current alert condition. 0 = Docked, 1 = Green, 2 = Yellow, 3 = Red.

=== <code>alertEnergy</code> ===
'''alertEnergy''' : Boolean (read-only)
Whether the player’s energy level is depleted (i.e., <code>[[Oolite JavaScript Reference: Entity#energy|energy]]</code> is less than <code>[[Oolite JavaScript Reference: Entity#maxEnergy|maxEnergy]]</code>).

=== <code>alertHostiles</code> ===
'''alertHostiles''' : Boolean (read-only)
Whether there are hostile ships within scanner range.

=== <code>alertMassLocked</code> ===
'''alertMassLocked''' : Boolean (read-only)
Whether the player is mass locked.

=== <code>alertTemperature</code> ===
'''alertTemperature''' : Boolean (read-only)
Whether the cabin temperature is dangerously high.

=== <code>bounty</code> ===
'''bounty''' : Number (read/write integer)
The bounty on the player, which determines legal status. It is halved at each witchspace jump.

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

=== <code>contractReputation</code> ===
'''contractReputation''' : Number (read-only integer)
{{oolite-prop-added|1.79}}
'''contractReputationPrecise''' : Number (read-only decimal)
The player’s cargo contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards..

'''See also:''' <code>[[#decreaseContractReputation|decreaseContractReputation()]]</code>, <code>[[#increaseContractReputation|increaseContractReputation()]]</code>, <code>[[Oolite JavaScript Reference: Ship#contracts|contracts]]</code>, <code>[[#parcelReputation|parcelReputation]]</code>, <code>[[#passengerReputation|passengerReputation]]</code>

=== <code>credits</code> ===
'''credits''' : Number (read/write, float)
The amount of money the player has, in credits.

=== <code>dockingClearanceStatus</code> ===
'''dockingClearanceStatus''' : String (read-only)
A string indicating whether the player has docking clearance. (''Clarify: for which station? -[[User:Ahruman|Ahruman]] 20:34, 3 November 2008 (UTC)'') Possible values are:
* <code>"DOCKING_CLEARANCE_STATUS_NONE"</code>
* <code>"DOCKING_CLEARANCE_STATUS_REQUESTED"</code>
* <code>"DOCKING_CLEARANCE_STATUS_NOT_REQUIRED"</code>
* <code>"DOCKING_CLEARANCE_STATUS_GRANTED"</code>
* <code>"DOCKING_CLEARANCE_STATUS_TIMING_OUT"</code>

=== <code>escapePodRescueTime</code> ===
{{oolite-prop-added|1.89}}
'''escapePodRescueTime''' : Number (read-write decimal)
Number of seconds that will be added to the clock when the player uses an escape pod and is rescued. Default value is 0 (zero), which will utilise the default time calculation that can add up to eight days to the clock.
Negative numbers will be ignored (and default calculation will apply).

=== <code>legalStatus</code> ===
'''legalStatus''' : String (read-only)
A string mainly for display purposes describing the player’s legal status based on <code>[[#bounty|bounty]]</code>. In English, this is one of <code>"Clean"</code> (bounty = 0), <code>"Offender"</code> (0 < bounty ≤ 50) or <code>"Fugitive"</code>, but note that it can be localized.

=== <code>name</code> ===
'''name''' : String (read-only, read/write from 1.79)
The name of the player’s character (e.g., <code>"Jameson"</code>). Prior to 1.79, this was also used as the filename for the savegame and so was not writable.

=== <code>parcelReputation</code> ===
{{oolite-prop-added|1.77}}
'''parcelReputation''' : Number (read-only integer)
{{oolite-prop-added|1.79}}
'''parcelReputationPrecise''' : Number (read-only decimal)
The player’s parcel contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards.

'''See also:''' <code>[[#decreaseParcelReputation|decreaseParcelReputation()]]</code>, <code>[[#increaseParcelReputation|increaseParcelReputation()]]</code>, <code>[[Oolite JavaScript Reference: Ship#parcels|parcels]]</code>, <code>[[#contractReputation|contractReputation]]</code>, <code>[[#passengerReputation|passengerReputation]]</code>

=== <code>passengerReputation</code> ===
'''passengerReputation''' : Number (read-only integer)
{{oolite-prop-added|1.79}}
'''passengerReputationPrecise''' : Number (read-only decimal)
The player’s passenger contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards.

'''See also:''' <code>[[#decreasePassengerReputation|decreasePassengerReputation()]]</code>, <code>[[#increasePassengerReputation|increasePassengerReputation()]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengers|passengers]]</code>, <code>[[#contractReputation|contractReputation]]</code>, <code>[[#parcelReputation|parcelReputation]]</code>

=== <code>rank</code> ===
'''rank''' : String (read-only)
A string mainly for display purposes describing the player’s rank (such as <code>"Mostly Harmless"</code> or <code>"Dangerous"</code>) based on <code>[[#score|score]]</code>. Note that it can be localized.

=== <code>roleWeights</code> ===
{{oolite-prop-added|1.79}}
'''roleWeights''' : Array (read-only)
An array of the player's current role as perceived by the game. Generally NPCs will pick a random entry from this list and treat the player as if they were an NPC of that role. The '<code>player-unknown</code>' role is the default role. The size of the list depends on the player's current Elite ranking.

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

=== <code>score</code> ===
'''score''' : Number (read/write, integer)
The player’s score; nominally the number of kills the player has made, although some missions award additional points.

=== <code>ship</code> ===
'''ship''' : [[Oolite_JavaScript_Reference:_Ship | Ship]]
The player’s ship

=== <code>trumbleCount</code> ===
'''trumbleCount''' : Number (read-only nonnegative integer)
The number of trumbles the player is currently blessed with.

== Methods ==
=== <code>addMessageToArrivalReport</code> ===
function '''addMessageToArrivalReport'''(message : String)
Adds a message to the arrival report shown immediately after docking. Oolite puts its own stuff on the list immediately after [[Oolite JavaScript Reference: World script event handlers#shipWillDockWithStation|shipWillDockWithStation]] so this is a good moment to add the messages when you know what station will be docked. [[Oolite JavaScript Reference: World script event handlers#shipDockedWithStation|shipDockedWithStation]] may also be used. Messages added while in flight or during shipWillDockWithStation will be above Oolite's own arrival messages. Those added during shipDockedWithStation will be below Oolite's own arrival messages.

'''See also''': <code>[[Oolite JavaScript Reference: Station#suppressArrivalReports|station.suppressArrivalReports]]</code>

=== <code>commsMessage</code> ===
function '''commsMessage'''(message : String [, duration: Number])
Writes the specified message in the player’s communications log, as well as displaying it as a console message. The optional <code>duration</code> parameter determines how long the message should be displayed on the console before fading out. It is clamped to the range [1, 10]. If no duration is specified, 4.5 seconds will be used.

'''Example:'''
player.commsMessage("Hello, cruel universe.", 6)
NB, this <code>commsMessage()</code> is a method of the <code>player</code> object. <code>player.ship</code> can also have a <code>[[Oolite_JavaScript_Reference:_Ship#commsMessage|commsMessage()]]</code> method, but that belongs to the ship and has a different second parameter.
*[http://aegidian.org/bb/viewtopic.php?f=4&t=10880 Formatting text msgs on a HUD] (2011)

=== <code>consoleMessage</code> ===
function '''consoleMessage'''(message : String [, duration: Number])
Displays the specified message as a console message, that is, as a message on the HUD. The optional <code>duration</code> parameter determines how long the message should be displayed before fading out. It is clamped to the range [1, 10]. If no duration is specified, 3 seconds will be used.

'''See also''': [http://aegidian.org/bb/viewtopic.php?f=4&t=10880 Formatting text msgs on a HUD] (2011)

=== <code>decreaseContractReputation</code> ===
function '''decreaseContractReputation'''()
Give the player a negative reputation point for cargo contracts. Decreases the underlying value for contractReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.

'''See also:''' <code>[[#contractReputation|contractReputation]]</code>, <code>[[#increaseContractReputation|increaseContractReputation()]]</code>

=== <code>decreaseParcelReputation</code> ===
{{oolite-method-added|1.77}}
function '''decreaseParcelReputation'''()
Give the player a negative reputation point for parcel contracts. Decreases the underlying value for parcelReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.

'''See also:''' <code>[[#parcelReputation|parcelReputation]]</code>, <code>[[#increaseParcelReputation|increaseParcelReputation()]]</code>

=== <code>decreasePassengerReputation</code> ===
function '''decreasePassengerReputation'''()
Give the player a negative reputation point for passenger contracts. Decreases the underlying value for passengerReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.

'''See also:''' <code>[[#passengerReputation|passengerReputation]]</code>, <code>[[#increasePassengerReputation|increasePassengerReputation()]]</code>

=== <code>endScenario</code> ===
{{oolite-method-added|1.79}}
function '''endScenario'''(key : String) : Boolean
End the current game immediately and return to the start game screen. Returns <code>true</code> if it succeeds (though this will shortly be irrelevant) or <code>false</code> if it fails, which it will do if the key passed in is not the same as the [[scenarios.plist#scenario|scenario key]] in the current game scenario. If the current game scenario has no scenario key, this method will always fail.

There is no way to find out what, if any, the current scenario key is. If you are calling this method, you should be doing so in a context where you already know what it is.

=== <code>increaseContractReputation</code> ===
function '''increaseContractReputation'''()
Give the player a positive reputation point for cargo contracts. Increases the underlying value for contractReputation by 1 until a maximum of 7

'''See also:''' <code>[[#contractReputation|contractReputation]]</code>, <code>[[#decreaseContractReputation|decreaseContractReputation()]]</code>

=== <code>increaseParcelReputation</code> ===
{{oolite-method-added|1.77}}
function '''increaseParcelReputation'''()
Give the player a positive reputation point for parcel contracts. Increases the underlying value for parcelReputation by 1 until a maximum of 7

'''See also:''' <code>[[#parcelReputation|parcelReputation]]</code>, <code>[[#decreaseParcelReputation|decreaseParcelReputation()]]</code>

=== <code>increasePassengerReputation</code> ===
function '''increasePassengerReputation'''()
Give the player a positive reputation point for passenger contracts. Increases the underlying value for passengerReputation by 1 until a maximum of 7

'''See also:''' <code>[[#passengerReputation|passengerReputation]]</code>, <code>[[#decreasePassengerReputation|decreasePassengerReputation()]]</code>

=== <code>setEscapePodDestination</code> ===
function '''setEscapePodDestination'''(destination)
This method can only be called after the player has launched an escape pod – mainly from the [[Oolite_JavaScript_Reference:_World_script_event_handlers#escapePodSequenceOver|<code>escapePodSequenceOver</code>]] event handler. It determines where the player will end up. The <code>destination</code> parameter may be any station/carrier, the string <code>"NEARBY_SYSTEM"</code> or <code>null</code>. If it is <code>"NEARBY_SYSTEM"</code>, the player will end up at the main station in a random nearby system. If it is <code>null</code> (which is the default in interstellar space), the player will die of life support failure.

=== <code>setPlayerRole</code> ===
{{oolite-method-added|1.79}}
function '''setPlayerRole'''(role [,index])
Sets one of the player's perceived role entries to the specified role. If index is not specified, a random entry will be chosen.

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

=== <code>replaceShip</code> ===
{{Oolite-method-added|1.77}}
function '''replaceShip'''(dataKey [, personality])
This method can only be called while the player is docked at a station. It discards the player's current ship (including all cargo, passenger contracts, and equipment), and replaces it with the ship defined by the shipyard.plist entry <code>dataKey</code> (obviously the key must also be defined in shipyard.plist as a valid player ship). The new ship will have all standard equipment for a ship of that type, and any equipment from the previous ship which was [[Oolite JavaScript Reference: EquipmentInfo#isPortableBetweenShips|isPortableBetweenShips]]. While this may not necessarily be a ship purchase, the [[Oolite JavaScript Reference: World script event handlers#playerBoughtNewShip|playerBoughtNewShip]] will fire to notify other scripts of the change, although this event is being deprecated in favour of [[Oolite JavaScript Reference: World script event handlers#playerReplacedShip|playerReplacedShip]], which was added in Oolite Test Release 1.89.

If the dataKey was not defined in both shipdata.plist and shipyard.plist, or the player is in flight, this method does nothing.

<code>personality</code> is optional, and can be between 0 and 32767. The new ship is given that specific [[Oolite_JavaScript_Reference:_Ship#entityPersonality|entityPersonality]], which for some ships may affect its appearance with shaders.

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Player

2022-10-30T17:24:27Z

Massively Locked: /* legalStatus */ cleared up wording

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

The '''<code>Player</code>''' class is represents the player. There is always exactly one <code>Player</code> object in existence, which can be accessed through the <code>player</code> global property.

== Properties ==
=== <code>alertAltitude</code> ===
'''alertAltitude''' : Boolean (read-only)
Whether the player is dangerously close to a planet. (closer than 4000 meter to the surface)

=== <code>alertCondition</code> ===
'''alertCondition''' : Number (read-only, integer)
Returns the current alert condition. 0 = Docked, 1 = Green, 2 = Yellow, 3 = Red.

=== <code>alertEnergy</code> ===
'''alertEnergy''' : Boolean (read-only)
Whether the player’s energy level is depleted (i.e., <code>[[Oolite JavaScript Reference: Entity#energy|energy]]</code> is less than <code>[[Oolite JavaScript Reference: Entity#maxEnergy|maxEnergy]]</code>).

=== <code>alertHostiles</code> ===
'''alertHostiles''' : Boolean (read-only)
Whether there are hostile ships within scanner range.

=== <code>alertMassLocked</code> ===
'''alertMassLocked''' : Boolean (read-only)
Whether the player is mass locked.

=== <code>alertTemperature</code> ===
'''alertTemperature''' : Boolean (read-only)
Whether the cabin temperature is dangerously high.

=== <code>bounty</code> ===
'''bounty''' : Number (read/write integer)
The bounty on the player, which determines legal status. It is halved at each witchspace jump.

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

=== <code>contractReputation</code> ===
'''contractReputation''' : Number (read-only integer)
{{oolite-prop-added|1.79}}
'''contractReputationPrecise''' : Number (read-only decimal)
The player’s cargo contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards..

'''See also:''' <code>[[#decreaseContractReputation|decreaseContractReputation()]]</code>, <code>[[#increaseContractReputation|increaseContractReputation()]]</code>, <code>[[Oolite JavaScript Reference: Ship#contracts|contracts]]</code>, <code>[[#parcelReputation|parcelReputation]]</code>, <code>[[#passengerReputation|passengerReputation]]</code>

=== <code>credits</code> ===
'''credits''' : Number (read/write, float)
The amount of money the player has, in credits.

=== <code>dockingClearanceStatus</code> ===
'''dockingClearanceStatus''' : String (read-only)
A string indicating whether the player has docking clearance. (''Clarify: for which station? -[[User:Ahruman|Ahruman]] 20:34, 3 November 2008 (UTC)'') Possible values are:
* <code>"DOCKING_CLEARANCE_STATUS_NONE"</code>
* <code>"DOCKING_CLEARANCE_STATUS_REQUESTED"</code>
* <code>"DOCKING_CLEARANCE_STATUS_NOT_REQUIRED"</code>
* <code>"DOCKING_CLEARANCE_STATUS_GRANTED"</code>
* <code>"DOCKING_CLEARANCE_STATUS_TIMING_OUT"</code>

=== <code>escapePodRescueTime</code> ===
{{oolite-prop-added|1.89}}
'''escapePodRescueTime''' : Number (read-write decimal)
Number of seconds that will be added to the clock when the player uses an escape pod and is rescued. Default value is 0 (zero), which will utilise the default time calculation that can add up to eight days to the clock.
Negative numbers will be ignored (and default calculation will apply).

=== <code>legalStatus</code> ===
'''legalStatus''' : String (read-only)
A string mainly for display purposes describing the player’s legal status based on <code>[[#bounty|bounty]]</code>. In English, this is one of <code>"Clean"</code> (bounty = 0), <code>"Offender"</code> (0 < bounty ≤ 50) or <code>"Fugitive"</code>, but note that it can be localized.

=== <code>name</code> ===
'''name''' : String (read-only, read/write from 1.79)
The name of the player’s character (e.g., <code>"Jameson"</code>). Prior to 1.79, this was also used as the filename for the savegame and so was not writable.

=== <code>parcelReputation</code> ===
{{oolite-prop-added|1.77}}
'''parcelReputation''' : Number (read-only integer)
{{oolite-prop-added|1.79}}
'''parcelReputationPrecise''' : Number (read-only decimal)
The player’s parcel contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards.

'''See also:''' <code>[[#decreaseParcelReputation|decreaseParcelReputation()]]</code>, <code>[[#increaseParcelReputation|increaseParcelReputation()]]</code>, <code>[[Oolite JavaScript Reference: Ship#parcels|parcels]]</code>, <code>[[#contractReputation|contractReputation]]</code>, <code>[[#passengerReputation|passengerReputation]]</code>

=== <code>passengerReputation</code> ===
'''passengerReputation''' : Number (read-only integer)
{{oolite-prop-added|1.79}}
'''passengerReputationPrecise''' : Number (read-only decimal)
The player’s passenger contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards.

'''See also:''' <code>[[#decreasePassengerReputation|decreasePassengerReputation()]]</code>, <code>[[#increasePassengerReputation|increasePassengerReputation()]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengers|passengers]]</code>, <code>[[#contractReputation|contractReputation]]</code>, <code>[[#parcelReputation|parcelReputation]]</code>

=== <code>rank</code> ===
'''rank''' : String (read-only)
A string describing the player’s rank for display purposes, based on <code>[[#score|score]]</code>, such as <code>"Mostly Harmless"</code> or <code>"Dangerous"</code>. Note that it can be localized.

=== <code>roleWeights</code> ===
{{oolite-prop-added|1.79}}
'''roleWeights''' : Array (read-only)
An array of the player's current role as perceived by the game. Generally NPCs will pick a random entry from this list and treat the player as if they were an NPC of that role. The '<code>player-unknown</code>' role is the default role. The size of the list depends on the player's current Elite ranking.

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

=== <code>score</code> ===
'''score''' : Number (read/write, integer)
The player’s score; nominally the number of kills the player has made, although some missions award additional points.

=== <code>ship</code> ===
'''ship''' : [[Oolite_JavaScript_Reference:_Ship | Ship]]
The player’s ship

=== <code>trumbleCount</code> ===
'''trumbleCount''' : Number (read-only nonnegative integer)
The number of trumbles the player is currently blessed with.

== Methods ==
=== <code>addMessageToArrivalReport</code> ===
function '''addMessageToArrivalReport'''(message : String)
Adds a message to the arrival report shown immediately after docking. Oolite puts its own stuff on the list immediately after [[Oolite JavaScript Reference: World script event handlers#shipWillDockWithStation|shipWillDockWithStation]] so this is a good moment to add the messages when you know what station will be docked. [[Oolite JavaScript Reference: World script event handlers#shipDockedWithStation|shipDockedWithStation]] may also be used. Messages added while in flight or during shipWillDockWithStation will be above Oolite's own arrival messages. Those added during shipDockedWithStation will be below Oolite's own arrival messages.

'''See also''': <code>[[Oolite JavaScript Reference: Station#suppressArrivalReports|station.suppressArrivalReports]]</code>

=== <code>commsMessage</code> ===
function '''commsMessage'''(message : String [, duration: Number])
Writes the specified message in the player’s communications log, as well as displaying it as a console message. The optional <code>duration</code> parameter determines how long the message should be displayed on the console before fading out. It is clamped to the range [1, 10]. If no duration is specified, 4.5 seconds will be used.

'''Example:'''
player.commsMessage("Hello, cruel universe.", 6)
NB, this <code>commsMessage()</code> is a method of the <code>player</code> object. <code>player.ship</code> can also have a <code>[[Oolite_JavaScript_Reference:_Ship#commsMessage|commsMessage()]]</code> method, but that belongs to the ship and has a different second parameter.
*[http://aegidian.org/bb/viewtopic.php?f=4&t=10880 Formatting text msgs on a HUD] (2011)

=== <code>consoleMessage</code> ===
function '''consoleMessage'''(message : String [, duration: Number])
Displays the specified message as a console message, that is, as a message on the HUD. The optional <code>duration</code> parameter determines how long the message should be displayed before fading out. It is clamped to the range [1, 10]. If no duration is specified, 3 seconds will be used.

'''See also''': [http://aegidian.org/bb/viewtopic.php?f=4&t=10880 Formatting text msgs on a HUD] (2011)

=== <code>decreaseContractReputation</code> ===
function '''decreaseContractReputation'''()
Give the player a negative reputation point for cargo contracts. Decreases the underlying value for contractReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.

'''See also:''' <code>[[#contractReputation|contractReputation]]</code>, <code>[[#increaseContractReputation|increaseContractReputation()]]</code>

=== <code>decreaseParcelReputation</code> ===
{{oolite-method-added|1.77}}
function '''decreaseParcelReputation'''()
Give the player a negative reputation point for parcel contracts. Decreases the underlying value for parcelReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.

'''See also:''' <code>[[#parcelReputation|parcelReputation]]</code>, <code>[[#increaseParcelReputation|increaseParcelReputation()]]</code>

=== <code>decreasePassengerReputation</code> ===
function '''decreasePassengerReputation'''()
Give the player a negative reputation point for passenger contracts. Decreases the underlying value for passengerReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.

'''See also:''' <code>[[#passengerReputation|passengerReputation]]</code>, <code>[[#increasePassengerReputation|increasePassengerReputation()]]</code>

=== <code>endScenario</code> ===
{{oolite-method-added|1.79}}
function '''endScenario'''(key : String) : Boolean
End the current game immediately and return to the start game screen. Returns <code>true</code> if it succeeds (though this will shortly be irrelevant) or <code>false</code> if it fails, which it will do if the key passed in is not the same as the [[scenarios.plist#scenario|scenario key]] in the current game scenario. If the current game scenario has no scenario key, this method will always fail.

There is no way to find out what, if any, the current scenario key is. If you are calling this method, you should be doing so in a context where you already know what it is.

=== <code>increaseContractReputation</code> ===
function '''increaseContractReputation'''()
Give the player a positive reputation point for cargo contracts. Increases the underlying value for contractReputation by 1 until a maximum of 7

'''See also:''' <code>[[#contractReputation|contractReputation]]</code>, <code>[[#decreaseContractReputation|decreaseContractReputation()]]</code>

=== <code>increaseParcelReputation</code> ===
{{oolite-method-added|1.77}}
function '''increaseParcelReputation'''()
Give the player a positive reputation point for parcel contracts. Increases the underlying value for parcelReputation by 1 until a maximum of 7

'''See also:''' <code>[[#parcelReputation|parcelReputation]]</code>, <code>[[#decreaseParcelReputation|decreaseParcelReputation()]]</code>

=== <code>increasePassengerReputation</code> ===
function '''increasePassengerReputation'''()
Give the player a positive reputation point for passenger contracts. Increases the underlying value for passengerReputation by 1 until a maximum of 7

'''See also:''' <code>[[#passengerReputation|passengerReputation]]</code>, <code>[[#decreasePassengerReputation|decreasePassengerReputation()]]</code>

=== <code>setEscapePodDestination</code> ===
function '''setEscapePodDestination'''(destination)
This method can only be called after the player has launched an escape pod – mainly from the [[Oolite_JavaScript_Reference:_World_script_event_handlers#escapePodSequenceOver|<code>escapePodSequenceOver</code>]] event handler. It determines where the player will end up. The <code>destination</code> parameter may be any station/carrier, the string <code>"NEARBY_SYSTEM"</code> or <code>null</code>. If it is <code>"NEARBY_SYSTEM"</code>, the player will end up at the main station in a random nearby system. If it is <code>null</code> (which is the default in interstellar space), the player will die of life support failure.

=== <code>setPlayerRole</code> ===
{{oolite-method-added|1.79}}
function '''setPlayerRole'''(role [,index])
Sets one of the player's perceived role entries to the specified role. If index is not specified, a random entry will be chosen.

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

=== <code>replaceShip</code> ===
{{Oolite-method-added|1.77}}
function '''replaceShip'''(dataKey [, personality])
This method can only be called while the player is docked at a station. It discards the player's current ship (including all cargo, passenger contracts, and equipment), and replaces it with the ship defined by the shipyard.plist entry <code>dataKey</code> (obviously the key must also be defined in shipyard.plist as a valid player ship). The new ship will have all standard equipment for a ship of that type, and any equipment from the previous ship which was [[Oolite JavaScript Reference: EquipmentInfo#isPortableBetweenShips|isPortableBetweenShips]]. While this may not necessarily be a ship purchase, the [[Oolite JavaScript Reference: World script event handlers#playerBoughtNewShip|playerBoughtNewShip]] will fire to notify other scripts of the change, although this event is being deprecated in favour of [[Oolite JavaScript Reference: World script event handlers#playerReplacedShip|playerReplacedShip]], which was added in Oolite Test Release 1.89.

If the dataKey was not defined in both shipdata.plist and shipyard.plist, or the player is in flight, this method does nothing.

<code>personality</code> is optional, and can be between 0 and 32767. The new ship is given that specific [[Oolite_JavaScript_Reference:_Ship#entityPersonality|entityPersonality]], which for some ships may affect its appearance with shaders.

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Global

2022-10-30T17:03:41Z

Massively Locked: /* Methods */ uniform string format (x7), fixed param name (x2)

Global variables and functions are visible to all scripts. They are also properties of <code>[[#global|global]]</code>, which is itself a global variable and hence a property of itself.

== Properties ==
=== <code>clock</code> ===
'''clock''' : {{oojsclass|Clock}} (read-only)
This property allows an OXP to access the game clock's properties and methods.

=== <code>defaultFont</code> ===
'''defaultFont''' : Object (read-only)
An object with a single method, <code>measureString(string)</code>, which returns the width of the specified string, as it would be shown on the screen, in '''ems'''. One em is the intrinsic unit size of a font; for example, if a font is rendered at 12 points, 1 em = 12 pt. The mission screen text area is 32 em wide.

=== <code>galaxyNumber</code> ===
'''galaxyNumber''' : Number (read-only)
Returns the number of the galaxy the player is in.

=== <code>global</code> ===
'''global''' : Global (read-only)
All global variables and functions are actually properties of the global object. The global object is a property of itself, and this is it.

=== <code>guiScreen</code> ===
'''guiScreen''' : String (read-only)
Returns the screen the player is looking at. If in flight, this is <code>"GUI_SCREEN_MAIN"</code>. In 1.76, the other possible values are <code>"GUI_SCREEN_INTRO1"</code>, <code>"GUI_SCREEN_INTRO2"</code>, <code>"GUI_SCREEN_STATUS"</code>(F5), <code>"GUI_SCREEN_MANIFEST"</code>(F5F5), <code>"GUI_SCREEN_EQUIP_SHIP"</code>(F3), <code>"GUI_SCREEN_SHIPYARD"</code>(F3F3), <code>"GUI_SCREEN_LONG_RANGE_CHART"</code>(F6F6), <code>"GUI_SCREEN_SHORT_RANGE_CHART"</code>(F6), <code>"GUI_SCREEN_SYSTEM_DATA"</code>(F7), <code>"GUI_SCREEN_MARKET"</code>(F8), <code>"GUI_SCREEN_CONTRACTS"</code>, <code>"GUI_SCREEN_OPTIONS"</code>, <code>"GUI_SCREEN_GAMEOPTIONS"</code>, <code>"GUI_SCREEN_LOAD"</code>, <code>"GUI_SCREEN_SAVE"</code>, <code>"GUI_SCREEN_SAVE_OVERWRITE"</code>, <code>"GUI_SCREEN_STICKMAPPER"</code>, <code>"GUI_SCREEN_MISSION"</code> and <code>"GUI_SCREEN_REPORT"</code>.

In 1.77, <code>"GUI_SCREEN_INTERFACES"</code>(F4) is added, and <code>"GUI_SCREEN_CONTRACTS"</code> is removed.

In 1.81, <code>"GUI_SCREEN_MARKETINFO"</code>(F8F8) is added.

=== <code>manifest</code> ===
'''manifest''' : {{oojsclass|Manifest}} (read-only)
An alias to <code>[[Oolite JavaScript Reference: PlayerShip#manifest|player.ship.manifest]]</code>.

=== <code>mission</code> ===
'''mission''' : {{oojsclass|Mission}} (read-only)
See [[Oolite JavaScript Reference: Mission]].

=== <code>missionVariables</code> ===
'''missionVariables''' : Object (read-only)
The <code>missionVariables</code> object stores values that are stored in saved games. This is the main way for scripts to store information permanently.

Whenever a value is assigned to a property of <code>missionVariables</code>, it is converted to a string object and tracked with the player. When the value is read, it will be converted to a number if possible, otherwise returned as a string. Example:
missionVariables.exampleVar = 42;
let x = missionVariables.exampleVar; // x is now the number 42
Do not use <code>false</code> in missionVariables! It will return <code>true</code> because it will be parsed as a string. Use 0 or 1 to store boolean values.

You can store arrays using [http://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON JSON] stringify and parse methods. For example:
this.$MyArray = [];

this.startUp = function() {
var s = missionVariables.$MyArray;
if( s && s.length > 0 ) this.$MyArray = JSON.parse(s);
}

this.playerWillSaveGame = function(message) {
missionVariables.$MyArray = JSON.stringify(this.$MyArray);
}
Mission variables can also be used in legacy scripts and in [[descriptions.plist]] string expansions, by prefixing the name with <code>"mission_"</code>. Example:
expandDescription("My variable is [mission_exampleVar].")
Setting and retrieving mission variables has a significant overhead'''*'''. If a function needs to use a mission variable value several times, it is strongly recommended that it be copied into a local variable and, if necessary, stored back once. Example:
let x = missionVariables.exampleVar;
if (x < 3) x = processSmallValue(x);
else x = processBigValue(x);
missionVariables.exampleVar = x;
Mission variable names may not begin with an underscore (“_”). Unassigned mission variables are always <code>null</code>.

'''*''' On a computer where the loop <code>for (var i = 0; i < 1000; i++) {}</code> takes just 0.62 msec, the same loop with missionVarriables <code>for (missionVariables.i = 0; missionVariables.i < 1000; missionVariables.i++) {}</code> consumes a full 38 msec. That is 60 times longer.

=== <code>oolite</code> ===
'''oolite''' : {{oojsclass|Oolite}} (read-only)
An object describing properties of the Oolite application; see [[Oolite JavaScript Reference: Oolite]].

=== <code>player</code> ===
'''player''' : {{oojsclass|Player}} (read-only)
This property allows an OXP to access the player object's properties and methods.

=== <code>system</code> ===
'''system''' : {{oojsclass|System}} (read-only)
This property allows an OXP to access the current system's properties and methods.

=== <code>timeAccelerationFactor</code> ===
'''timeAccelerationFactor''' : Number (read/write)
Also known as TAF. Will change the ratio between game real time and actual real time (default is 1). The accepted range is between 0.0625 (1/16) and 16. Attempting to set numbers outside this range will reset the TAF to 1. (In end-user stable builds, this will be a read-only property with the value 1.)

=== <code>worldScriptNames</code> ===
'''worldScriptNames''' : Array of strings (read-only)
A list of the names of world script objects, the keys of <code>[[#worldScripts|worldScripts]]</code>.

=== <code>worldScripts</code> ===
'''worldScripts''' : Object (read-only)
All loaded world script objects. The keys are the <code>name</code> properties of the scripts.

'''Example:'''
log(worldScripts["oolite-nova"].version);

== Methods ==
=== <code>addFrameCallback</code> ===
function '''addFrameCallback'''(callback : Function) : ''TrackingID''
Registers a ''frame callback'' which will be invoked every frame, after entity updates but before rendering. This can be used to implement animations, to apply gradual changes in ship state, to build large data structures without risking reaching processing time limits by trying to do it all at once, or to watch variables which need a same-frame response to changes. The return value is a ''tracking ID'' which may be passed to <code>[[#removeFrameCallback|removeFrameCallback()]]</code>; the type and meaning of the tracking ID is unspecified and may change at any time. Frame callbacks are automatically removed when the game resets (for instance, when the player dies), but not at any other time.

The callback is passed one parameter, <code>delta</code>, which is the time since the last frame (in [[Time_scales in Oolite|game clock time]]). Frame callbacks fire even when the game is paused, in which case <code>delta</code> is 0.

'''Example:'''
var sum = 0;
this.$fcb = addFrameCallback(function (delta)
{
sum += delta;
log("Time elapsed: " + sum + " (delta: " + delta + ")");
});

'''See also:''' <code>[[#removeFrameCallback|removeFrameCallback()]]</code>, <code>[[#isValidFrameCallback|isValidFrameCallback()]]</code>, and for repeated events with a longer repeat interval, use [[Oolite_JavaScript_Reference:_Timer|Timers]] instead.

=== <code>displayNameForCommodity</code> ===
function '''displayNameForCommodity'''(commodityName : String) : String
Returns the display name corresponding to the specified commodity. Useful in conjunction with localisation OXPs, or expansions that rename commodities depending on which station / system the player is at.

=== <code>expandDescription</code> ===
function '''expandDescription'''(description : String [, locals : Object (Dictionary)]) : String
Expands a string, substituting special tokens and any key inside square brackets with the substitution rules for [[Missiontext.plist#Special_Expansions|string expansions]].
When local key/value pairs are provided, they take precedence over any other values.

In Oolite 1.79 or later, this method uses a higher quality random number generator which does not have noticeable correlation problems when used for recursive expansion.

'''Example:'''
expandDescription("My ball is [my_color].", { my_color: "red" });

=== <code>expandMissionText</code> ===
function '''expandMissionText'''(textKey: String [, locals : Object (Dictionary)]) : String
Load a string specified by <code>textKey</code> from [[missiontext.plist]], then perform <code>[[#expandDescription|expandDescription()]]</code>type substitutions on it, and also replace <code>"\n"</code> with line breaks. The <code>local</code> parameter works as with <code>[[#expandDescription|expandDescription()]]</code>.

In Oolite 1.79 or later, this method uses a higher quality random number generator which does not have noticeable correlation problems when used for recursive expansion.

'''Example:'''
expandMissionText("oolite_trumble_title");

=== <code>formatCredits</code> ===
function '''formatCredits'''(value : number, [includeDeciCredits : boolean, [includeCurrencySymbol : boolean]]) : String
Converts the <code>value</code> parameter to a string formatted in a currency friendly manner. If <code>includeDeciCredits</code> is <code>true</code> the string will be formatted to 1 decimal place. If <code>includeCurrencySymbol</code> is <code>true</code> an appropriate currency symbol following any localisation rules is included. The default currency symbol is a terminal ₢.

=== <code>formatInteger</code> ===
function '''formatInteger'''(value : number) : String
Converts the <code>value</code> parameter to a string formatted as an integer following any localisation rules in place.

=== <code>getGuiColorSettingForKey</code> ===
{{oolite-method-added|1.87}}
function '''getGuiColorSettingForKey'''(keyname : string) : Array
Returns the current color for a particular keyname (referenced in the [[gui-settings.plist]] file). Returns an array of RGBA values.

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

=== <code>getScreenBackgroundForKey</code> ===
{{oolite-method-added|1.85}}
function '''getScreenBackgroundForKey'''(keyname : string) : guiTextureSpecifier
Returns the guiTextureSpecifier for a particular keyname (referenced in the screenbackgrounds.plist file).

''guiTextureSpecifier'' can be either a string or an object with the required key <code>name</code> and optional keys <code>width</code> and <code>height</code>. If neither width nor height is specified, the dimensions of the image are used. If only one is specified, the other is calculated such that the image is not distorted. The scale unit is 1/480 of the height of the window; in other words, the window is always considered 480 units high, and the width depends on the aspect ratio of the window.

'''Example:'''
getScreenBackgroundForKey("long_range_chart_mission");

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

=== <code>isValidFrameCallback</code> ===
function '''isValidFrameCallback'''(trackingID: ''TrackingID'') : Boolean
Returns <code>true</code> if <code>trackingID</code> identifies a frame callback which has been registered with <code>[[#addFrameCallback|addFrameCallback()]]</code> and not yet removed. (There should be no need to use this except for debugging and testing.)

'''See also:''' <code>[[#addFrameCallback|addFrameCallback()]]</code>, <code>[[#removeFrameCallback|removeFrameCallback()]]</code>

=== <code>log</code> ===
function '''log'''([messageClass : String ,] message : String)
Writes a message to Oolite's log. The optional messageClass parameter can be used to specify which type of message is written to the log. The default messageClass is <code>script.debug.message</code>. When set to <code>true</code>, the messages will be written to the log file. The classes to be logged are set in the file <code>logcontrol.plist</code>. messageClasses not listed in <code>logcontrol.plist</code> are always logged.

'''Example:'''
log("myOXP.init","MyOXP initialised and ready!");

You can temporarily enable/disable logging the above message by typing in the console:
console.setDisplayMessagesInClass("myOXP.init", true/false)

===<code>pauseGame</code>===
function '''pauseGame'''() : Boolean
Pauses the game. It does not work on screens that cannot be paused by keyboard: mission screens, long range chart, arrival report, save menu. In those cases, the method returns <code>false</code>. Otherwise, it pauses the game and returns <code>true</code>.

This was added in v1.87 (the exact version is unconfirmed)

'''See also:''' [http://aegidian.org/bb/viewtopic.php?f=6&t=18900 Scriptable pause?]

=== <code>randomInhabitantsDescription</code> ===
function '''randomInhabitantsDescription'''([plural : boolean, default true]) : String
Returns a random sentient species name, like <code>"Large Red Fat Insects"</code> or <code>"Human Colonials"</code>, following the same pattern (and probability distribution) as for planet inhabitants.

'''Example:'''
player.consoleMessage("You'll meet a " + randomInhabitantsDescription(false) + ". She'll be with a group of " + randomInhabitantsDescription() + ".");

=== <code>randomName</code> ===
function '''randomName'''() : String
Returns a random capitalised word, suitable for use as name, or indeed surname.

'''Example:'''
player.consoleMessage(randomName() + " " + randomName() + " rules this system with an iron fist.");

=== <code>removeFrameCallback</code> ===
function '''removeFrameCallback'''(trackingID : ''TrackingID'')
Removes a frame callback previously registered with <code>[[#addFrameCallback|addFrameCallback()]]</code>.

'''See also:''' <code>[[#addFrameCallback|addFrameCallback()]]</code>, <code>[[#isValidFrameCallback|isValidFrameCallback()]]</code>

=== <code>setGuiColorSettingForKey</code> ===
{{oolite-method-added|1.87}}
function '''setGuiColorSettingorKey'''(keyname : string , [[Materials_in_Oolite#Colour_specifiers|Colour specifier]] : string)
Override the color setting for a particular keyname (referenced in the [[gui-settings.plist]] file) with the specified color. This override is only for the current play-session and does not get written to [[gui-settings.plist]].

'''Example:'''
setGuiColorSettingForKey("screen_title_color", "whiteColor");

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

=== <code>setScreenBackground</code> ===
function '''setScreenBackground'''(image : ''guiTextureSpecifier'')
Temporary override that sets the background of the current gui screen to the specified image. Override is lost after the player switches screens.

''guiTextureSpecifier'' can be either a string or an object with the required key <code>name</code> and optional keys <code>width</code> and <code>height</code>. If neither width nor height is specified, the dimensions of the image are used. If only one is specified, the other is calculated such that the image is not distorted. The scale unit is 1/480 of the height of the window; in other words, the window is always considered 480 units high, and the width depends on the aspect ratio of the window.

'''Example:'''
setScreenBackground({ name: "oolite-nova-system.png", height: 480 });

=== <code>setScreenBackgroundForKey</code> ===
{{oolite-method-added|1.85}}
function '''setScreenBackgroundForKey'''(keyname : string, image : ''guiTextureSpecifier'')
Override the background for a particular keyname (referenced in the screenbackgrounds.plist file) with the specified image. Override is only for the current play-session only and does not get written out to screenbackgrounds.plist.

''guiTextureSpecifier'' can be either a string or an object with the required key <code>name</code> and optional keys <code>width</code> and <code>height</code>. If neither width nor height is specified, the dimensions of the image are used. If only one is specified, the other is calculated such that the image is not distorted. The scale unit is 1/480 of the height of the window; in other words, the window is always considered 480 units high, and the width depends on the aspect ratio of the window.

'''Example:'''
setScreenBackgroundForKey("long_range_chart_mission", { name: "my_mission_background.png", height: 480 });

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

=== <code>setScreenOverlay</code> ===
function '''setScreenOverlay'''(image : ''guiTextureSpecifier'')
Temporary override that sets the overlay of the current gui screen to the specified image. Override is lost after the player switches screens.

See <code>[[#setScreenBackground|setScreenBackground()]]</code> for a discussion of ''guiTextureSpecifier''.

'''Example:'''
setScreenOverlay('trumblebox.png');

=== <code>takeSnapShot</code> ===
function '''takeSnapShot'''([filename : String]) : Boolean
Saves a snapshot of the current screen to your hard disk. A filename is optional. When a name is used, only alphanumeric values and <code>"-"</code> and <code>"_"</code> are allowed for the filename. The appropriate extension for the used operating system (like .png) is added by Oolite and should not be part of the filename. 
When a filename already exists, it is not overwritten but the string <code>"-xxx"</code> is added, starting with <code>"-001"</code>. 
<code>takeSnapShot()</code> will not be available in the stable release version of Oolite, but will be available in a special OXP developer release.

'''Example:'''
takeSnapShot('mission_target_1');

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Global

2022-10-30T16:51:40Z

Massively Locked: /* missionVariables */ uniform string format, cleared up wording

Global variables and functions are visible to all scripts. They are also properties of <code>[[#global|global]]</code>, which is itself a global variable and hence a property of itself.

== Properties ==
=== <code>clock</code> ===
'''clock''' : {{oojsclass|Clock}} (read-only)
This property allows an OXP to access the game clock's properties and methods.

=== <code>defaultFont</code> ===
'''defaultFont''' : Object (read-only)
An object with a single method, <code>measureString(string)</code>, which returns the width of the specified string, as it would be shown on the screen, in '''ems'''. One em is the intrinsic unit size of a font; for example, if a font is rendered at 12 points, 1 em = 12 pt. The mission screen text area is 32 em wide.

=== <code>galaxyNumber</code> ===
'''galaxyNumber''' : Number (read-only)
Returns the number of the galaxy the player is in.

=== <code>global</code> ===
'''global''' : Global (read-only)
All global variables and functions are actually properties of the global object. The global object is a property of itself, and this is it.

=== <code>guiScreen</code> ===
'''guiScreen''' : String (read-only)
Returns the screen the player is looking at. If in flight, this is <code>"GUI_SCREEN_MAIN"</code>. In 1.76, the other possible values are <code>"GUI_SCREEN_INTRO1"</code>, <code>"GUI_SCREEN_INTRO2"</code>, <code>"GUI_SCREEN_STATUS"</code>(F5), <code>"GUI_SCREEN_MANIFEST"</code>(F5F5), <code>"GUI_SCREEN_EQUIP_SHIP"</code>(F3), <code>"GUI_SCREEN_SHIPYARD"</code>(F3F3), <code>"GUI_SCREEN_LONG_RANGE_CHART"</code>(F6F6), <code>"GUI_SCREEN_SHORT_RANGE_CHART"</code>(F6), <code>"GUI_SCREEN_SYSTEM_DATA"</code>(F7), <code>"GUI_SCREEN_MARKET"</code>(F8), <code>"GUI_SCREEN_CONTRACTS"</code>, <code>"GUI_SCREEN_OPTIONS"</code>, <code>"GUI_SCREEN_GAMEOPTIONS"</code>, <code>"GUI_SCREEN_LOAD"</code>, <code>"GUI_SCREEN_SAVE"</code>, <code>"GUI_SCREEN_SAVE_OVERWRITE"</code>, <code>"GUI_SCREEN_STICKMAPPER"</code>, <code>"GUI_SCREEN_MISSION"</code> and <code>"GUI_SCREEN_REPORT"</code>.

In 1.77, <code>"GUI_SCREEN_INTERFACES"</code>(F4) is added, and <code>"GUI_SCREEN_CONTRACTS"</code> is removed.

In 1.81, <code>"GUI_SCREEN_MARKETINFO"</code>(F8F8) is added.

=== <code>manifest</code> ===
'''manifest''' : {{oojsclass|Manifest}} (read-only)
An alias to <code>[[Oolite JavaScript Reference: PlayerShip#manifest|player.ship.manifest]]</code>.

=== <code>mission</code> ===
'''mission''' : {{oojsclass|Mission}} (read-only)
See [[Oolite JavaScript Reference: Mission]].

=== <code>missionVariables</code> ===
'''missionVariables''' : Object (read-only)
The <code>missionVariables</code> object stores values that are stored in saved games. This is the main way for scripts to store information permanently.

Whenever a value is assigned to a property of <code>missionVariables</code>, it is converted to a string object and tracked with the player. When the value is read, it will be converted to a number if possible, otherwise returned as a string. Example:
missionVariables.exampleVar = 42;
let x = missionVariables.exampleVar; // x is now the number 42
Do not use <code>false</code> in missionVariables! It will return <code>true</code> because it will be parsed as a string. Use 0 or 1 to store boolean values.

You can store arrays using [http://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON JSON] stringify and parse methods. For example:
this.$MyArray = [];

this.startUp = function() {
var s = missionVariables.$MyArray;
if( s && s.length > 0 ) this.$MyArray = JSON.parse(s);
}

this.playerWillSaveGame = function(message) {
missionVariables.$MyArray = JSON.stringify(this.$MyArray);
}
Mission variables can also be used in legacy scripts and in [[descriptions.plist]] string expansions, by prefixing the name with <code>"mission_"</code>. Example:
expandDescription("My variable is [mission_exampleVar].")
Setting and retrieving mission variables has a significant overhead'''*'''. If a function needs to use a mission variable value several times, it is strongly recommended that it be copied into a local variable and, if necessary, stored back once. Example:
let x = missionVariables.exampleVar;
if (x < 3) x = processSmallValue(x);
else x = processBigValue(x);
missionVariables.exampleVar = x;
Mission variable names may not begin with an underscore (“_”). Unassigned mission variables are always <code>null</code>.

'''*''' On a computer where the loop <code>for (var i = 0; i < 1000; i++) {}</code> takes just 0.62 msec, the same loop with missionVarriables <code>for (missionVariables.i = 0; missionVariables.i < 1000; missionVariables.i++) {}</code> consumes a full 38 msec. That is 60 times longer.

=== <code>oolite</code> ===
'''oolite''' : {{oojsclass|Oolite}} (read-only)
An object describing properties of the Oolite application; see [[Oolite JavaScript Reference: Oolite]].

=== <code>player</code> ===
'''player''' : {{oojsclass|Player}} (read-only)
This property allows an OXP to access the player object's properties and methods.

=== <code>system</code> ===
'''system''' : {{oojsclass|System}} (read-only)
This property allows an OXP to access the current system's properties and methods.

=== <code>timeAccelerationFactor</code> ===
'''timeAccelerationFactor''' : Number (read/write)
Also known as TAF. Will change the ratio between game real time and actual real time (default is 1). The accepted range is between 0.0625 (1/16) and 16. Attempting to set numbers outside this range will reset the TAF to 1. (In end-user stable builds, this will be a read-only property with the value 1.)

=== <code>worldScriptNames</code> ===
'''worldScriptNames''' : Array of strings (read-only)
A list of the names of world script objects, the keys of <code>[[#worldScripts|worldScripts]]</code>.

=== <code>worldScripts</code> ===
'''worldScripts''' : Object (read-only)
All loaded world script objects. The keys are the <code>name</code> properties of the scripts.

'''Example:'''
log(worldScripts["oolite-nova"].version);

== Methods ==
=== <code>addFrameCallback</code> ===
function '''addFrameCallback'''(callback : Function) : ''TrackingID''
Registers a ''frame callback'' which will be invoked every frame, after entity updates but before rendering. This can be used to implement animations, to apply gradual changes in ship state, to build large data structures without risking reaching processing time limits by trying to do it all at once, or to watch variables which need a same-frame response to changes. The return value is a ''tracking ID'' which may be passed to <code>[[#removeFrameCallback|removeFrameCallback()]]</code>; the type and meaning of the tracking ID is unspecified and may change at any time. Frame callbacks are automatically removed when the game resets (for instance, when the player dies), but not at any other time.

The callback is passed one parameter, <code>delta</code>, which is the time since the last frame (in [[Time_scales in Oolite|game clock time]]). Frame callbacks fire even when the game is paused, in which case <code>delta</code> is 0.

'''Example:'''
var sum = 0;
this.$fcb = addFrameCallback(function (delta)
{
sum += delta;
log("Time elapsed: " + sum + " (delta: " + delta + ")");
});

'''See also:''' <code>[[#removeFrameCallback|removeFrameCallback()]]</code>, <code>[[#isValidFrameCallback|isValidFrameCallback()]]</code>, and for repeated events with a longer repeat interval, use [[Oolite_JavaScript_Reference:_Timer|Timers]] instead.

=== <code>displayNameForCommodity</code> ===
function '''displayNameForCommodity'''(commodityName : String) : String
Returns the display name corresponding to the specified commodity. Useful in conjunction with localisation OXPs, or expansions that rename commodities depending on which station / system the player is at.

=== <code>expandDescription</code> ===
function '''expandDescription'''(description : String [, locals : Object (Dictionary)]) : String
Expands a string, substituting special tokens and any key inside square brackets with the substitution rules for [[Missiontext.plist#Special_Expansions|string expansions]].
When local key/value pairs are provided, they take precedence over any other values.

In Oolite 1.79 or later, this method uses a higher quality random number generator which does not have noticeable correlation problems when used for recursive expansion.

'''Example:'''
expandDescription("My ball is [my_color].", { my_color: "red" });

=== <code>expandMissionText</code> ===
function '''expandMissionText'''(textKey: String [, locals : Object (Dictionary)]) : String
Load a string specified by <code>textKey</code> from [[missiontext.plist]], then perform <code>[[#expandDescription|expandDescription()]]</code>-type substitutions on it, and also replace “\n” with line breaks. The <code>local</code> parameter works as with <code>[[#expandDescription|expandDescription()]]</code>.

In Oolite 1.79 or later, this method uses a higher quality random number generator which does not have noticeable correlation problems when used for recursive expansion.

'''Example:'''
expandMissionText("oolite_trumble_title");

=== <code>formatCredits</code> ===
function '''formatCredits'''(value : number, [includeDeciCredits : boolean, [includeCurrencySymbol : boolean]]) : String
Converts the <code>number</code> parameter to a string formatted in a currency friendly manner. If <code>includeDeciCredits</code> is <code>true</code> the string will be formatted to 1 decimal place. If <code>includeCurrencySymbol</code> is <code>true</code> an appropriate currency symbol following any localisation rules is included. The default currency symbol is a terminal ₢.

=== <code>formatInteger</code> ===
function '''formatInteger'''(value : number) : String
Converts the <code>number</code> parameter to a string formatted as an integer following any localisation rules in place.

=== <code>getGuiColorSettingForKey</code> ===
{{oolite-method-added|1.87}}
function '''getGuiColorSettingForKey'''(keyname : string) : Array
Returns the current color for a particular keyname (referenced in the [[gui-settings.plist]] file). Returns an array of RGBA values.

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

=== <code>getScreenBackgroundForKey</code> ===
{{oolite-method-added|1.85}}
function '''getScreenBackgroundForKey'''(keyname : string) : guiTextureSpecifier
Returns the guiTextureSpecifier for a particular keyname (referenced in the screenbackgrounds.plist file).

''guiTextureSpecifier'' can be either a string or an object with the required key <code>name</code> and optional keys <code>width</code> and <code>height</code>. If neither width nor height is specified, the dimensions of the image are used. If only one is specified, the other is calculated such that the image is not distorted. The scale unit is 1/480 of the height of the window; in other words, the window is always considered 480 units high, and the width depends on the aspect ratio of the window.

'''Example:'''
getScreenBackgroundForKey("long_range_chart_mission");

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

=== <code>isValidFrameCallback</code> ===
function '''isValidFrameCallback'''(trackingID: ''TrackingID'') : Boolean
Returns <code>true</code> if <code>trackingID</code> identifies a frame callback which has been registered with <code>[[#addFrameCallback|addFrameCallback()]]</code> and not yet removed. (There should be no need to use this except for debugging and testing.)

'''See also:''' <code>[[#addFrameCallback|addFrameCallback()]]</code>, <code>[[#removeFrameCallback|removeFrameCallback()]]</code>

=== <code>log</code> ===
function '''log'''([messageClass : String ,] message : String)
Writes a message to Oolite's log. The optional messageClass parameter can be used to specify which type of message is written to the log. The default messageClass is <code>script.debug.message</code>. When set to <code>true</code>, the messages will be written to the log file. The classes to be logged are set in the file <code>logcontrol.plist</code>. messageClasses not listed in <code>logcontrol.plist</code> are always logged.

'''Example:'''
log("myOXP.init","MyOXP initialised and ready!");

You can temporarily enable/disable logging the above message by typing in the console:
console.setDisplayMessagesInClass("myOXP.init", true/false)

===<code>pauseGame</code>===
function '''pauseGame'''() : Boolean
Pauses the game. It does not work on screens that cannot be paused by keyboard: mission screens, long range chart, arrival report, save menu. In those cases, the method returns <code>false</code>. Otherwise, it pauses the game and returns <code>true</code>.

This was added in v1.87 (the exact version is unconfirmed)

'''See also:''' [http://aegidian.org/bb/viewtopic.php?f=6&t=18900 Scriptable pause?]

=== <code>randomInhabitantsDescription</code> ===
function '''randomInhabitantsDescription'''([plural : boolean, default true]) : String
Returns a random sentient species name, like “Large Red Fat Insects” or “Human Colonials”, following the same pattern (and probability distribution) as for planet inhabitants.

'''Example:'''
player.consoleMessage("You'll meet a " + randomInhabitantsDescription(false) + ". She'll be with a group of " + randomInhabitantsDescription() + ".");

=== <code>randomName</code> ===
function '''randomName'''() : String
Returns a random capitalised word, suitable for use as name, or indeed surname.

'''Example:'''
player.consoleMessage(randomName() + " " + randomName() + " rules this system with an iron fist.");

=== <code>removeFrameCallback</code> ===
function '''removeFrameCallback'''(trackingID : ''TrackingID'')
Removes a frame callback previously registered with <code>[[#addFrameCallback|addFrameCallback()]]</code>.

'''See also:''' <code>[[#addFrameCallback|addFrameCallback()]]</code>, <code>[[#isValidFrameCallback|isValidFrameCallback()]]</code>

=== <code>setGuiColorSettingForKey</code> ===
{{oolite-method-added|1.87}}
function '''setGuiColorSettingorKey'''(keyname : string , [[Materials_in_Oolite#Colour_specifiers|Colour specifier]] : string)
Override the color setting for a particular keyname (referenced in the [[gui-settings.plist]] file) with the specified color. This override is only for the current play-session and does not get written to [[gui-settings.plist]].

'''Example:'''
setGuiColorSettingForKey("screen_title_color", "whiteColor");

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

=== <code>setScreenBackground</code> ===
function '''setScreenBackground'''(image : ''guiTextureSpecifier'')
Temporary override that sets the background of the current gui screen to the specified image. Override is lost after the player switches screens.

''guiTextureSpecifier'' can be either a string or an object with the required key <code>name</code> and optional keys <code>width</code> and <code>height</code>. If neither width nor height is specified, the dimensions of the image are used. If only one is specified, the other is calculated such that the image is not distorted. The scale unit is 1/480 of the height of the window; in other words, the window is always considered 480 units high, and the width depends on the aspect ratio of the window.

'''Example:'''
setScreenBackground({ name: "oolite-nova-system.png", height: 480 });

=== <code>setScreenBackgroundForKey</code> ===
{{oolite-method-added|1.85}}
function '''setScreenBackgroundForKey'''(keyname : string, image : ''guiTextureSpecifier'')
Override the background for a particular keyname (referenced in the screenbackgrounds.plist file) with the specified image. Override is only for the current play-session only and does not get written out to screenbackgrounds.plist.

''guiTextureSpecifier'' can be either a string or an object with the required key <code>name</code> and optional keys <code>width</code> and <code>height</code>. If neither width nor height is specified, the dimensions of the image are used. If only one is specified, the other is calculated such that the image is not distorted. The scale unit is 1/480 of the height of the window; in other words, the window is always considered 480 units high, and the width depends on the aspect ratio of the window.

'''Example:'''
setScreenBackgroundForKey("long_range_chart_mission", { name: "my_mission_background.png", height: 480 });

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

=== <code>setScreenOverlay</code> ===
function '''setScreenOverlay'''(image : ''guiTextureSpecifier'')
Temporary override that sets the overlay of the current gui screen to the specified image. Override is lost after the player switches screens.

See <code>[[#setScreenBackground|setScreenBackground()]]</code> for a discussion of ''guiTextureSpecifier''.

'''Example:'''
setScreenOverlay('trumblebox.png');

=== <code>takeSnapShot</code> ===
function '''takeSnapShot'''([filename : String]) : Boolean
Saves a snapshot of the current screen to your hard disk. A filename is optional. When a name is used, only alphanumeric values and "-" and "_" are allowed for the filename. The appropriate extension for the used operating system (like .png) is added by Oolite and should not be part of the filename. 
When a filename already exists, it is not overwritten but the string "-xxx" is added, starting with "-001". 
<code>takeSnapShot()</code> will not be available in the stable release version of Oolite, but will be available in a special OXP developer release.

'''Example:'''
takeSnapShot('mission_target_1');

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Script

2022-10-30T15:43:54Z

Massively Locked: /* Common properties */ added code tags

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

The '''<code>Script</code>''' class represents a JavaScript script. There are several categories of scripts: ''ship scripts'' which are attached to individual ships/in-game entities and ''world scripts'' which are effectively attached to the player. There are also ''[[Oolite JavaScript Reference: Condition scripts| Condition scripts]]'', ''[[Oolite JavaScript Reference: Equipment scripts| Equipment scripts]]'', ''[[Oolite JavaScript Reference: Market Scripts| Market Scripts]]'' and ''[[Oolite JavaScript Reference: VisualEffect#Effect Scripts|Visual Effects Scripts]]''.

==Scripting overview==
World scripts are run once at game start-up, at which point they may create ''event handlers''. Event handlers are functions with predefined names which are called by the game at specific points. Ship scripts are run when their ship is loaded, and can also create event handlers. An event handler is specified as a property of the <code>Script</code> object itself. For example, to set up an event handler for the ''willDock'' event, a script would typically look like this:
this.willDock = function()
{
// Do stuff when about to dock
log("Woo, I’m about to dock!");
}

This assigns an anonymous function with no arguments to the <code>Script</code> object’s <code>willDock</code> property.

A property of the <code>Script</code> object which is a function is called a '''method'''. The most common use for methods is for event handlers, but a script may assign itself arbitrary methods, and any script may call the methods of another <code>Script</code> object. For instance, consider the case of a ship which needs to interact with its escorts in an unusual way. The script for the escorts may define a method such as:
this._escortPerformSpecialManoeuvre = function (target)
{
// Do something very clever here
}
which the mothership might do as follows:
// Warning: untested code
this._makeEscortsPerformSpecialManoeuvre = function (target)
{
this.ship.escorts.forEach(function(escort){escort.script._escortPerformSpecialManoeuvre(this.target)}, this);
}
I can hear the cries of “huh” now, so let’s expand on that a little:
this._makeEscortsPerformSpecialManoeuvre = function (target)
{
// The function we want to call for each element of the escorts array.
function callEscortMethod(escort)
{
escort.script._escortPerformSpecialManoeuvre(this.target);
}

// Get the list of escorts from our ship.
var escorts = this.ship.escorts;

// For each element in the list, call callEscortMethod().
escorts.forEach(callEscortMethod, this);
}

<code>Script</code> objects do not have many predefined properties. Instead, the script can set whatever properties it needs. Which properties are used by the game depends on the context in which the script is being used. Note that properties not intended to be event handlers should have names starting with an '_' or '$' character, so that future additions of Oolite event handlers do not cause a conflict.

==Predefined properties==
===<code>ship</code>===
'''ship''' : [[Oolite JavaScript Reference: Ship|Ship]] (read-only)
For ship scripts, this is the ship to which the script is attached. For world scripts, it is undefined.

'''Note''' that <code>ship</code> refers to the {{oojsclass|Ship}} object that “owns” the script, which might not be a ship from a player perspective; it may be a station, missile, asteroid etc.

==Common properties==
These are properties scripts can set on themselves which have a standard meaning. In Oolite 1.79 and later, the <code>author</code>, <code>license</code> and <code>version</code> properties will be set automatically from the [[manifest.plist]] file if one is available, and so do not need to be included in the script file itself.

===<code>author</code>===
'''author''' : String
Who wrote the script. This property is currently not checked by any Oolite core functionality.

===<code>copyright</code>===
'''copyright''' : String
A copyright statement for the script. This property is currently not checked by any Oolite core functionality.

===<code>description</code>===
'''description''' : String
A short description of the script. This property is currently not checked by any Oolite core functionality.

===<code>license</code>===
'''license''' : String
A statement of the license for the script. This property is currently not checked by any Oolite core functionality.

===<code>name</code>===
'''name''' : String
The name of the script. World scripts must have a unique <code>name</code>. It’s a good habit to set a <code>name</code> for all scripts. If no <code>name</code> is set when the script is first run, Oolite will make one up. While it is possible to set the <code>name</code> property at any time, the value used after the script is first run is the one Oolite will continue to use.

Starting in Oolite 1.75, any underscores (“_”) or spaces will be removed from the beginning and end of the <code>name</code> property.

===<code>version</code>===
'''version''' : String
A string specifying the version of the script. This is used, together with <code>name</code>, for identification in log messages and similar. While it is possible to set the <code>version</code> property at any time, the value used after the script is first run is the one Oolite will continue to use. It is recommended to have this value equal the version of the OXP containing the script.

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Script

2022-10-30T15:37:09Z

Massively Locked: /* ship */ reworded

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

The '''<code>Script</code>''' class represents a JavaScript script. There are several categories of scripts: ''ship scripts'' which are attached to individual ships/in-game entities and ''world scripts'' which are effectively attached to the player. There are also ''[[Oolite JavaScript Reference: Condition scripts| Condition scripts]]'', ''[[Oolite JavaScript Reference: Equipment scripts| Equipment scripts]]'', ''[[Oolite JavaScript Reference: Market Scripts| Market Scripts]]'' and ''[[Oolite JavaScript Reference: VisualEffect#Effect Scripts|Visual Effects Scripts]]''.

==Scripting overview==
World scripts are run once at game start-up, at which point they may create ''event handlers''. Event handlers are functions with predefined names which are called by the game at specific points. Ship scripts are run when their ship is loaded, and can also create event handlers. An event handler is specified as a property of the <code>Script</code> object itself. For example, to set up an event handler for the ''willDock'' event, a script would typically look like this:
this.willDock = function()
{
// Do stuff when about to dock
log("Woo, I’m about to dock!");
}

This assigns an anonymous function with no arguments to the <code>Script</code> object’s <code>willDock</code> property.

A property of the <code>Script</code> object which is a function is called a '''method'''. The most common use for methods is for event handlers, but a script may assign itself arbitrary methods, and any script may call the methods of another <code>Script</code> object. For instance, consider the case of a ship which needs to interact with its escorts in an unusual way. The script for the escorts may define a method such as:
this._escortPerformSpecialManoeuvre = function (target)
{
// Do something very clever here
}
which the mothership might do as follows:
// Warning: untested code
this._makeEscortsPerformSpecialManoeuvre = function (target)
{
this.ship.escorts.forEach(function(escort){escort.script._escortPerformSpecialManoeuvre(this.target)}, this);
}
I can hear the cries of “huh” now, so let’s expand on that a little:
this._makeEscortsPerformSpecialManoeuvre = function (target)
{
// The function we want to call for each element of the escorts array.
function callEscortMethod(escort)
{
escort.script._escortPerformSpecialManoeuvre(this.target);
}

// Get the list of escorts from our ship.
var escorts = this.ship.escorts;

// For each element in the list, call callEscortMethod().
escorts.forEach(callEscortMethod, this);
}

<code>Script</code> objects do not have many predefined properties. Instead, the script can set whatever properties it needs. Which properties are used by the game depends on the context in which the script is being used. Note that properties not intended to be event handlers should have names starting with an '_' or '$' character, so that future additions of Oolite event handlers do not cause a conflict.

==Predefined properties==
===<code>ship</code>===
'''ship''' : [[Oolite JavaScript Reference: Ship|Ship]] (read-only)
For ship scripts, this is the ship to which the script is attached. For world scripts, it is undefined.

'''Note''' that <code>ship</code> refers to the {{oojsclass|Ship}} object that “owns” the script, which might not be a ship from a player perspective; it may be a station, missile, asteroid etc.

==Common properties==
These are properties scripts can set on themselves which have a standard meaning. In Oolite 1.79 and later, the <code>author</code>, <code>license</code> and <code>version</code> properties will be set automatically from the [[manifest.plist]] file if one is available, and so do not need to be included in the script file itself.

===<code>author</code>===
'''author''' : String
Who wrote the script. This property is currently not checked by any Oolite core functionality.

===<code>copyright</code>===
'''copyright''' : String
A copyright statement for the script. This property is currently not checked by any Oolite core functionality.

===<code>description</code>===
'''description''' : String
A short description of the script. This property is currently not checked by any Oolite core functionality.

===<code>license</code>===
'''license''' : String
A statement of the license for the script. This property is currently not checked by any Oolite core functionality.

===<code>name</code>===
'''name''' : String
The name of the script. World scripts must have a unique name. It’s a good habit to set a name for all scripts. If no name is set when the script is first run, Oolite will make one up. While it is possible to set the <code>name</code> property at any time, the value used after the script is first run is the one Oolite will continue to use.

Starting in Oolite 1.75, any underscores (“_”) or spaces will be removed from the beginning and end of the name property.

===<code>version</code>===
'''version''' : String
A string specifying the version of the script. This is used, together with name, for identification in log messages and similar. While it is possible to set the <code>version</code> property at any time, the value used after the script is first run is the one Oolite will continue to use. It is recommended to have this value equal the version of the OXP containing the script.

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Oolite

2022-10-30T15:14:40Z

Massively Locked: /* gameSettings */ added code tags, cleared up wording

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

The '''<code>Oolite</code>''' class represents Oolite itself. It allows scripts to access information about the application. There is a global instance of <code>Oolite</code>, named <code>oolite</code>.

== Properties ==
=== <code>gameSettings</code> ===
'''gameSettings''' : Object(read-only)
This property allows an [[OXP]] to detect various game settings. It has the following read-only properties:

autosave : Boolean
gameWindow : Object (see below)
keyConfig : Object (from v1.77.1 onwards, see below)
musicMode : String ("MUSIC_OFF", "MUSIC_ON", or "MUSIC_ITUNES")
procedurallyTexturedPlanets : Boolean
reducedDetailGraphics : Boolean
detailLevel : String ("DETAIL_LEVEL_MINIMUM", "DETAIL_LEVEL_NORMAL", "DETAIL_LEVEL_SHADERS", or "DETAIL_LEVEL_EXTRAS")
speechOn : Boolean
wireframeGraphics : Boolean

Before 1.80, there was no <code>detailLevel</code> property, but there was a <code>shaderEffectsLevel</code> property.

The <code>gameWindow</code> property contains the following properties:
height : Number
width : Number
fullScreen : Boolean

The <code>keyConfig</code> property contains numeric (decimal) KeyCode values of all Keyconfig Entries in oolite.app/Resources/Config/keyconfig.plist. Keyconfig Entry - KeyCode pairs are documented in ''[[Oolite_Keyboard_Controls]]''.

You can use the standard Javascript <code>String.fromCharCode()</code> method to convert KeyCode to a string:
var button = String.fromCharCode( oolite.gameSettings.keyConfig.key_ident_system );
player.consoleMessage( "Press " + button + " to turn on the ident system." );

Keys like tab, escape, arrow keys, etc. need to be handled separately.

=== <code>jsVersion</code> ===
'''jsVersion''' : Number (read-only)
The version of the JavaScript language implemented by this version of Oolite, multiplied by 100, as an integer. For instance, for [http://developer.mozilla.org/en/docs/New_in_JavaScript_1.7 JavaScript 1.7] (used in Oolite 1.74), this will be equal to <code>170</code>.

=== <code>jsVersionString</code> ===
'''jsVersionString''' : String (read-only)
The version of the JavaScript language implemented by this version of Oolite, as a string. For instance, for JavaScript 1.7, this will be equal to <code>"1.7"</code>.

=== <code>resourcePaths</code> ===
{{oolite-method-added|1.83}}
'''resourcePaths''' : Array (read-only)
Contain full path of loaded config files and expansion packs, including all .oxp folders and .oxz files.

=== <code>version</code> ===
'''version''' : Array (read-only)
The version of Oolite, as an array of version components. For instance, for Oolite 1.74 this is <code>[1, 74]</code>. For version 1.73.4, it is <code>[1, 73, 4]</code>.

=== <code>versionString</code> ===
'''versionString''' : String (read-only)
The version of Oolite, as a string. For instance, for Oolite 1.74 this is <code>"1.74"</code>. For version 1.73.4, it is <code>"1.73.4"</code>.

== Methods ==
=== <code>compareVersion</code> ===
function '''compareVersion'''(versionSpec) : Number
Compare the version of Oolite to <code>versionSpec</code>, which may be either a string or an array (in the format given by <code>[[#version|version]]</code>). If the current version of Oolite is less than <code>versionSpec</code>, 1 is returned. If the current version of Oolite is greater than <code>versionSpec</code>, -1 is returned. If they are equal, 0 is returned. Example:
if (0 < oolite.compareVersion("1.80"))
{
// Oolite version is older than 1.80.
log(this.name, "An old version of Oolite (" + oolite.versionString + ") is in use. Some features of SuperDuperOXP will not be available.")
}
else
{
// Enable advanced features here.
}

[[Category:Oolite JavaScript Reference]]

== Radical changes (new galaxies ''etc'') ==
[[User:Cim|Cim]] talks [http://aegidian.org/bb/viewtopic.php?f=4&t=17603 here] about doing this sort of thing.

Oolite Javascript Reference: PriorityAI Documentation

2022-10-30T14:35:59Z

Massively Locked: uniform null format (x6)

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.

Priority-based Javascript AI is available from Oolite 1.79 onwards.

== Constructor and general functions ==

==== Constructor ====
'''new PriorityAIController'''(ship : Ship) : PriorityAIController
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.

var ai = new worldScripts["oolite-libPriorityAI"].PriorityAIController(this.ship);

=== Properties ===

==== <code>ship</code> ====
'''ship''' : Ship (read-only)
The ship to which the priority AI is attached.

=== General Methods ===

Additional methods are described in later sections, sorted by purpose.

==== <code>applyHandlers</code> ====
function '''applyHandlers'''(handlers : Object)
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.

==== <code>clearHandlers</code> ====
function '''clearHandlers'''(handlers : Object)
Deletes any existing event handlers applied to the ship's AI Script by a previous invocation of <code>applyHandlers</code>.

==== <code>communicate</code> ====
function '''communicate'''(key : String, params : Object, priority : Number)
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:
* <code>oolite_entityClass</code> = <code>ship.shipClassName</code>
* <code>oolite_entityName</code> = <code>ship.shipUniqueName</code>
Other parameters may be added later to this expansion.

The priority can be a number from 1 to 4
# Always send this message
# Send this message if no messages sent in the last 10 seconds
# Send this message if no messages sent or received in the last 10 seconds
# Send this message if no messages sent or received in the last 60 seconds
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.

==== <code>communicationsPersonality</code> ====
function '''communicationsPersonality'''() : String
The current communications personality

==== <code>communicationsRole</code> ====
function '''communicationsRole'''() : String
The current communications role

==== <code>getParameter</code> ====
function '''getParameter'''(key : String) : Value
If a parameter with that key has previously been set, return its value. Otherwise return <code>null</code>. Note that the return value can be of any type, so you must be careful when setting and retrieving parameters to avoid type errors.

==== <code>getWaypointGenerator</code> ====
function '''getWaypointGenerator'''() : Function
If a waypoint generation function has previously been set, return it.

==== <code>noteCommsHeard</code> ====
function '''noteCommsHeard'''()
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.

==== <code>reconsiderIn</code> ====
function '''reconsiderIn'''(delay : Number)
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.

==== <code>reconsiderNow</code> ====
function '''reconsiderNow'''()
Force a reconsideration of the AI's priority list ahead of schedule.

==== <code>setCommunicationsRole</code> ====
function '''setCommunicationsRole'''(role : String)
Sets the ship's communications role to the given value. This is then used to vary the communications messages as defined by [[#setCommunication|_setCommunication]].

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)

==== <code>setCommunicationsPersonality</code> ====
function '''setCommunicationsPersonality'''(role : String)
Sets the ship's communications personality to the given value. This is then used to vary the communications messages as defined by [[#setCommunication|_setCommunication]].

==== <code>setParameter</code> ====
function '''setParameter'''(key : String, value : Value)
Set the named parameter to the given value. Values may be of any type. To remove a parameter, use a value of <code>null</code>. See the [[#Parameters|Parameters]] section below for parameter keys used by the core AIs and the standard priority AI library.

==== <code>setPriorities</code> ====
function '''setPriorities'''(priorities : Array [, delay: Number])
Set the priority list for the AI, and evaluate it. The format of the priority list is described in the next section.

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.

==== <code>setWaypointGenerator</code> ====
function '''setWaypointGenerator'''(generator : Function)
Sets the AI's [[#Waypoint_Generators|Waypoint Generators]] waypoint generator function.

=== Parameters ===
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.

As with all custom items, prefixing new parameter names with a key unique to your OXP is strongly advised.

==== Flag Parameters ====
Flag parameters are intended to be set in the AI initialisation routine to vary the behaviour of the AI.

oolite_flag_allowPlanetaryLanding
oolite_flag_autoSpreadMissiles
oolite_flag_behaviourLogging
oolite_flag_continueUnlikelyPursuits
oolite_flag_escortsCoverRetreat
oolite_flag_fightsNearHostileStations
oolite_flag_fleesPreemptively
oolite_flag_likesInterstellarSpace
oolite_flag_listenForDistressCall
oolite_flag_markOffenders
oolite_flag_neverFleeToWitchspace
oolite_flag_noDockingUntilDestination
oolite_flag_noSpecialThargoidReaction
oolite_flag_patrolStation
oolite_flag_scanIgnoresUnpowered
oolite_flag_selfDestructAbandonedShip
oolite_flag_sendsDistressCalls
oolite_flag_surrendersEarly
oolite_flag_surrendersLate
oolite_flag_watchForCargo
oolite_flag_witchspacePursuit

==== Other parameters ====
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.

oolite_cargoDropped
oolite_cascadeDetected
oolite_distressAggressor
oolite_distressSender
oolite_distressTimestamp
oolite_dockingStation
oolite_escortRole
oolite_friendlyRoles
oolite_groupPower
oolite_interceptCoordinates
oolite_interceptTarget
oolite_lastAssist
oolite_lastFleeing
oolite_lastPirateVictim
oolite_leaderRole
oolite_personalityMatchesLeader
oolite_pirateLurk
oolite_playerFriendlyFireAlready
oolite_rememberedTarget
oolite_scanResults
oolite_scanResultSpecific
oolite_selectedPlanet
oolite_selectedStation
oolite_stationPatrolRole
oolite_waypoint
oolite_waypointRange
oolite_waypoints
oolite_witchspaceDestination
oolite_witchspaceEntry
oolite_witchspaceWormhole

== Writing a priority list ==

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.

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!

=== Basic structure ===

The priority list is an array of objects. Each object contains a set
of keys and values. The keys are considered in the
following order and are all optional.
* '''preconfiguration''': function run unconditionally if this element of the list is reached.
* '''condition''': function run unconditionally if this element of the list is reached. If it returns <code>false</code>, the remainder of the object is ignored, and consideration moves to the next list element.
* '''notcondition''': function run unconditionally if this element of the list is reached. If it returns <code>true</code>, the remainder of the object is ignored, and consideration moves to the next list element.
If neither '''condition''' nor '''notcondition''' are set, this is treated as if a condition was set and was <code>true</code>.
* '''configuration''': function run if conditions allow
* '''behaviour''': function run if conditions allow. If this exists, no further elements of the priority list will be considered.
* '''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.
* '''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.
* '''falsebranch''': a priority list array. This will be executed if the the conditions caused the previous four elements to be skipped.

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

Example of simple behaviour: (from thargoid AI)
{
preconfiguration: ai.configurationCheckScanner,
condition: ai.conditionScannerContainsNonThargoid,
configuration: ai.configurationAcquireScannedTarget,
behaviour: ai.behaviourDestroyCurrentTarget,
reconsider: 1
},

Example of branch usage: (from police AI)
{
/* The group leader leads the patrol */
condition: ai.conditionIsGroupLeader,
truebranch: [
/* Nothing interesting here. Patrol for a bit */
{
condition: ai.conditionHasWaypoint,
configuration: ai.configurationSetDestinationToWaypoint,
behaviour: ai.behaviourApproachDestination,
reconsider: 30
},
/* No patrol route set up. Make one */
{
configuration: ai.configurationSetWaypoint,
behaviour: ai.behaviourApproachDestination,
reconsider: 30
}
],
/* Other ships in the group will set themselves up
* as escorts if possible, or looser followers if
* not */
falsebranch: [
{
preconfiguration: ai.configurationEscortGroupLeader,
condition: ai.conditionIsEscorting,
behaviour: ai.behaviourEscortMothership,
reconsider: 30
},
/* if we can't set up as an escort */
{
behaviour: ai.behaviourFollowGroupLeader,
reconsider: 15
}
]
}

The AI Library provides a selection of standard condition,
configuration and behaviour functions for us in AIs, but you can also
write your own.
/* Ship is unstable and may explode under stress */
{
condition: function()
{
return Math.random() < 0.01; // 1% chance per evaluation
}
behaviour: function()
{
this.ship.explode();
}
}

=== Evaluation context ===

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.

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

== Behaviour functions ==

Behaviour functions determine what the ship will do next. They
generally begin a particular behaviour, and set up event handlers
(generally aided by the response templates) to allow interruption or
modification of that behaviour should anything interesting happen.

Behaviour functions take no arguments and return nothing.

=== General behaviours ===

Behaviours intended for ships in general. These mostly use <code>responsesAddStandard</code>, and occasionally add others.

==== <code>behaviourApproachDestination</code> ====
function '''behaviourApproachDestination'''()
Travels from the current position to within <code>desiredRange</code> of <code>destination</code>, avoiding obstacles on the way.

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.

Temporary waypoints needed to avoid obstacles will be stored in the
"oolite_waypoints" parameter.

==== <code>behaviourAssassinateCurrentTarget</code> ====
function '''behaviourAssassinateCurrentTarget'''()
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]]

==== <code>behaviourAvoidCascadeExplosion</code> ====
function '''behaviourAvoidCascadeExplosion'''()
Fly, using injectors if available, to a safe distance from any nearby quirium cascades (or active mines)

==== <code>behaviourBecomeInactiveThargon</code> ====
function '''behaviourBecomeInactiveThargon'''()
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.

==== <code>behaviourCollectSalvage</code> ====
function '''behaviourCollectSalvage'''()
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.

==== <code>behaviourCommenceAttackOnCurrentTarget</code> ====
function '''behaviourCommenceAttackOnCurrentTarget'''()
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.

==== <code>behaviourDestroyCurrentTarget</code> ====
function '''behaviourDestroyCurrentTarget'''()
This behaviour attacks the current target, only stopping when interrupted or when the target is destroyed.

==== <code>behaviourDockWithStation</code> ====
function '''behaviourDockWithStation'''()
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.

==== <code>behaviourEnterWitchspace</code> ====
function '''behaviourEnterWitchspace'''()
This behaviour attempts to enter witchspace. It can do this in several ways:
* If the parameter "oolite_witchspaceWormhole" is set to an active wormhole, it will try to fly to and use that wormhole.
* 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.
* Otherwise, it will wait for a wormhole to be suggested by another member of its group, or for the player to create one.

==== <code>behaviourEscortMothership</code> ====
function '''behaviourEscortMothership'''()
This behaviour performs non-combat escorting of the ship's group leader, in the formation requested by the lead ship.

==== <code>behaviourFineCurrentTarget</code> ====
function '''behaviourFineCurrentTarget'''()
If the ship has scan class "CLASS_POLICE" and a current target, mark that target for fines when it next docks.

==== <code>behaviourFleeCombat</code> ====
function '''behaviourFleeCombat'''()
The ship will flee from hostility, in the following order:
* Cascade explosions (coordinates from the parameter "oolite_cascadeDetected")
* Its current target, if it can see it
* Its defense targets, if it can see them

==== <code>behaviourFollowCurrentTarget</code> ====
function '''behaviourFollowCurrentTarget'''()
The ship will follow the current target, including through a witchspace jump if necessary, and will additionally [[#conditionHasRememberedTarget|remember]] the target.

==== <code>behaviourFollowGroupLeader</code> ====
function '''behaviourFollowGroupLeader'''()
The ship will follow the group leader if there is one, attempting to remain within a few kilometres of it.

==== <code>behaviourGuardTarget</code> ====
function '''behaviourGuardTarget'''()
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.

==== <code>behaviourJoinTargetGroup</code> ====
function '''behaviourJoinTargetGroup'''()
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.

==== <code>behaviourLandOnPlanet</code> ====
function '''behaviourLandOnPlanet'''()
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.

==== <code>behaviourLeaveVicinityOfDestination</code> ====
function '''behaviourLeaveVicinityOfDestination'''()
Moves outside scanner range of the current destination coordinates.

==== <code>behaviourLeaveVicinityOfTarget</code> ====
function '''behaviourLeaveVicinityOfTarget'''()
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.

==== <code>behaviourMineTarget</code> ====
function '''behaviourMineTarget'''()
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.

==== <code>behaviourOfferToEscort</code> ====
function '''behaviourOfferToEscort'''()
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.

To be accepted as an escort, the ship must have a primary role in the <code>oolite-escorts</code> [[role-categories.plist|role category]].

==== <code>behaviourPayOffPirates</code> ====
function '''behaviourPayOffPirates'''()
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]]

==== <code>behaviourReconsider</code> ====
function '''behaviourReconsider'''()
Does nothing except schedule a re-evaluation of the priority list.

==== <code>behaviourRejoinMothership</code> ====
function '''behaviourRejoinMothership'''()
This behaviour flies to rejoin the mothership, and then escorts it as in [[#behaviourEscortMothership|behaviourEscortMothership]].

==== <code>behaviourRepelCurrentTarget</code> ====
function '''behaviourRepelCurrentTarget'''()
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.

==== <code>behaviourRespondToDistressCall</code> ====
function '''behaviourRespondToDistressCall'''()
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.

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.

==== <code>behaviourRobTarget</code> ====
function '''behaviourRobTarget'''()
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.

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.

==== <code>behaviourSunskim</code> ====
function '''behaviourSunskim'''()
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.

==== <code>behaviourTumble</code> ====
function '''behaviourTumble'''()
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.

==== <code>behaviourWaitHere</code> ====
{{oolite-method-added|1.81}}
function '''behaviourWaitHere'''()
Stop at (or close to) the current location, and wait for something to happen.

=== Missile behaviours ===

Missile behaviours use <code>responsesAddMissile</code>. More discussion of setting missile parameters, ECM response, and detonation can be found there.

==== <code>behaviourMissileInterceptCoordinates</code> ====
function '''behaviourMissileInterceptCoordinates'''()
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.

==== <code>behaviourMissileInterceptTarget</code> ====
function '''behaviourMissileInterceptTarget'''()
Close to the desired missile range (default 25m, or specified by the <code>oolite_missile_proximity</code> key in script info), detonating when reached.

==== <code>behaviourMissileSelfDestruct</code> ====
function '''behaviourMissileSelfDestruct'''()
Destroys the missile without detonating the payload.

=== Station behaviours ===

Station behaviours use <code>responsesAddStation</code> to set up their general handlers, as most standard behaviours are unnecessary or unhelpful for a stationary station.

==== <code>behaviourStationLaunchDefenseShips</code> ====
function '''behaviourStationLaunchDefenseShips'''()
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.

==== <code>behaviourStationLaunchMiner</code> ====
function '''behaviourStationLaunchMiner'''()
If the station does not currently have a miner in its ship group, launches one. Also reduces the alert condition by one step.

==== <code>behaviourStationLaunchPatrol</code> ====
function '''behaviourStationLaunchPatrol'''()
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.

==== <code>behaviourStationLaunchSalvager</code> ====
function '''behaviourStationLaunchSalvager'''()
Launches a salvager. Also reduces the alert condition by one step.

==== <code>behaviourStationManageTraffic</code> ====
function '''behaviourStationManageTraffic'''()
The station idles. If the system repopulator has requested launches that this station can fulfil, it may launch a ship.

==== <code>behaviourStationRespondToDistressCall</code> ====
function '''behaviourStationRespondToDistressCall'''()
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.

== Condition functions ==

Condition functions are used to determine whether to execute a
priority AI behaviour. They take no arguments and return a Boolean.

=== Combat conditions ===

Conditions related to the ship's performance in combat.

==== <code>conditionCascadeDetected</code> ====
function '''conditionCascadeDetected'''() : Boolean
Returns <code>true</code> if a cascade explosion has been detected recently (as given by the parameter "oolite_cascadeDetected" containing the explosion coordinates).

==== <code>conditionCombatOdds*</code> ====
function '''conditionCombatOddsTerrible'''() : Boolean
function '''conditionCombatOddsBad'''() : Boolean
function '''conditionCombatOddsGood'''() : Boolean
function '''conditionCombatOddsExcellent'''() : Boolean
These functions return <code>true</code> 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.

==== <code>conditionGroupAttritionReached</code> ====
function '''conditionGroupAttritionReached'''() : Boolean
This condition is <code>true</code> if the ship is in a group and that group has lost more than a quarter of its initial ships.

==== <code>conditionGroupSuppliesLow</code> ====
function '''conditionGroupSuppliesLow'''() : Boolean
This condition is <code>true</code> if the ship's group is running out of consumables such as missiles or fuel, or has several damaged ships.

==== <code>conditionInCombat</code> ====
function '''conditionInCombat'''() : Boolean
The ship is currently attacking other ships, or a ship in its group or one of its escorts is.

==== <code>conditionInCombatWithHostiles</code> ====
function '''conditionInCombatWithHostiles'''() : Boolean
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)

==== <code>conditionLosingCombat</code> ====
function '''conditionLosingCombat'''() : Boolean
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.

==== <code>conditionMothershipInCombat</code> ====
function '''conditionMothershipInCombat'''() : Boolean
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.

==== <code>conditionMothershipIsAttacking</code> ====
function '''conditionMothershipIsAttacking'''() : Boolean
This ship's group leader is attacking a target. This ship must be able to see its leader's target.

==== <code>conditionMothershipIsAttackingHostileTarget</code> ====
function '''conditionMothershipIsAttackingHostileTarget'''() : Boolean
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.

==== <code>conditionMothershipUnderAttack</code> ====
function '''conditionMothershipUnderAttack'''() : Boolean
This ship's group leader is currently being targeted. This ship must be able to see the attacker.

==== <code>conditionSuppliesLow</code> ====
function '''conditionSuppliesLow'''() : Boolean
This condition is <code>true</code> 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>.

=== Navigation conditions ===

Conditions related to the ship's surroundings and navigation through the system.

==== <code>conditionCanWitchspaceOnRoute</code> ====
function '''conditionCanWitchspaceOnRoute'''() : Boolean
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.

==== <code>conditionCanWitchspaceOut</code> ====
function '''conditionCanWitchspaceOut'''() : Boolean
The ship has a witchspace drive, and at least one other system is within range with the current fuel supply.

==== <code>conditionFriendlyStationExists</code> ====
function '''conditionFriendlyStationExists'''() : Boolean
There is at least one friendly station in the system.

==== <code>conditionFriendlyStationNearby</code> ====
function '''conditionFriendlyStationNearby'''() : Boolean
There is at least one friendly station within scanner range

==== <code>conditionGroupIsSeparated</code> ====
function '''conditionGroupIsSeparated'''() : Boolean
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)

==== <code>conditionHasSelectedPlanet</code> ====
function '''conditionHasSelectedPlanet'''() : Boolean
The ship has a valid planet in the "oolite_selectedPlanet" parameter.

==== <code>conditionHasSelectedStation</code> ====
function '''conditionHasSelectedStation'''() : Boolean
The ship has a valid station in the "oolite_selectedStation" parameter.

==== <code>conditionHomeStationExists</code> ====
function '''conditionHomeStationExists'''() : Boolean
The ship's home station still exists

==== <code>conditionHomeStationNearby</code> ====
function '''conditionHomeStationNearby'''() : Boolean
The ship's home station is within scanner range.

==== <code>conditionHostileStationNearby</code> ====
function '''conditionHostileStationNearby'''() : Boolean
There is at least one hostile station within scanner range

==== <code>conditionInInterstellarSpace</code> ====
function '''conditionInInterstellarSpace'''() : Boolean
The ship is currently in interstellar space.

==== <code>conditionMainPlanetNearby</code> ====
function '''conditionMainPlanetNearby'''() : Boolean
The ship is within 3 radii of the surface of the main planet

==== <code>conditionNearDestination</code> ====
function '''conditionNearDestination'''() : Boolean
The ship is closer than the desired range to its destination

==== <code>conditionPlayerNearby</code> ====
function '''conditionPlayerNearby'''() : Boolean
The player's ship is within scanner range.

==== <code>conditionReadyToSunskim</code> ====
function '''conditionReadyToSunskim'''() : Boolean
The ship is close enough to the sun to scoop fuel.

==== <code>conditionSelectedStationNearby</code> ====
function '''conditionSelectedStationNearby'''() : Boolean
The ship has a selected station in the "oolite_selectedStation" parameter, and it is within scanner range.

==== <code>conditionSelectedStationNearMainPlanet</code> ====
function '''conditionSelectedStationNearMainPlanet'''() : Boolean
The ship has a selected station in the "oolite_selectedStation" parameter, and it is within 3 radii of the surface of the main planet.

==== <code>conditionStationNearby</code> ====
function '''conditionStationNearby'''() : Boolean
There is a station within scanner range.

==== <code>conditionSunskimPossible</code> ====
function '''conditionSunskimPossible'''() : Boolean
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.

==== <code>conditionWormholeNearby</code> ====
function '''conditionWormholeNearby'''() : Boolean
There is an entry wormhole within scanner range.

=== Piracy-related conditions ===

Conditions involved in piratical activities.

==== <code>conditionCargoDemandsMet</code> ====
function '''conditionCargoDemandsMet'''() : Boolean
Since this ship (or an ally) made a cargo demand, this ship has seen enough cargo dropped to meet that demand.

==== <code>conditionGroupHasEnoughLoot</code> ====
function '''conditionGroupHasEnoughLoot'''() : Boolean
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.

==== <code>conditionPiratesCanBePaidOff</code> ====
function '''conditionPiratesCanBePaidOff'''() : Boolean
Pirates have demanded that this ship dump cargo, and it currently has enough cargo on board to meet that demand.

=== Scanning conditions ===

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 <code>true</code>.

==== <code>conditionScannerContainsAssassinationTarget</code> ====
function '''conditionScannerContainsAssassinationTarget'''() : Boolean
The scan contains an assassination target (i.e. an escape capsule)

==== <code>conditionScannerContainsCleanShip</code> ====
function '''conditionScannerContainsCleanShip'''() : Boolean
The scan contains a clean ship

==== <code>conditionScannerContainsCourier</code> ====
function '''conditionScannerContainsCourier'''() : Boolean
The scan contains a courier ship

==== <code>conditionScannerContainsEscapePods</code> ====
function '''conditionScannerContainsEscapePods'''() : Boolean
The scan contains an escape pod travelling slower than this ship's maximum speed, and this ship is able to scoop cargo.

==== <code>conditionScannerContainsFineableOffender</code> ====
function '''conditionScannerContainsFineableOffender'''() : Boolean
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.

==== <code>conditionScannerContainsFugitive</code> ====
function '''conditionScannerContainsFugitive'''() : Boolean
The scan contains a fugitive ship

==== <code>conditionScannerContainsHuntableOffender</code> ====
function '''conditionScannerContainsHuntableOffender'''() : Boolean
The scan contains a piloted ship with an offender legal status not too small to bother with (varies with government).

==== <code>conditionScannerContainsSeriousOffender</code> ====
function '''conditionScannerContainsSeriousOffender'''() : Boolean
The scan contains a piloted ship with an offender legal status at or above the system threshold for fines (varies with government).

==== <code>conditionScannerContainsHunters</code> ====
function '''conditionScannerContainsHunters'''() : Boolean
The scan contains a ship with role "hunter", or a police ship, or the main station.

==== <code>conditionScannerContainsLoneVictim</code> ====
function '''conditionScannerContainsLoneVictim'''() : Boolean
The scan contains a single pirate victim and no other unallied ships.

==== <code>conditionScannerContainsMiningOpportunity</code> ====
function '''conditionScannerContainsMiningOpportunity'''() : Boolean
The scan contains a boulder (preferentially) or an asteroid, and the ship has a mining laser, a fuel scoop, and a non-full hold.

==== <code>conditionScannerContainsNonThargoid</code> ====
function '''conditionScannerContainsNonThargoid'''() : Boolean
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.

==== <code>conditionScannerContainsPirateLeader</code> ====
function '''conditionScannerContainsPirateLeader'''() : Boolean
The scan contains a pirate leader (usually a heavily-armed freighter)

==== <code>conditionScannerContainsPirateVictims</code> ====
function '''conditionScannerContainsPirateVictims'''() : Boolean
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.

==== <code>conditionScannerContainsReadyThargoidMothership</code> ====
function '''conditionScannerContainsReadyThargoidMothership'''() : Boolean
The scan contains a thargoid mothership which has the capability to control at least one more thargon.

==== <code>conditionScannerContainsRocks</code> ====
function '''conditionScannerContainsRocks'''() : Boolean
The scan contains boulders (preferentially) or asteroids.

==== <code>conditionScannerContainsSalvage</code> ====
function '''conditionScannerContainsSalvage'''() : Boolean
The scan contains cargo which could in theory be scooped.

==== <code>conditionScannerContainsSalvageForGroup</code> ====
function '''conditionScannerContainsSalvageForGroup'''() : Boolean
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..

==== <code>conditionScannerContainsSalvageForMe</code> ====
function '''conditionScannerContainsSalvageForMe'''() : Boolean
The scan contains cargo which can be scooped by this ship (travelling slowly enough, and this ship has scoops and space)

==== <code>conditionScannerContainsShipNeedingEscort</code> ====
function '''conditionScannerContainsShipNeedingEscort'''() : Boolean
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.

==== <code>conditionScannerContainsSuspiciousShip</code> ====
function '''conditionScannerContainsSuspiciousShip'''() : Boolean
The scan contains a ship with a criminal reputation (whether or not it currently carries a bounty)

==== <code>conditionScannerContainsThargoidMothership</code> ====
function '''conditionScannerContainsThargoidMothership'''() : Boolean
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.

==== <code>conditionScannerContainsUnspreadMissile</code> ====
function '''conditionScannerContainsUnspreadMissile'''() : Boolean
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.

=== State querying conditions ===

Conditions related to the state of the ship

==== <code>conditionAllEscortsInFlight</code> ====
function '''conditionAllEscortsInFlight'''() : Boolean
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>.

==== <code>conditionCanScoopCargo</code> ====
function '''conditionCanScoopCargo'''() : Boolean
The ship has a working fuel scoop and at least 1 TC of free space in its hold.

==== <code>conditionCargoIsProfitableHere</code> ====
function '''conditionCargoIsProfitableHere'''() : Boolean
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.

==== <code>conditionCoinFlip</code> ====
function '''conditionCoinFlip'''() : Boolean
Returns <code>true</code> half the time.

==== <code>conditionGroupLeaderIsStation</code> ====
function '''conditionGroupLeaderIsStation'''() : Boolean
The ship has a group leader and the group leader is a station.

==== <code>conditionHasInterceptCoordinates</code> ====
function '''conditionHasInterceptCoordinates'''() : Boolean
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.

==== <code>conditionHasMothership</code> ====
function '''conditionHasMothership'''() : Boolean
The ship has a group leader which is not itself.

==== <code>conditionHasNonThargoidTarget</code> ====
function '''conditionHasNonThargoidTarget'''() : Boolean
The ship's target is not <code>null</code> and is not a thargoid ship (by scan class).

==== <code>conditionHasReceivedDistressCall</code> ====
function '''conditionHasReceivedDistressCall'''() : Boolean
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.

==== <code>conditionHasRememberedTarget</code> ====
function '''conditionHasRememberedTarget'''() : Boolean
The ship has a remembered target. This is set by [[#behaviourFollowCurrentTarget|behaviourFollowCurrentTarget]] to allow persistent tracking of a ship.

==== <code>conditionHasTarget</code> ====
function '''conditionHasTarget'''() : Boolean
The ship's target is not <code>null</code>.

==== <code>conditionHasWaypoint</code> ====
function '''conditionHasWaypoint'''() : Boolean
The ship has a waypoint set by its [[#Waypoint_Generators|waypoint generator]].

==== <code>conditionIsActiveThargon</code> ====
function '''conditionIsActiveThargon'''() : Boolean
The ship is a thargon ("EQ_THARGON") and is active.

==== <code>conditionIsEscorting</code> ====
function '''conditionIsEscorting'''() : Boolean
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.

==== <code>conditionIsGroupLeader</code> ====
function '''conditionIsGroupLeader'''() : Boolean
The ship is in a group and is the leader of the group

==== <code>conditionMissileNeedsLaunchEvasion</code> ====
function '''conditionMissileNeedsLaunchEvasion'''() : Boolean
This function checks if the <code>oolite_flag_launchAdjustMissile</code> parameter is set to a non-<code>null</code> value, and returns <code>true</code> if so.

Missile AI scripts may find the following code useful to set this flag to avoid collisions with the launching ship.

this.shipSpawned = function()
{
/* Launch correction when fired at target in aft arc */
var s = this.ship;
if(s.target && s.target.position.subtract(s.position).direction().dot(s.vectorForward) < -0.8)
{
this.oolite_priorityai.setParameter("oolite_flag_launchAdjustMissile",true);
}
}

See also [[#configurationMissileAdjustLaunch|configurationMissileAdjustLaunch]]

==== <code>conditionMissileOutOfFuel</code> ====
function '''conditionMissileOutOfFuel'''() : Boolean
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.

==== <code>conditionPatrolIsOver</code> ====
function '''conditionPatrolIsOver'''() : Boolean
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.

From Oolite 1.81, the distance threshold can be changed from the default 200km by setting the <code>oolite_patrolLength</code> parameter.

==== <code>conditionWitchspaceEntryRequested</code> ====
function '''conditionWitchspaceEntryRequested'''() : Boolean
The ship has been requested to enter a wormhole set in the "oolite_witchspaceWormhole" parameter.

== Configuration functions ==

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.

=== Destination configurations ===

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.

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.

==== <code>configurationMissileAdjustLaunch</code> ====
function '''configurationMissileAdjustLaunch'''()
This function causes the missile to dive sharply. The intended use is in conjunction with [[#conditionMissileNeedsLaunchEvasion|conditionMissileNeedsLaunchEvasion]] to avoid collisions with the launching ship.

==== <code>configurationMissileAdjustSpread</code> ====
function '''configurationMissileAdjustSpread'''()
This function sets an intermediate destination for "smart" missiles which are adjusting their flight path to spread out a salvo's impacts on target.

==== <code>configurationSetDestinationToHomeStation</code> ====
function '''configurationSetDestinationToHomeStation'''()
Locates the home station, sets the destination to its position and the desired range to 15km.

==== <code>configurationSetDestinationToGroupLeader</code> ====
function '''configurationSetDestinationToGroupLeader'''()
Locates the group leader, sets the destination to its position and the desired range to 15km. Maximum flight speed is used.

==== <code>configurationSetDestinationToMainPlanet</code> ====
function '''configurationSetDestinationToMainPlanet'''()
Sets the destination to the main planet's position, and the desired range to 3 radii (i.e. 2 radii from the surface).

==== <code>configurationSetDestinationToMainStation</code> ====
function '''configurationSetDestinationToMainStation'''()
Sets the destination to the main station's position, and the desired range to 15km

==== <code>configurationSetDestinationToNearestHostileStation</code> ====
function '''configurationSetDestinationToNearestHostileStation'''()
Locates the nearest friendly station, sets the destination to its position and the desired range to 15km.

==== <code>configurationSetDestinationToNearestFriendlyStation</code> ====
function '''configurationSetDestinationToNearestFriendlyStation'''()
Locates the nearest friendly station, sets the destination to its position and the desired range to 15km.

==== <code>configurationSetDestinationToNearestStation</code> ====
function '''configurationSetDestinationToNearestStation'''()
Locates the nearest station, sets the destination to its position and the desired range to 15km.

==== <code>configurationSetDestinationToNearestWormhole</code> ====
function '''configurationSetDestinationToNearestWormhole'''()
Locates the nearest entry wormhole, sets the destination to its position and the desired range to zero.

==== <code>configurationSetDestinationToPirateLurk</code> ====
function '''configurationSetDestinationToPirateLurk'''()
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".

The desired range is 1km.

==== <code>configurationSetDestinationToScannedTarget</code> ====
function '''configurationSetDestinationToScannedTarget'''()
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.

==== <code>configurationSetDestinationToSelectedPlanet</code> ====
function '''configurationSetDestinationToSelectedPlanet'''()
Sets the destination to the position of the planet in the parameter "oolite_selectedPlanet", and the desired range to 100m from the surface.

==== <code>configurationSetDestinationToSelectedStation</code> ====
function '''configurationSetDestinationToSelectedStation'''()
Sets the destination to the position of the station in the parameter "oolite_selectedStation", and the desired range to 15km.

==== <code>configurationSetDestinationToSunskimEnd</code> ====
function '''configurationSetDestinationToSunskimEnd'''()
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.

Note: if this function is used above sunskimming height, it will still
move parallel to the sun's surface, but this will not be much use.

==== <code>configurationSetDestinationToSunskimStart</code> ====
function '''configurationSetDestinationToSunskimStart'''()
Sets the destination to the sun's position, and the desired range to sunskimming height.

==== <code>configurationSetDestinationToWaypoint</code> ====
function '''configurationSetDestinationToWaypoint'''()
If the parameters "oolite_waypoint" and "oolite_waypointRange" are set, use those as the destination and desired range.

==== <code>configurationSetDestinationToWitchpoint</code> ====
function '''configurationSetDestinationToWitchpoint'''()
Sets the destination to the witchpoint and the range to 10km

==== <code>configurationSetWaypoint</code> ====
function '''configurationSetWaypoint'''()
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.

=== Docking configurations ===

Each of these configurations sets the "oolite_dockingStation" parameter used by [[#behaviourDockWithStation|behaviourDockWithStation]]

==== <code>configurationSetNearbyFriendlyStationForDocking</code> ====
function '''configurationSetNearbyFriendlyStationForDocking'''()
Sets the "oolite_dockingStation" parameter to a friendly station in scanner range, if possible.

==== <code>configurationSetHomeStationForDocking</code> ====
function '''configurationSetHomeStationForDocking'''()
Sets the "oolite_dockingStation" parameter to the ship's home station.

==== <code>configurationSetSelectedStationForDocking</code> ====
function '''configurationSetHomeStationForDocking'''()
Sets the "oolite_dockingStation" parameter to the station in the parameter "oolite_selectedStation".

=== Miscellaneous configurations ===

==== <code>configurationAppointGroupLeader</code> ====
function '''configurationAppointGroupLeader'''()
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.

If the parameter "oolite_leaderRole" is set, the primary role of the new leader will be changed to that role.

==== <code>configurationEscortGroupLeader</code> ====
function '''configurationEscortGroupLeader'''()
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.

==== <code>configurationForgetCargoDemand</code> ====
function '''configurationForgetCargoDemand'''()
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.

==== <code>configurationLeaveEscortGroup</code> ====
function '''configurationLeaveEscortGroup'''()
If the ship is currently escorting another ship, leave the escort group.

==== <code>configurationLightsOff</code> ====
function '''configurationLightsOff'''()
Set the ship's flashers to the 'off' state.

==== <code>configurationLightsOn</code> ====
function '''configurationLightsOn'''()
Set the ship's flashers to the 'on' state.

==== <code>configurationSetRemoteControl</code> ====
function '''configurationSetRemoteControl'''()
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.

=== Navigation configurations ===

==== <code>configurationSelectPlanet</code> ====
function '''configurationSelectPlanet'''()
This function places a randomly selected planet or moon in the parameter "oolite_selectedPlanet"

==== <code>configurationSelectRandomTradeStation</code> ====
function '''configurationSelectRandomTradeStation'''()
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.

If the main station was not selected at the previous step, a random
friendly station will be selected (which may be the main station
anyway)

==== <code>configurationSelectShuttleDestination</code> ====
function '''configurationSelectShuttleDestination'''()
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.

If the selected entity was a planet, it will be stored in "oolite_selectedPlanet". Otherwise, it will be stored in "oolite_selectedStation".

==== <code>configurationSelectWitchspaceDestination</code> ====
function '''configurationSelectWitchspaceDestination'''()
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.

==== <code>configurationSelectWitchspaceDestinationInbound</code> ====
function '''configurationSelectWitchspaceDestinationInbound'''()
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.

==== <code>configurationSelectWitchspaceDestinationOutbound</code> ====
function '''configurationSelectWitchspaceDestinationOutbound'''()
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.

=== Station configurations ===

==== <code>configurationStationReduceAlertLevel</code> ====
function '''configurationStationReduceAlertLevel'''()
Reduce the alert level of the station by one stage if it is not already Green.

==== <code>configurationStationValidateTarget</code> ====
function '''configurationStationValidateTarget'''()
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.

=== Target acquisition configurations ===

==== <code>configurationAcquireCombatTarget</code> ====
function '''configurationAcquireCombatTarget'''()
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).

==== <code>configurationAcquireDefensiveEscortTarget</code> ====
function '''configurationAcquireDefensiveEscortTarget'''()
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.

==== <code>configurationAcquireHostileCombatTarget</code> ====
function '''configurationAcquireHostileCombatTarget'''()
As [[#configurationAcquireCombatTarget|configurationAcquireCombatTarget]] but only targets which are hostile (i.e. would be valid for [[#behaviourRepelTarget|behaviourRepelTarget]]) will be selected.

==== <code>configurationAcquireOffensiveEscortTarget</code> ====
function '''configurationAcquireOffensiveEscortTarget'''()
If this ship's group leader is attacking a target, and this ship can see that target, acquire that target. Otherwise retain current target.

==== <code>configurationAcquirePlayerAsTarget</code> ====
function '''configurationAcquirePlayerAsTarget'''()
Set this ship's target to the player.

==== <code>configurationAcquireScannedTarget</code> ====
function '''configurationAcquireScannedTarget'''()
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.

==== <code>configurationCheckScanner</code> ====
function '''configurationCheckScanner'''()
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.

If the scanner is particularly full, the list will not contain all visible objects. The current scan limit is 16.

== Response definition functions and components ==

=== Response definition functions ===

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.

They are generally used in behaviour functions to set up common responses.
var handlers = {}; // new handler object
this.responsesAddStandard(handlers); // add standard response set
// add a handler for this behaviour
handlers.shipEnteredStationAegis = function(station)
{
this.ship.beaconCode = null; // stop transmitting
}
this.applyHandlers(handlers);

==== <code>responsesAddDocking</code> ====
function '''responsesAddDocking'''(handlers : Object)
Provides some additional event handlers for use when docking with a station.

==== <code>responsesAddEscort</code> ====
function '''responsesAddEscort'''(handlers : Object)
Provides some additional event handlers for use when escorting a ship, and changes the response to in-group help requests.

==== <code>responsesAddMissile</code> ====
function '''responsesAddMissile'''(handlers : Object)
A standard set of event handlers for missiles, which should be used instead of <code>responsesAddStandard</code>.

A number of script info keys are used to modify the responses.
* 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.
* 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.
* 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.

==== <code>responsesAddScooping</code> ====
function '''responsesAddScooping'''(handlers : Object)
Provides some additional event handlers for use when scooping fuel.

==== <code>responsesAddStandard</code> ====
function '''responsesAddStandard'''(handlers : Object)
Sets up standard event handlers to detect and respond to attacks, and to manage other common events. Certain parameter flags are used:
* oolite_flag_allowPlanetaryLanding: if <code>true</code>, the ship will land on a planet if it receives the <code>approachingPlanetSurface</code> event. Otherwise, it will immediately reconsider its behaviour.
* oolite_flag_listenForDistressCall: if <code>true</code>, the ship will set the "oolite_distressAggressor", "oolite_distressSender" and "oolite_distressTimestamp" parameters if it receives a distress call.
* oolite_flag_markOffenders: if <code>true</code>, the ship will apply a small bounty increase to ships it sees committing crimes.
* oolite_flag_sendsDistressCalls: if <code>true</code>, the ship will send distress calls when attacked.
* oolite_flag_watchForCargo: if <code>true</code>, the ship will increment the "oolite_cargoDropped" parameter if cargo is dumped nearby.

If multiple standard responses are being applied, this one should be the first one applied.

==== <code>responsesAddStation</code> ====
function '''responsesAddStation'''(handlers : Object)
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>.

=== Response definition components ===

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.
var handlers = {};
handlers.approachingPlanetSurface = this.responseComponent_standard_approachingPlanetSurface;
// .. etc ..
this.applyHandlers(handlers);

==== Standard components ====
Standard event handlers for normal ships.
responseComponent_standard_approachingPlanetSurface
responseComponent_standard_cargoDumpedNearby
responseComponent_standard_cascadeWeaponDetected
responseComponent_standard_commsMessageReceived
responseComponent_standard_distressMessageReceived
responseComponent_standard_escortAccepted
responseComponent_standard_helpRequestReceived
responseComponent_standard_offenceCommittedNearby
responseComponent_standard_playerWillEnterWitchspace
responseComponent_standard_shipAcceptedEscort
responseComponent_standard_shipAchievedDesiredRange
responseComponent_standard_shipAttackedOther
responseComponent_standard_shipAttackedWithMissile
responseComponent_standard_shipAttackerDistracted
responseComponent_standard_shipBeingAttacked
responseComponent_standard_shipBeingAttackedUnsuccessfully
responseComponent_standard_shipFiredMissile
responseComponent_standard_shipKilledOther
responseComponent_standard_shipLaunchedEscapePod
responseComponent_standard_shipLaunchedFromStation
responseComponent_standard_shipScoopedOther
responseComponent_standard_shipTargetLost
responseComponent_standard_shipWillEnterWormhole
responseComponent_standard_shipWitchspaceBlocked
responseComponent_standard_wormholeSuggested

==== Missile components ====
Standard event handlers for missiles.
responseComponent_missile_commsMessageReceived
responseComponent_missile_shipHitByECM
responseComponent_missile_shipTargetCloaked
responseComponent_missile_shipTargetLost
responseComponent_missile_shipAchievedDesiredRange

==== Station components ====
Standard event handlers for stations.
responseComponent_station_commsMessageReceived
responseComponent_station_cascadeWeaponDetected
responseComponent_station_shipAttackedWithMissile
responseComponent_station_shipBeingAttacked
responseComponent_station_shipAttackedOther
responseComponent_station_shipFiredMissile
responseComponent_station_shipKilledOther
responseComponent_station_shipTargetLost
responseComponent_station_helpRequestReceived
responseComponent_station_distressMessageReceived
responseComponent_station_offenceCommittedNearby

==== Docking components ====
Alternative event handlers for docking ships.
responseComponent_docking_shipAchievedDesiredRange
responseComponent_docking_stationWithdrewDockingClearance
responseComponent_docking_shipAIFrustrated

==== Escort components ====
Alternative event handlers for escorts.
responseComponent_escort_escortDock
responseComponent_escort_helpRequestReceived

==== Expect-witchspace components ====
Alternative event handlers for ships expecting that their target might enter witchspace to escape
responseComponent_expectWitchspace_shipTargetLost

==== Scooping components ====
Alternative event handlers for ships scooping fuel.
responseComponent_scooping_shipAchievedDesiredRange
responseComponent_scooping_shipScoopedFuel

==== Track-player components ====
Alternative event handlers for ships following the player.
responseComponent_trackPlayer_playerWillEnterWitchspace

== Template functions ==

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.
{
condition: ai.conditionInCombat,
falsebranch: ai.templateReturnToBase()
}
or
priorities.concat(ai.templateReturnToBase());

==== templateLeadHuntingMission ====
function '''templateLeadHuntingMission'''() : Array
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.

==== templateLeadPirateMission ====
function '''templateLeadPirateMission'''() : Array
Return the priorities for selecting targets to rob if any are about, or moving to a suitable lurk position otherwise.

==== templateReturnToBase ====
function '''templateReturnToBase'''() : Array
Return the priorities for travelling to and docking with a suitable station.

==== templateReturnToBaseOrPlanet ====
function '''templateReturnToBaseOrPlanet'''() : Array
Return the priorities for travelling to and docking with a suitable station, or landing on a planet if no suitable stations are found.

==== templateWitchspaceJumpAnywhere ====
function '''templateWitchspaceJumpAnywhere'''() : Array
Returns priorities for getting the ship out of the current system somehow - either by jumping out, or by finding a wormhole to hitchhike.

==== templateWitchspaceJumpInbound ====
function '''templateWitchspaceJumpInbound'''() : Array
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.

==== templateWitchspaceJumpOutbound ====
function '''templateWitchspaceJumpOutbound'''() : Array
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.

== Utility functions ==

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.

==== <code>allied</code> ====
function '''allied'''(ship1, ship2) : Boolean
Returns <code>true</code> if the two ships are considered allied, <code>false</code> otherwise. Ships are considered allied if they are in the same group, or if they are escorts of ships in the same group.

==== <code>broadcastDistressMessage</code> ====
function '''broadcastDistressMessage'''()
Broadcasts a distress message, but with a delay to ensure that [[Oolite_JavaScript_Reference:_Ship#broadcastDistressMessage|ship.broadcastDistressMessage()]] is not called too often.

==== <code>checkScannerWithPredicate</code> ====
function '''checkScannerWithPredicate'''(function) : Boolean
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.

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

==== <code>cruiseSpeed</code> ====
function '''cruiseSpeed'''() : Number
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.

==== <code>distance</code> ====
function '''distance'''(position : [[Oolite_JavaScript_Reference:_Vector3D#Vector_Expressions|vectorExpression]])
Returns the distance to the given coordinates. This is more efficient than calling <code>this.ship.position.distanceTo(position)</code>.

==== <code>entityCommsParams</code> ====
function '''entityCommsParams'''(entity : Entity) : Object
Returns an object of communications parameters relating to the given entity. Used internally by [[#communicate|communicate()]] but may be of use elsewhere.

==== <code>fineThreshold</code> ====
function '''fineThreshold'''() : Number
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.

==== <code>friendlyStation</code> ====
function '''friendlyStation'''(station) : Boolean
Returns <code>true</code> if the station is friendly to the current ship, <code>false</code> 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.

==== <code>homeStation</code> ====
function '''homeStation'''() : Boolean
Returns the home station of this ship. If the ship has an owner, and
the owner is a station, then that is the home station. Otherwise, the
first station in the ship's group is returned.

If no home station can be found, returns <code>null</code>.

==== <code>ignorePlayerFriendlyFire</code> ====
function '''ignorePlayerFriendlyFire'''() : Boolean
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.

==== <code>isAggressive</code> ====
function '''isAggressive'''() : Boolean
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)

==== <code>isEscaping</code> ====
function '''isEscaping'''() : Boolean
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.

==== <code>isFighting</code> ====
function '''isFighting'''() : Boolean
Returns <code>true</code> if the ship is in combat (including fleeing). Similar to <code>ship.hasHostileTarget</code> but works for stations as well.

==== <code>noteDistraction</code> ====
function '''noteDistraction'''(whom : Entity)
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.

==== <code>oddsAssessment</code> ====
function '''oddsAssessment'''() : Number
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.

==== <code>playerRoleAssessment</code> ====
function '''playerRoleAssessment'''() : String
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.

==== <code>respondToThargoids</code> ====
function '''respondToThargoids'''(whom : Ship, passon : Boolean) : Boolean
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.

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.

==== <code>setWitchspaceRouteTo</code> ====
function '''setWitchspaceRouteTo'''(dest : Number)
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.

==== <code>shipHasRiskyContracts</code> ====
function '''shipHasRiskyContracts'''(ship : Ship) : Boolean
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.

==== <code>shipInRoleCategory</code> ====
function '''shipInRoleCategory'''(ship : Ship, category : String) : Boolean
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.

==== <code>stationAllegiance</code> ====
function '''stationAllegiance'''(station : Station) : String
Returns <code>station.allegiance</code> for the given station, but if this is <code>null</code> (as it will be for pre-1.79 stations), first sets it using a heuristic calculation.

==== <code>threatAssessment</code> ====
function '''threatAssessment'''(ship : Ship, full : Boolean) : Number
This is a wrapper around <code>_threatAssessment</code> (intentionally not documented) 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.

== Waypoint Generators ==

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.

In general, you should only call a waypoint generator if a waypoint is not already set.

==== <code>waypointsSpacelanePatrol</code> ====
function '''waypointsSpacelanePatrol'''()
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.

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.

==== <code>waypointsStationPatrol</code> ====
function '''waypointsStationPatrol'''()
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.

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.

==== <code>waypointsWitchpointPatrol</code> ====
function '''waypointsWitchpointPatrol'''()

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.

== Global Configuration ==
All PriorityAIControllers share a single communications message library. This library may be edited using functions in the priority AI worldscript

=== Usage ===

When a key is asked for, the communications library will be checked in the following order:
# for a key with the specified role and personality
# if the role does not start with "_", a key with the specified personality and the role "generic"
# if the personality does not start with "_", a key with the specified role and the personality "generic"
# if neither role nor personality start with "_", a key with "generic" role and personality.
In general, setting keys for the generic role (and especially with a generic personality as well) should be used with caution.

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.

==== Standard Communications Keys ====

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

===== oolite_agreeingToDumpCargo =====
Parameter: "oolite_demandSize" (size of demand in TC)
Priority: 1
Used when a ship dumps cargo to satisfy a pirate demand

===== oolite_attackLowEnergy =====
Parameter: Ship,
Priority: 2
Used when requesting help as under attack and close to death

===== oolite_beginningAssassination =====
Parameter: Ship, plus "oolite_entityContracts" parameter
Priority: 3
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)

===== oolite_beginningAttack =====
Parameter: Ship
Priority: 3
Used when commencing an attack on the Ship defined in the parameter.

===== oolite_beginningAttackInanimate =====
Parameter: Ship
Priority: 3
Used when commencing an attack on the Ship (expected to be an uncrewed object like an asteroid, cargo pod, etc.) defined in the parameter.

===== oolite_beginningAttackThargoid =====
Parameter: Ship
Priority: 3
Used when commencing an attack on the Ship (expected to be a Thargoid ship) defined in the parameter.

===== oolite_beginningFight =====
Parameter: Ship
Priority: 3
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)

===== oolite_continueFleeing =====
Parameter: Ship
Priority: 4
Used when the ship has been unable to reach safety from its attacker.

===== oolite_continuingAttack =====
Parameter: Ship
Priority: 4
Used when continuing an attack on the Ship defined in the parameter (the low priority means this is relatively rarely used, of course)

===== oolite_continuingAttackInanimate =====
Parameter: Ship
Priority: 4
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)

===== oolite_continuingAttackThargoid =====
Parameter: Ship
Priority: 4
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)

===== oolite_distressResponseAggressor =====
Parameter: Ship
Priority: 2
Used to threaten the ship a distress call has been sent about.

===== oolite_distressResponseSender =====
Parameter: Ship
Priority: 2 or 3
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.

===== oolite_dockingWait =====
Parameter: none
Priority: 4
Used when a ship is waiting in a docking queue.

===== oolite_eject =====
Parameter: none
Priority: 1
Used when a ship launches an escape pod (the communication comes from the ship, not the pod, as the pod is being launched)

===== oolite_engageWitchspaceDrive =====
Parameter: none
Priority: 4
Used when a lone ship is beginning its witchspace entry sequence, and is expected to enter witchspace in around 15 seconds.

===== oolite_engageWitchspaceDriveFlee =====
Parameter: none
Priority: 2
Used when a ship is preparing to escape from a fight by making a witchspace jump

===== oolite_engageWitchspaceDriveGroup =====
Parameter: none
Priority: 4
Used when a grouped ship is beginning its witchspace entry sequence, and is expected to enter witchspace in around 15 seconds.

===== oolite_escortAccepted =====
Parameter: Ship
Priority: 2
Used when a ship accepts a new escort. The new escort will be passed as the parameter.

===== oolite_escortFormation =====
Parameter: Ship
Priority: 4
Used when a ship is entering or maintaining escort formation. The mothership will be passed as the parameter.

===== oolite_escortMotherAccepted =====
Parameter: Ship
Priority: 2
Used when a ship is accepted as a new escort. The ship being escorted will be passed as the parameter.

===== oolite_firedMissile =====
Parameter: Ship
Priority: 4
Used when firing a missile. The target of the missile will be passed as the parameter.

===== oolite_friendlyFire =====
Parameter: Ship
Priority: 2, 3 or 4 depending on circumstances
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.

===== oolite_groupIsOutnumbered =====
Parameter: none
Priority: 2 if group leader, 4 otherwise
Used when a ship realises it is in a fight with a group which seriously outclasses it, and therefore should flee.

===== oolite_hitTarget =====
Parameter: Ship
Priority: 4
Used when the ship hits its target. The target is passed as the parameter.

===== oolite_incomingMissile =====
Parameter: Ship
Priority: 3
Used when the ship has had a missile launched at it and is unable to use ECM. The missile is passed as the parameter.

===== oolite_killedAlly =====
Parameter: Ship
Priority: 3
Used when the ship destroys an allied ship. The target is passed as the parameter.

===== oolite_killedTarget =====
Parameter: Ship
Priority: 2 (3 for stations)
Used when the ship destroys its current target. The target is passed as the parameter.

===== oolite_killedNonTarget =====
Parameter: Ship
Priority: 3
Used when the ship destroys something other than its current target. The target is passed as the parameter.

===== oolite_killedUncrewedTarget =====
Parameter: Ship
Priority: 3 (4 for stations)
Used when the ship destroys an uncrewed object which is its current target. The target is passed as the parameter.

===== oolite_killedUncrewedNonTarget =====
Parameter: Ship
Priority: 3 (4 for stations)
Used when the ship destroys an uncrewed object other than its current target. The target is passed as the parameter.

===== oolite_landingOnPlanet =====
Parameter: none
Priority: 4
Used when beginning final landing approach to a planet.

===== oolite_launchDefenseShips, oolite_launchMiner, oolite_launchPatrol, oolite_launchSalvager =====
Parameter: Ship
Priority: 3
Used when a station launches a ship of a particular type. The parameter is the station's current target.

===== oolite_leaveVicinity =====
Parameter: Ship
Priority: 3
Used when a ship is executing [[#behaviourLeaveVicinityOfDestination|behaviourLeaveVicinityOfDestination]]. The parameter is the current target.

===== oolite_makeDistressCall =====
Parameter: Ship
Priority: 2
Used as the message when a distress call is sent. The parameter is the ship's primary aggressor.

===== oolite_makePirateDemand =====
Parameter: Ship and "oolite_demandSize"
Priority: 1
Used when making a piracy demand on a ship. The Ship parameters are from the ship being robbed.

===== oolite_markForFines =====
Parameter: Ship
Priority: 1
Used when a police ship is marking another ship for fines on docking. The parameter is the ship being marked.

===== oolite_mining =====
Parameter: none
Priority: 4
Used when carrying out mining activity

===== oolite_newAssailiant =====
Parameter: Ship
Priority: 3
Used when the ship is attacked by someone not previously considered hostile. The attacker is the parameter.

===== oolite_offenceDetected =====
Parameter: Ship
Priority: 3 if this increases the aggressor's bounty, 4 otherwise
Used when a police ship detects illegal hostilities. The parameter is the aggressor.

===== oolite_patrolReportIn =====
Parameter: Ship
Priority: 4
Used when a station patrol ship reaches a waypoint. The parameter is its parent station.

===== oolite_quiriumCascade =====
Parameter: none
Priority: 3
Used when a quirium cascade or an imminent cascade is detected.

===== oolite_scoopedCargo =====
Parameter: "oolite_goodsDescription" is a description of the cargo commodity
Priority: 4
Used when this ship scoops cargo.

===== oolite_selectedStation =====
Parameter: Ship
Priority: 4
Used when a ship selects a station to navigate to (e.g. traders, shuttles). The parameter is the selected station.

===== oolite_selectedWitchspaceDestination =====
Parameter: "oolite_witchspaceDestination" is the name of the destination system
Priority: 4
Used when a ship selects its witchspace destination.

===== oolite_startFleeing =====
Parameter: Ship
Priority: 3
Used when a ship begins fleeing combat, with the parameter being the ship's current target.

===== oolite_startHelping =====
Parameter: Ship
Priority: 4
Used when a ship responds to a request for help from another grouped ship by changing its target. The parameter is the new target.

===== oolite_surrender =====
Parameter: none
Priority: 3
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)

===== oolite_thanksForHelp =====
Parameter: Ship
Priority: 1 if thanking the player, 3 otherwise
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.

===== oolite_thargoidAttack =====
Parameter: Ship
Priority: 2
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.

===== oolite_waypointReached =====
Parameter: none
Priority: 3
This message is sent when a ship reaches a waypoint set with the waypoint generator function.

===== oolite_witchspaceBlocked =====
Parameter: Ship
Priority: 3
This message is sent when a large nearby mass (usually a station or asteroid) prevents witchspace entry. The parameter is the blocking mass.

==== Standard Communications Roles ====

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.

Note that OXP AIs might not specify the same fallback roles. OXP AIs wishing to can use code like

if (worldScripts["oolite-libPriorityAI"]._getCommunicationPersonalities("hermit").length > 0)
{
ai.setCommunicationsRole("hermit");
}
else
{
ai.setCommunicationsRole("station");
}

* '''assassin''' - assassins
* '''defenseShip''' - defense ships
* '''escapepod''' - escape pods
* '''escort''' - escorts
* '''hermit''' - rock hermits. If no personalities are defined for this role, "station" will be used instead.
* '''hunter''' - bounty hunters
* '''pirate''' - pirates
* '''pirate-aegis-raider''' - pirates showing off by attacking the main station. If no personalities are defined for this role, "pirate" will be used instead.
* '''pirate-freighter''' - pirate freighters leading a pack. If no personalities are defined for this role, "pirate" will be used instead.
* '''pirate-interceptor''' - pirates assigned to distract police and hunters. If no personalities are defined for this role, "pirate" will be used instead.
* '''police''' - police ships
* '''scavenger''' - scavengers and miners.
* '''shuttle''' - orbital shuttles (usually unarmed)
* '''station''' - stations.
* '''trader''' - traders
* '''trader-courier''' - couriers. If no personalities are defined for this role, "trader" will be used instead.
* '''trader-opportunist''' - opportunistic traders. If no personalities are defined for this role, "trader" will be used instead.
* '''trader-smuggler''' - smugglers. If no personalities are defined for this role, "trader" will be used instead.

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.

=== Methods ===

==== _getCommunication ====
function '''_getCommunication'''(role : String, personality : String, key : String) : StringOrFunction
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.

==== _getCommunicationPersonalities ====
function '''_getCommunicationPersonalities'''(role : String) : Array
Returns the personalities which have at least one communication key defined for the given role.

==== _setCommunication ====
function '''_setCommunication'''(role : String, personality : String, key : String, value : StringOrFunction)
This function sets the communications values returned by [[#getCommunication|_getCommunication]]. The value may either be:
* a String, which will be passed to expandDescription
* a Function, which will be called with two parameters: the key, and the parameters object.

For example
worldScripts["oolite-libPriorityAI"]._setCommunication("myoxp_role","generic",
"oolite_continuingAttack","[myoxp_role_continuesAttack]");
worldScripts["oolite-libPriorityAI"]._setCommunication("myoxp_role","generic",
"oolite_continuingAttack",function(k,p) { return "Targeting the "+p.oolite_entityName+". Cover me."; });

==== _setCommunications ====
function '''_setCommunications'''(comms : Object)
This function can be used to set multiple communications keys at once. The format of the object is
comms[role][personality][key] = value;

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: World script event handlers

2022-10-29T21:48:15Z

Massively Locked: /* missionChoiceWasReset */ uniform null format, fixed js method

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

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

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

World scripts are always active.

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

=== Game State ===

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

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

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

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

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

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

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

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

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

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

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

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

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

Note that from Oolite 1.79 onwards the player is in the main station while this handler runs but may be moved to another station soon after.

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

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

=== Docking ===

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

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

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

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

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

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

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

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

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

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

The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect. The handler's argument is the station which launched the ship.

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

At this moment <code>ship.dockedStation == null</code>, <code>ship.docked == false</code>, <code>ship.status == "STATUS_IN_FLIGHT"</code>.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Witchspace Jumps ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18392 Order of JS events when galactic jumping] (2016)

=== Enter/Exit Aegis ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Combat ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Equipment and Cargo ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<code>shipyard</code> is a dictionary object containing details about the ship being purchased, with information similar to the following:
{
short_description: "Python: Plus Galactic Hyperdrive. Extra Energy Unit. Docking Computers. E.C.M. System. Forward weapon upgraded to military laser. Price 215 000 ₢.",
shipdata_key: "python-player",
id: "675b6b-c60a74",
price: 215000,
ship: {
...''[[shipdata.plist]]'' details of ship...
},
personality: 9807,
extras: ["EQ_GAL_DRIVE", "EQ_FUEL_SCOOPS", "EQ_ENERGY_UNIT", "EQ_FUEL_INJECTION", "EQ_DOCK_COMP", "EQ_ECM"]
}

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

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

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

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

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

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

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

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

=== Other ===

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

The <code>chartHighlightModeChanged</code> handler is called whenever the highlight mode of the galactic chart is changed either manually (from player input) or programmatically (by setting the mode with <code>[[Oolite JavaScript Reference: PlayerShip#chartHighlightMode|player.ship.chartHightlightMode]]</code>). The "newMode" parameter will be one of the following:
* <code>"OOLRC_MODE_SUNCOLOR"</code>
* <code>"OOLRC_MODE_ECONOMY"</code>
* <code>"OOLRC_MODE_GOVERNMENT"</code>
* <code>"OOLRC_MODE_TECHLEVEL"</code>

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

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

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

COMPASS_MODE_BASIC
COMPASS_MODE_PLANET
COMPASS_MODE_STATION
COMPASS_MODE_SUN
COMPASS_MODE_TARGET
COMPASS_MODE_BEACONS

script example

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

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

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

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

==== <code>escapePodSequenceOver</code> ====

The <code>escapePodSequenceOver</code> handler is called at the end of the escape pod sequence, after the <code>shipLaunchedEscapePod</code> event and just prior to the <code>shipWillDockWithStation</code> and <code>shipDockedWithStation</code> events.

Use this handler if you need to override the destination for the escape pod with [[Oolite_JavaScript_Reference:_Player#setEscapePodDestination|<code>player.setEscapePodDestination()</code>]].

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

==== <code>guiScreenChanged</code> ====

The <code>guiScreenChanged</code> handler is called when the <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> changes. The ''from'' parameter is the screen it is leaving and ''to'' is the screen initially being switched to. Note that the screen can have changed again in the meantime by the action of other oxps. Therefore, it is generally better to test the global <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> to see which page is really on display instead of using the ''to'' parameter. (world script only)

This handler will only fire when switched to/from any of the following:

1.76: <code>"GUI_SCREEN_MAIN"</code>, <code>"GUI_SCREEN_STATUS"</code>(F5), <code>"GUI_SCREEN_MANIFEST"</code>(F5F5), <code>"GUI_SCREEN_SYSTEM_DATA"</code>(F7), <code>"GUI_SCREEN_OPTIONS"</code>, <code>"GUI_SCREEN_EQUIP_SHIP"</code>(F3), <code>"GUI_SCREEN_SHIPYARD"</code>(F3F3), <code>"GUI_SCREEN_SHORT_RANGE_CHART"</code>(F6), <code>"GUI_SCREEN_LONG_RANGE_CHART"</code>(F6F6), <code>"GUI_SCREEN_MARKET"</code>(F8), <code>"GUI_SCREEN_CONTRACTS"</code>, <code>"GUI_SCREEN_REPORT"</code>

1.77: adds <code>"GUI_SCREEN_INTERFACES"</code>(F4) and removes <code>"GUI_SCREEN_CONTRACTS"</code>

1.81: adds <code>"GUI_SCREEN_MARKETINFO"</code>(F8F8)

this.guiScreenChanged = function(to, from)
{
// Your code here
}

==== <code>guiScreenWillChange</code> ====

The <code>guiScreenWillChange</code> handler is called when the <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> is about to change. On these screens, a script could change the content of the page to be displayed. (world script only)

This handler will only fire when switching to/from any of the following:

<code>"GUI_SCREEN_EQUIP_SHIP"</code>(F3), <code>"GUI_SCREEN_MANIFEST"</code>(F5F5), <code>"GUI_SCREEN_MARKET"</code>(F8), <code>"GUI_SCREEN_SHIPYARD"</code>(F3F3), <code>"GUI_SCREEN_SYSTEM_DATA"</code>(F7)

1.77: adds <code>"GUI_SCREEN_INTERFACES"</code>(F4), <code>"GUI_SCREEN_STATUS"</code>(F5)

1.81: adds <code>"GUI_SCREEN_MARKETINFO"</code>(F8F8)

this.guiScreenWillChange = function(to, from)
{
// Your code here
}

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

The <code>infoSystemChanged</code> handler is called when the system displayed in F7 is changed, e.g. by moving the small blue cursor along the planned route in the chart.

this.infoSystemChanged = function(to, from)
{
// Your code here
}

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

The <code>infoSystemWChange</code> handler is called just before the system displayed in F7 is updated, e.g. by moving the small blue cursor along the planned route in the chart.

this.infoSystemWillChange = function(to, from)
{
// Your code here
}

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

The <code>mfdKeyChanged</code> handler is called whenever the player changes the content of an MFD slot. The <code>activeMFD</code> parameter identifies which MFD slot is being changed, and the <code>mfdKey</code> specifies the key code now in use in this slot.

this.mfdKeyChanged = function(activeMFD : integer, mfdKey : string)
{
// Your code here
}

'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#setMultiFunctionDisplay|PlayerShip.setMultiFunctionDisplay()]]</code>

==== <code>missionChoiceWasReset</code> ====

The <code>missionChoiceWasReset</code> handler is called when the mission choice is set to <code>null</code> via script (either using the legacy script method resetMissionChice or using <code>mission.runScreen ({choices: null})</code> in javascript)

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

==== <code>missionScreenEnded</code> ====

The <code>missionScreenEnded</code> handler is called when a mission screen ends. Note that another script may have put up a new mission screen in the meantime. (world script only)

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

==== <code>missionScreenOpportunity</code> ====

The <code>missionScreenOpportunity</code> handler is called if there are no mission/report screens active and the player's ship is docked. It gets fired at game startup, upon docking and after an arrival report or previous mission screen has ended. (world script only)

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

This handler works a bit different from other handlers. It fires for every installed OXP/OXZ until one creates a mission screen during this handler, and then it stops. When the mission screen ends and there is no callback function that creates a new mission screen, the <code>missionScreenOpportunity</code> is sent again to all installed OXPs/OXZs starting with the one that created the last mission screen. All this means is that when this handler fires, it is safe to show a mission screen and no further tests are needed.

==== <code>reportScreenEnded</code> ====

The <code>reportScreenEnded</code> handler is called when the last arrival-report screen ends. This is a screen that should not be written by a missionscreen. The code should wait until this eventhandler fires. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

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

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

The <code>selectedMFDChanged</code> handler is send whenever the player selects a new MFD slot (normally using the default keypress ";"). The <code>activeMFD</code> paramater is the index of the MFD which is now active.

this.selectedMFDChanged = function(activeMFD : integer)
{
// Your code here
}

==== <code>shipCollided</code> ====

The <code>shipCollided</code> handler is send after a collision with otherShip.

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

==== <code>shipSpawned</code> ====

The <code>shipSpawned</code> handler is called after an NPC ship has been added to the system. After a witchspace jump it means that first all ships are added to the system, then all the relevant shipSpawned events are triggered. 
This handler for the worldScript is new since Oolite 1.74. After the event is sent to the shipScript, it is now also send to the worldScript with the added entity as argument.

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

==== <code>shipLaunchedEscapePod</code> ====

The <code>shipLaunchedEscapePod</code> handler is called when the player bails out. This will be followed by the <code>escapePodSequenceOver</code> event, and then a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds.

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

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

The <code>systemInformationChanged</code> handler is called when system information is modified. It is passed the galaxy and system ID which were changed, and the key and new value in the SystemInfo object.

To avoid problems with recursion, attempting to change the value of any system information property from within this handler will fail and log an error. Also note that changes which take place while Oolite is not running (from OXP planetinfo.plist files) will not cause this handler to be called when the game is reloaded.

this.systemInformationChanged = function(galaxy,system,key,newValue)
{
// Your code here
}

==== <code>viewDirectionChanged</code> ====

The <code>viewDirectionChanged</code> handler is called when the player view changes, with a string to indicate which view the player is facing. Amongst its possible values are "VIEW_FORWARD", "VIEW_AFT", "VIEW_PORT", "VIEW_STARBOARD",
"VIEW_CUSTOM",
"VIEW_GUI_DISPLAY".

this.viewDirectionChanged = function(viewString)
{
if (viewString == "VIEW_PORT")
{
// Your code here
}
}

=== System population ===

In Oolite 1.79 and later, functions are called to populate and repopulate the system. These functions do not have fixed names, as they depend on the system, but otherwise act like normal worldscript functions. [[Oolite System Populator|The populator page]] has more documentation on these functions.

=== Defunct ===

==== <code>equipmentDestroyed</code> ====
''Handler no longer exists in current stable version 1.80''

The <code>equipmentDestroyed</code> handler is called when equipment gets destroyed completely beyond repair. (in strict mode, 1.77 or earlier only) (world script only)

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

==== <code>tickle</code> (removed in 1.77) ====

The <code>tickle</code> handler is called periodically-ish, whenever the old [[property list|plist]] scripts are updated. <code>tickle()</code> is deprecated. In new code, use appropriate event handlers or [[Oolite JavaScript Reference: Timer|timers]] instead.

=== Missing Events ===

All the initially planned events have been implemented in 1.74.

If there are other events you would like to be able to respond to, please write a request [http://www.aegidian.org/bb/viewtopic.php?t=3296 on the forum].

'''See also:''' [[Oolite JavaScript Reference: Ship script event handlers|ship script event handlers]]

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: VisualEffect

2022-10-29T21:17:25Z

Massively Locked: /* scannerDisplayColor1 */ uniform null format

'''Prototype:''' <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> 

The '''<code>VisualEffect</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing a visible but non-solid object defined from [[effectdata.plist]]. It has all the properties and methods of an Entity, and several others.

== Properties ==
Unless otherwise stated {{oolite-prop-added|1.77}}

=== <code>beaconCode</code> ===
'''beaconCode''' : String (read-write)
If the effect 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>.

=== <code>beaconLabel</code> ===
{{oolite-prop-added|1.79}}
'''beaconLabel''' : String (read/write)
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.

=== <code>dataKey</code> ===
'''dataKey''' : String (read-only)
The data key from [[effectdata.plist]] used to generate this visual effect.

=== <code>hullHeatLevel</code> ===
'''hullHeatLevel''' : Float (read/write)
While visual effects do not have a temperature as such, this property is provided to allow easy compatibility with the default Oolite shader for ships.

=== <code>isBreakPattern</code> ===
'''isBreakPattern''' : Boolean (read/write)
If this is <code>true</code>, the VisualEffect object will remain visible while break patterns on docking, launching or witchspace are being displayed (or not displayed). Normally all objects other than the break pattern itself are hidden.

=== <code>scaleX</code>, <code>scaleY</code>, <code>scaleZ</code> ===
'''scaleX''' : positive Float (read/write)
'''scaleY''' : positive Float (read/write)
'''scaleZ''' : positive Float (read/write)

Adjust the apparent size of the visual effect along each of its main axes. Subentity visual effects will be repositioned and rescaled accordingly. Subentity flashers will be repositioned and resized to keep a roughly proportionate volume, but not rescaled (as flashers are always spherical).

effect.scaleX = effect.scaleY = effect.scaleZ = newsize;
is equivalent to
effect.scale(newsize);
if you need to rescale the effect uniformly

=== <code>scannerDisplayColor1</code> ===
'''scannerDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
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 [[effectdata.plist]].

If both this and <code>scannerDisplayColor2</code> are set to <code>null</code>, and no value is set for either in [[effectdata.plist]] then the effect will not appear on scanners.

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

=== <code>scannerDisplayColor2</code> ===
'''scannerDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
The second scanner colour. If both <code>scannerDisplayColor1</code> and <code>scannerDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.

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

=== <code>script</code> ===
'''script''' : [[Oolite JavaScript Reference: Script|Script]] (read-only)
The effect’s script. See the "Effect Scripts" section below for more details.

=== <code>scriptInfo</code> ===
'''scriptInfo''' : Object (read-only)
The contents of the <code>script_info</code> key in the effect’s ''[[effectdata.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. 
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).

=== <code>shader*</code> ===
'''shaderFloat1''' : Number (read/write)
'''shaderFloat2''' : Number (read/write)
'''shaderInt1''' : Number (read/write)
'''shaderInt2''' : Number (read/write)
'''shaderVector1''' : Vector (read/write)
'''shaderVector2''' : Vector (read/write)
Since visual effects have very few intrinsic properties, some arbitrary parameters which may be bound as shader uniforms are provided.

=== <code>subEntities</code> ===
'''subEntities''' : Array (read-only)
A list of those subentities which are also visual effects

== Methods ==
{{oolite-method-added|1.77}}

=== <code>getMaterials</code> ===
function '''getMaterials'''() : Object
getMaterials() returns the effect's current materials dictionary, or if none present an empty dictionary.

'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code>

=== <code>getShaders</code> ===
function '''getShaders'''() : Object
getShaders() returns the effect's current shaders dictionary, or if none present an empty dictionary.

'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code>

=== <code>remove</code> ===
function '''remove'''()
Immediately removes the effect from the universe.

=== <code>restoreSubEntities</code> ===
function '''restoreSubEntities'''()
Restores all missing subentities. Returns the number of subentities restored.

=== <code>scale</code> ===
function '''scale'''(factor : Number)
Multiplies the size of the visual effect by <code>factor</code>. Subentities will be rescaled as well, and moved further from the centre of the effect as appropriate. An error will occur if <code>factor</code> is less than or equal to zero.

Note that this method resizes relative to the objects ''original'' size, not its current size. <code>scale(1)</code> will therefore always return to the original size.

=== <code>setMaterials</code> ===
function '''setMaterials'''(materialDictionary : Object [, shaderDictionary : Object]) : Boolean
Set the materials of the effect’s model. This works exactly like the <code>materials</code> dictionary in [[effectdata.plist]]. The optional <code>shaderDictionary</code> argument overrides <code>materialDictionary</code> if shaders are active.

'''Example:'''
effect.setMaterials({"my_effect_diffuse.png": { diffuse_map: "my_effect_damaged_diffuse.png" }});

'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code>

=== <code>setShaders</code> ===
function '''setShaders'''(shaderDictionary : Object) : Boolean
Set the shader materials of the effect’s model. Equivalent to <code>[[#setMaterials|setMaterials()]]</code> with the <code>materialDictionary</code> value set to the effect’s current material dictionary.

'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code>

== Effect Scripts ==

Visual Effects may have an effect script attached to them. These work in a similar way to ship scripts, but define different handlers and properties. As with ship scripts, there will be a separate independent copy of the script for each visual effect.

Effects scripts have one property, <code>this.visualEffect</code>, which is a reference to the visual effect this is a script for. They have the following event handlers.

=== <code>effectRemoved</code> ===

The <code>effectRemoved</code> handler is called when the effect is removed from the universe, either by the [[#remove|remove]] method or automatically when the player leaves the system. This is a good place to clean up any frame callbacks or timers associated with this effect.

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

=== <code>effectSpawned</code> ===

The <code>effectSpawned</code> handler is called on the first update after the effect is added to the universe.

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

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: SystemInfo

2022-10-29T21:06:49Z

Massively Locked: /* routeToSystem */ uniform null format

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

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

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

== Properties ==
=== <code>coordinates</code> ===
'''coordinates''' : {{oojsclass|Vector3D}} (read-only)
The coordinates of the system in light years. e.g. for Lave: <code>(8, 34.6, 0)</code>. The z component is always zero.

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.

'''Example:'''
System.infoForSystem(galaxyNumber, 7).coordinates
returns the coordinates of the system with an ID number of 7 in the current galaxy. In the first galaxy that would be the coordinates for Lave: <code>(8, 34.6, 0)</code>.

=== <code>galaxyID</code> ===
'''galaxyID''' : Number (read-only nonnegative integer)
The ID number of the galaxy.

=== <code>internalCoordinates</code> ===
'''internalCoordinates''' : {{oojsclass|Vector3D}} (read-only)
'''Discouraged in favour of <code>[[#coordinates|coordinates]]</code>.''' 
The coordinate of the system in the internal coordinate system.

=== <code>systemID</code> ===
'''systemID''' : Number (read-only nonnegative integer)
The ID number of the system.

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

'''Example:'''
<code>system.info.description = "This is a dull planet."</code>
sets the description of the current planet to “This is a dull planet.”

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

== Methods ==
=== <code>distanceToSystem</code> ===
function '''distanceToSystem'''(system : SystemInfo) : Number
Returns the distance in light years to another <code>SystemInfo</code>.

'''Example:'''
System.infoForSystem(galaxyNumber, 7).distanceToSystem(System.infoForSystem(galaxyNumber, 8))
If galaxyNumber is 0, this returns 92.8.

=== <code>routeToSystem</code> ===
function '''routeToSystem'''(system : SystemInfo [, "OPTIMIZED_BY_JUMPS" | "OPTIMIZED_BY_TIME"] ) : Object
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.

'''Example:'''
var myRoute = System.infoForSystem(galaxyNumber, 7).routeToSystem(System.infoForSystem(galaxyNumber, 8))
myRoute.route
myRoute.distance
myRoute.time
returns:
7,129,227,73,89,222,29,42,131,62,150,36,28,16,185,86,138,51,8 (the route)
96.40 (distance of added jumps)
530.40 (travelled time)

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

=== <code>samplePrice</code> ===
{{oolite-method-added|1.81}}
function '''samplePrice'''(commodity : String) : Array
Return a sample main market price in decicredits for the commodity with that key in this system. As this requires reading system information, it will only work for systems in the current galaxy. There is of course no guarantee that the price returned by this method will be anywhere near the actual price when the system is next entered.

=== <code>setProperty</code> ===
{{oolite-method-added|1.81}}
function '''setProperty'''(layer: Number, key : String, value: String [, manifest: String])

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

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

=== <code>systemsInRange</code> ===
function '''systemsInRange'''([range : Number]) : Array
Returns an array of <code>SystemInfo</code>s in range (default: 7) from the given system.

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

'''Example:'''
system.info.systemsInRange(5);

== Static methods ==
=== <code>filteredSystems</code> ===
function '''filteredSystems'''(this : Object, predicate : Function) : Array of SystemInfo
A list of the <code>SystemInfo</code>s for which <code>predicate</code> returns <code>true</code>.

'''Example:'''
// This is the actual implementation of <code>[[#systemsInRange|systemsInRange()]]</code>.
SystemInfo.prototype.systemsInRange = function systemsInRange(range)
{
if (range === undefined)
{
range = 7;
}

return SystemInfo.filteredSystems(this, function(other)
{
return (other.systemID !== this.systemID) && (this.distanceToSystem(other) <= range);
});
}

=== <code>setInterstellarProperty</code> ===
{{oolite-method-added|1.81}}
function '''setInterstellarProperty'''(galaxy : Number, fromsystem : Number, tosystem : Number, layer: Number, key : String, value: String, [, manifest: String])

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

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

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: System

2022-10-29T21:02:10Z

Massively Locked: /* setPopulator */ uniform null format

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

The '''<code>System</code>''' class represents the current star system. There is always one <code>System</code> object, available through the global property <code>system</code>.

Attempts to change system properties are ignored in interstellar space (i.e., the place you end up in after a witchspace malfunction).

== Properties ==
=== <code>allShips</code> ===
'''allShips''' : Array (read-only)
A list of the ships in the system.

'''See Also:''' <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>, <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>

=== <code>allVisualEffects</code> ===
{{oolite-prop-added|1.77}}
'''allVisualEffects''' : Array (read-only)
A list of the [[Oolite_JavaScript_Reference:_VisualEffect|visual effects]] in the system.

=== <code>ambientLevel</code> ===
{{oolite-prop-added|1.81}}
'''ambientLevel''' : float (read/write)
Adjusts the level of ambient light in the current system. Values should typically be between 0.0 and 1.0 (1.0 is the default) but can be higher for a flat lit, cartoon-like effect. This is will override the "ambient_level" setting defined in [[Planetinfo.plist]]. The change is not permanent and will be reset when the system is reloaded.

=== <code>breakPattern</code> ===
{{oolite-prop-added|1.77}}
'''breakPattern''' : Boolean (read/write)
If <code>true</code> (the default state set on entry to a new system), the break pattern will be shown to the player as they exit witchspace. While this property may be set from places other than the <code>shipWillExitWitchspace</code> world script event, it is pointless to do so.

Unlike all other system properties, this one may be changed on entry to interstellar space.

=== <code>description</code> ===
'''description''' : String (read/write)
The description of the current system, as seen on the planet info screen.

=== <code>economy</code> ===
'''economy''' : Number (integer, read/write)
The type of economy in the current system, ranging from 0 (Rich Industrial) to 7 (Poor Agricultural).

'''See Also:''' <code>[[#economyDescription|economyDescription]]</code>

=== <code>economyDescription</code> ===
'''economyDescription''' : String (read-only)
A localized description of the economy type, for example, <code>"Mostly Industrial"</code>. Since this string is localized, it should only be used for display purposes.

'''See Also:''' <code>[[#economy|economy]]</code>

=== <code>government</code> ===
'''government''' : Number (read/write, integer)
The type of government in the current system, ranging from 0 (Anarchy) to 7 (Corporate State).

'''See Also:''' <code>[[#governmentDescription|governmentDescription]]</code>

=== <code>governmentDescription</code> ===
'''governmentDescription''' : String (read-only)
A localized description of the government type, for example, <code>"Democracy"</code>. Since this string is localized, it should only be used for display purposes.

'''See Also:''' <code>[[#government|government]]</code>

=== <code>ID</code> ===
'''ID''' : Number (integer, read-only)
A number identifying the system. 0 to 255, or -1 for interstellar space.

=== <code>info</code> ===
'''info''' : [[Oolite JavaScript Reference: SystemInfo|SystemInfo]] (read/write)
Allows access to system properties, using the same keys as [[planetinfo.plist]].

'''Example:'''
system.info.description = "This is a dull planet.";

=== <code>inhabitantsDescription</code> ===
'''inhabitantsDescription''' : String (read/write)
The description of the inhabitants of the current system, such as <code>"Slimy Blue Frogs"</code>.

=== <code>isInterstellarSpace</code> ===
'''isInterstellarSpace''' : Boolean (read-only)
<code>true</code> if the current system is in interstellar space, <code>false</code> otherwise.

=== <code>mainPlanet</code> ===
'''mainPlanet''' : {{oojsclass|Planet}} (read-only)
The system’s main planet, or <code>null</code> if there is none.

'''See also''': <code>[[Oolite JavaScript Reference: Planet#isMainPlanet|planet.isMainPlanet]]</code>

=== <code>mainStation</code> ===
'''mainStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only)
The system’s main station or <code>null</code> if there is none.

'''See also''': <code>[[Oolite JavaScript Reference: Station#isMainStation|station.isMainStation]]</code>

=== <code>name</code> ===
'''name''' : String (read/write)
The name of the system.

=== <code>planets</code> ===
'''planets''' : Array (read-only)
A list of the planets in the system.

=== <code>population</code> ===
'''population''' : Number (integer, read/write)
The population of the current system.

=== <code>populatorSettings</code> ===
{{oolite-prop-added|1.79}}
'''populatorSettings''' : Dictionary (read-only)
The current [[Oolite_System_Populator|populator settings]]. This is only useful to read while the system population is being prepared. After that point, further changes are meaningless.

'''See Also:''' <code>[[#setPopulator|setPopulator]]</code>

=== <code>productivity</code> ===
'''productivity''' : Number (integer, read/write)
The productivity of the current system.

=== <code>pseudoRandom100</code> ===
'''pseudoRandom100''' : Number (integer, read-only)
A random number between 0 and 99 that is always the same for a given system. '''Important:''' this method has the undesirable side effect of resetting the system random number generator. It should only be used for backwards-compatibility. For new development, use <code>[[#scrambledPseudoRandomNumber|scrambledPseudoRandomNumber]]()</code> or <code>[[#pseudoRandomNumber|pseudoRandomNumber]]</code>.

=== <code>pseudoRandom256</code> ===
'''pseudoRandom256''' : Number (integer, read-only)
A random number between 0 and 255 that is always the same for a given system. '''Important:''' this method has the undesirable side effect of resetting the system random number generator. It should only be used for backwards-compatibility. For new development, use <code>[[#scrambledPseudoRandomNumber|scrambledPseudoRandomNumber]]()</code> or <code>[[#pseudoRandomNumber|pseudoRandomNumber]]</code>.

=== <code>pseudoRandomNumber</code> ===
'''pseudoRandomNumber''' : Number (read-only)
A random number between 0 and 1 that is always the same for a given system. In general, you should avoid using this number directly and call <code>[[#scrambledPseudoRandomNumber|scrambledPseudoRandomNumber]]()</code> instead.

=== <code>stations</code> ===
{{oolite-prop-added|1.79}}
'''stations''' : Array (read-only)
A list of the stations in the system.

=== <code>sun</code> ===
'''sun''' : [[Oolite JavaScript Reference: Sun|Sun]] (read-only)
The system’s sun, or <code>null</code> if there is none.

=== <code>techLevel</code> ===
'''techLevel''' : Number (integer, read/write)
The technology level of the current system, ranging from 0 to 15.

=== <code>wormholes</code> ===
{{oolite-prop-added|1.79}}
'''wormholes''' : Array (read-only)
A list of the [[Oolite_JavaScript_Reference:_Wormhole|wormholes]] in the system.

=== <code>waypoints</code> ===
{{oolite-prop-added|1.79}}
'''waypoints''' : Array (read-only)
A dictionary of the [[Oolite_JavaScript_Reference:_Waypoint|waypoints]] in the system by key and value.

'''See Also:''' <code>[[#setWaypoint|setWaypoint()]]</code>

== Methods ==
=== <code>addGroup</code> ===
function '''addGroup'''(role : String, count : Number [, position: {{oojsvecexpr}}] [, radius: Number]) : {{oojsclass|ShipGroup}}
Like <code>[[#addShips|addShips()]]</code>, but puts the ships in a group and returns the group.

'''See Also:''' <code>[[#addGroupToRoute|addGroupToRoute()]]</code>, <code>[[#addShips|addShips()]]</code>

=== <code>addGroupToRoute</code> ===
function '''addGroupToRoute'''(role : String, count : Number [, fraction: Number] [, route: String]) : {{oojsclass|ShipGroup}}
Like <code>[[#addShipsToRoute|addShipsToRoute()]]</code>, but puts the ships in a group and returns the group.

'''See Also:''' <code>[[#addGroup|addGroup()]]</code>, <code>[[#addShipsToRoute|addShipsToRoute()]]</code>

=== <code>addMoon</code> ===
function '''addMoon'''(planetInfoKey : String) : {{oojsclass|Planet}}
Adds a moon to the system, using the specified entry in ''[[planetinfo.plist]]''. A moon is the same as a planet, except that it has no atmosphere.

'''See Also:''' <code>[[#addPlanet|addPlanet()]]</code>

=== <code>addPlanet</code> ===
function '''addPlanet'''(planetInfoKey : String) : {{oojsclass|Planet}}
Adds a planet to the system, using the specified entry in ''[[planetinfo.plist]]''.

'''See Also:''' <code>[[#addMoon|addMoon()]]</code>

=== <code>addShips</code> ===
function '''addShips'''(role : String, count : Number [, position: {{oojsvecexpr}}] [, radius: Number]) : Array
Adds ships to the system and returns the added ships in an array. Position is in absolute coordinates. When no position is given, the witchpoint is assumed. When no radius is given, the maximum scanner range is used. Ships added in range of the witchpoint automatically create a witchpoint entry cloud.

When you want to use coordinates from the legacy "pwp" system, you can use the [[Oolite_JavaScript_Reference:_Vector3D#fromCoordinateSystem|fromCoordinateSystem]] method to convert legacy type coordinates to absolute coordinates.

If you wish to add ships of a specific shipdata key, pass the key as the "role" parameter, enclosed in square brackets.

'''See Also:''' <code>[[#addGroup|addGroup()]]</code>, <code>[[#addShipsToRoute|addShipsToRoute()]]</code>

=== <code>addShipsToRoute</code> ===
function '''addShipsToRoute'''(role : String, count : Number [, fraction: Number] [, route: String]) : Array
Adds ships to the system on certain common routes and returns the added ships as an array. The routes are the two character codes <code>"wp"</code>, <code>"pw"</code>, <code>"ws"</code>, <code>"sw"</code>, <code>"sp"</code>, and <code>"ps"</code>, where <code>"w"</code> stands for the witchpoint, <code>"p"</code> for the planet and <code>"s"</code> for the sun.

When no route is defined, the route witchpoint → main station is assumed.

The position is a fraction of the route and must be between 0 and 1. Unlike the legacy commands the fraction takes planetary radii in account, so it does not start counting in the centre of sun/planet but from its surface. When no fraction is defined, a random fraction is chosen. Ships are added within scanner range of this position. Ships added in range of the witchpoint automatically create a witchpoint entry cloud.

'''Example''':
var ships = system.addShipsToRoute("myShips", 2, 0.7, "sw")
var pirates = system.addShipsToRoute("pirate", 3, Math.random(), "sp")
The first line adds 2 ships near each-other on the route from sun to witchpoint and puts the added ship in the array <code>ships</code>, and the second line adds a group of 3 pirates at a random position along the sun to planet route and returns the array <code>pirates</code>.

'''Note:''' this method will fail and return <code>null</code> if either of the route end points doesn’t exist. No valid routes exist in interstellar space.

'''See Also:''' <code>[[#addGroupToRoute|addGroupToRoute()]]</code>, <code>[[#addShips|addShips()]]</code>

=== <code>addVisualEffect</code> ===
{{oolite-method-added|1.77}}
function '''addVisualEffect'''(effectKey : String, position: {{oojsvecexpr}}) : VisualEffect
Adds a new visual effect with the effectKey in effectdata to the system, at the specified position, and returns the added effect. If the effectKey does not exist, or creation was otherwise impossible, this method will fail and return <code>null</code>.

Note that unlike the methods for adding ships, <code>addVisualEffect</code> returns a single entity, not an array.

=== <code>countEntitiesWithScanClass</code> ===
function '''countEntitiesWithScanClass'''(scanClass : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Number (integer)
Returns the number of ships with the specified ScanClass in the system.

=== <code>countShipsWithPrimaryRole</code> ===
function '''countShipsWithPrimaryRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Number (integer)
Returns the number of ships with the specified primary role in the system.

=== <code>countShipsWithRole</code> ===
function '''countShipsWithRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Number (integer)
Returns the number of ships with the specified role in the system. Counts not only the primary role the ship is added with but all roles a ship can have.

=== <code>entitiesWithScanClass</code> ===
function '''entitiesWithScanClass'''(scanClass : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
A list of the entities in the system whose scan class is <code>scanClass</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.

'''See Also:''' <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.

=== <code>filteredEntities</code> ===
function '''filteredEntities'''(this : Object, predicate : Function [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
A list of the entities for which <code>predicate</code> returns <code>true</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.

'''Example:'''
this.findIdlePoliceInScannerRange = function()
{
function $isIdlePolice(entity)
{
return entity.isShip && entity.isPolice && !entity.target
}

return system.filteredEntities(this, $isIdlePolice, player.ship, 25600);
}

'''See Also:''' <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole]]()</code>, <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>.

=== <code>legacy_addShips etc.</code> ===
function '''legacy_addShips'''(role : String, count : Number)
function '''legacy_addSystemShips'''(role : String, count : Number, position : Number)
function '''legacy_addShipsAt'''(role : String, count : Number, coordscheme : String, where : {{oojsvecexpr}})
function '''legacy_addShipsAtPrecisely'''(role : String, count : Number, coordscheme : String, where : {{oojsclass|Planet}})
function '''legacy_addShipsWithinRadius'''(role : String, count : Number, coordScheme : String, where : {{oojsclass|Planet}}, radius : Number)
function '''legacy_spawnShip'''(shipDataKey : String)
Various ways of causing ships to appear. Each of these corresponds to a legacy scripting method. For more info about the <code>coordScheme</code>, look at [[Oolite coordinate systems]]. These methods are kept for backwards-compatibility; for new development, <code>[[#addShips|addShips()]]</code> is preferred.

'''Important:''' <code>legacy_spawn</code>, previously listed here, never worked as intended and has been replaced with <code>Ship.[[Oolite JavaScript Reference: Ship#spawn|spawn]]()</code>.

=== <code>locationFromCode</code> ===
{{oolite-method-added|1.79}}
function '''locationFromCode'''(code) : Vector
Returns a random location in the region specified by the code string. The code strings are the same as used by the [[Oolite_System_Populator|Oolite populator]]

=== <code>scrambledPseudoRandomNumber</code>===
function '''scrambledPseudoRandomNumber'''(salt : Number (integer)) : Number
Returns a number that’s greater than or equal to zero and less than one. It will always return the same value for a given <code>salt</code> value and system. Crucially, the relationship between systems and numbers is effectively completely different for each salt value, so scripts making similar decisions based on <code>scrambledPseudoRandomNumber()</code> but using different salts will get uncorrelated results. For example, if two different OXPs add a certain type of station to 25% of systems using <code>if (system.pseudoRandomNumber < 0.25)</code>, the two station types will always be found in the same system; using <code>scrambledPseudoRandomNumber()</code> with different salts avoids this.

{{QuoteText|Text=scrambledPseudoRandomNumber, was invented to generate 'random' numbers that are always the same for a given system. Useful to only add stations in certain systems and consistently over time. The salt was added to prevent all oxp's selecting the same 'random' choice for a given system. |Source=([http://oolite.aegidian.org/bb/viewtopic.php?p=193483#p193483 Eric Walch])}}

'''See also''': <code>[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random math.random]</code>

=== <code>sendAllShipsAway</code> ===
function '''sendAllShipsAway'''()
Makes all ships hyperspace out of the system.

=== <code>setPopulator</code> ===
{{oolite-method-added|1.79}}
function '''setPopulator'''(key : String, definition : Object)
Sets the [[Oolite_System_Populator|populator settings]] for the specified key to the given definition, or deletes them if the definition is <code>null</code>. Calling this outside of the system population set up is possible but useless. See the populator settings page for more information on the format of the <code>definition</code> object.

'''See Also:''' <code>[[#populatorSettings|populatorSettings]]</code>

=== <code>setWaypoint</code> ===
{{oolite-method-added|1.79}}
function '''setWaypoint'''(key : String, position : VectorExpression, orientation : QuaternionExpression, parameters : Object)
Adds a [[Oolite_JavaScript_Reference:_Waypoint|waypoint]] to the system with the given <code>key</code>, placed at the specified <code>position</code> and <code>orientation</code>. <code>parameter</code> is an object with the following optional keys:
* '''size''': the radius of the waypoint in metres
* '''beaconCode''': the beacon code (default "W")
* '''beaconLabel''': the beacon label (default "Waypoint")
Waypoints will be visible only when the player has a working Advanced Space Compass.

'''setWaypoint'''(key : String)
Removes the waypoint with the specified <code>key</code>, if it exists.

In Oolite 1.81, waypoints can either be oriented (the 1.80 default) or unoriented. Unoriented waypoints do not display the directional arrows. To create an unoriented waypoint, set its orientation to the zero quaternion (0,0,0,0) either on creation or later.

'''See Also:''' <code>[[#waypoints|waypoints]]</code>

=== <code>shipsWithPrimaryRole</code> ===
function '''shipsWithPrimaryRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
A list of the entities in the system whose [[Oolite JavaScript Reference: Ship#primaryRole|primary role]] is <code>role</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.

'''See Also:''' <code>[[#shipsWithRole|shipsWithRole]]()</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.

=== <code>shipsWithRole</code> ===
function '''shipsWithRole'''(role : String [, relativeTo : {{oojsclass|Entity}} [, range : Number]]) : Array
A list of the entities in the system whose [[Oolite JavaScript Reference: Ship#roles|role set]] contains <code>role</code>. If <code>relativeTo</code> is specified, the list will be sorted in order of proximity to <code>relativeTo</code> (i.e., the first element of the list is closest). If <code>range</code> is also specified, entities further than <code>range</code> metres from <code>relativeTo</code> will be excluded. If no matching entities are found, an empty array is returned.

'''See Also:''' <code>[[#shipsWithPrimaryRole|shipsWithPrimaryRole()]]</code>, <code>[[#entitiesWithScanClass|entitiesWithScanClass]]()</code>, <code>[[#filteredEntities|filteredEntities]]()</code>.

== Static Methods ==
=== <code>infoForSystem</code> ===
function '''infoForSystem'''(galaxyNumber: Integer, systemID : Integer) (write-only)
Overwrites existing info of the given system. As properties it uses the [[planetinfo.plist]] keys. e.g.
System.infoForSystem(0, 55).description = "This is a dull planet."
sets the description of planet nr 55 in galaxy 0 to <code>"This is a dull planet."</code>

Starting from Oolite 1.73, all system Info for the present galaxy is also readable. Even though any galaxy system info property is fully settable, due to engine limitations other galaxies' data is not accessible. In other words
System.infoForSystem(0, 55).description
would return <code>"This is a dull planet."</code> if called from galaxy 0, and throw an exception if called from the other galaxies.

Of particular note the spelling of the '''techlevel''' property when using the infoForSystem method to extract it. While the property of <code>system.'''techLevel'''</code> is spelt using camelCase, <code>System.infoForSystem(0, 55).'''techlevel'''</code> is all lowercase. This is because planetinfo.plist has always had the techlevel key spelt this way.

=== <code>systemIDForName</code> ===
function '''systemIDForName'''(systemName : String) : Integer
Returns the ID number of a system in the current galaxy based on the system name.

'''Note:''' in galaxy 8, there are two systems named <code>"Inzaan"</code>. <code>systemIDForName()</code> will return the lower ID, which is 22.

=== <code>systemNameForID</code> ===
function '''systemNameForID'''(systemID : Integer) : String
Returns the name of a system in the current galaxy based on the given ID number.

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: PlayerShip

2022-10-29T20:53:46Z

Massively Locked: /* currentWeapon */ uniform null format

'''Prototype:''' <code>[[Oolite JavaScript Reference: Ship|Ship]]</code> 
'''Subtypes:''' none

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

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.

== Properties ==
=== <code>activeMissile</code> ===
{{oolite-prop-added|1.89}}
'''activeMissile''' : Number (read-only integer)
Index in the [[Oolite_JavaScript_Reference:_Ship#missiles|<code>missiles</code>]] array of the currently selected missile.

=== <code>aftShield</code> ===
'''aftShield''' : Number (read/write, nonnegative)
The current aft shield level, ranging from 0 to <code>[[#maxAftShield|maxAftShield]]</code>.

'''See also''': <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#forwardShield|forwardShield]]</code>, <code>[[#maxAftShield|maxAftShield]]</code>

=== <code>aftShieldRechargeRate</code> ===
'''aftShieldRechargeRate''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)
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.

'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code>

=== <code>chartHighlightMode</code> ===
{{oolite-prop-added|1.87}}

'''chartHighlightMode''' : String (read/write)
Gets/sets the type of highlight being shown on the galactic chart. Can be any one of the following:
* <code>"OOLRC_MODE_SUNCOLOR"</code>
* <code>"OOLRC_MODE_ECONOMY"</code>
* <code>"OOLRC_MODE_GOVERNMENT"</code>
* <code>"OOLRC_MODE_TECHLEVEL"</code>

=== <code>compassMode</code> ===
'''compassMode''' : String (read-only in 1.84 and earlier, read/write in 1.85 and later)
Gets/sets the current compass mode, which can be any one of the following:
* <code>"COMPASS_MODE_BASIC"</code>
* <code>"COMPASS_MODE_PLANET"</code>
* <code>"COMPASS_MODE_STATION"</code>
* <code>"COMPASS_MODE_SUN"</code>
* <code>"COMPASS_MODE_TARGET"</code>
* <code>"COMPASS_MODE_BEACONS"</code>

=== <code>compassTarget</code> ===
'''compassTarget''' : Entity(read-only in 1.84 and earlier, read/write in 1.85 and later)
Gets/sets the entity currently targeted by the compass. When setting this value, the entity must be valid, and have a compass beacon.

=== <code>compassType</code> ===
'''compassType''' : String (read-only in 1.84 and earlier, read/write in 1.85 and later)
Gets/sets the current space compass type, which can be one of the following:
* <code>"OO_COMPASSTYPE_BASIC"</code>
* <code>"OO_COMPASSTYPE_ADVANCED"</code>

=== <code>crosshairs</code> ===
{{oolite-prop-added|1.77}}
'''crosshairs''' : String (read/write)
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.

If the HUD is changed, the old value of this property will be discarded, and the HUD's default crosshairs will be used.

=== <code>currentWeapon</code> ===
{{oolite-prop-added|1.77}}
'''currentWeapon''' : EquipmentInfo (read/write)
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.

If the player is on a screen with no active weapon (e.g. docked, or viewing the status screens) then this will always be <code>null</code> and attempting to write to it will give an error.

=== <code>cursorCoordinates</code> ===
'''cursorCoordinates''' : Vector3D (read-only)
'''Discouraged in favour of <code>[[#cursorCoordinatesInLY|cursorCoordinatesInLY]]</code>.''' 
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.

=== <code>cursorCoordinatesInLY</code> ===
'''cursorCoordinatesInLY''' : Vector3D (read-only)
The current x and y cursor coordinates on the long range screen, in light years. The <code>z</code> coordinate is always 0.

=== <code>docked</code> ===
'''docked''' : Boolean (read-only)
<code>true</code> if the player is docked with a station or carrier.

=== <code>dockedStation</code> ===
'''dockedStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only)
The station with which the player is currently docked.

=== <code>extraCargo</code> ===
{{Oolite-prop-added|1.79}}
'''extraCargo''' : Number (read-only integer)
The amount the <code>[[Oolite JavaScript Reference: Ship#cargoSpaceCapacity|cargoSpaceCapacity]]</code> increases when a [[Cargo Bay Expansion]] is installed. The corresponding ''shipdata.plist'' key is <code>[[Shipdata.plist#extra_cargo|extra_cargo]]</code>. Note that although this property can be used to check non-player ships, it only contains the value for the player ship.

'''See also''': <code>[[Oolite JavaScript Reference: Ship#cargoSpaceUsed|cargoSpaceUsed]]</code>,
<code>[[Oolite JavaScript Reference: Ship#cargoSpaceAvailable|cargoSpaceAvailable]]</code>

=== <code>fastEquipmentA</code> ===
{{oolite-prop-added|1.79}}
'''fastEquipmentA''' : String (read/write)
Gets/sets the equipment key of primable equipment item currently assigned to the fast affinity defensive slot (default key: 0).

=== <code>fastEquipmentB</code> ===
{{oolite-prop-added|1.79}}
'''fastEquipmentB''' : String (read/write)
Gets/sets the equipment key of primable equipment item currently assigned to the fast affinity offensive slot (default key: TAB).

=== <code>forwardShield</code> ===
'''forwardShield''' : Number (read/write, nonnegative)
The current forward shield level, ranging from 0 to <code>[[#maxForwardShield|maxForwardShield]]</code>.

'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code>

=== <code>forwardShieldRechargeRate</code> ===
'''forwardShieldRechargeRate''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)
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

'''See also''': <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#forwardShield|forwardShield]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code>

=== <code>fuelLeakRate</code> ===
'''fuelLeakRate''' : Number (read/write)
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.

=== <code>galacticHyperspaceBehaviour</code> ===
'''galacticHyperspaceBehaviour''' : String (read/write)
A string indicating what the effect of a galactic hyperspace jump will be. The available options are:
* <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.
* <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!
* <code>"BEHAVIOUR_FIXED_COORDINATES"</code>: The player arrives at the system closest to <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>.

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

=== <code>galacticHyperspaceFixedCoords</code> ===
'''galacticHyperspaceFixedCoords''' : [[Oolite JavaScript Reference: Vector3D|Vector3D]] (read/write)
'''Discouraged in favour of <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>.''' 
Like <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>, but in the internal coordinate system.

=== <code>galacticHyperspaceFixedCoordsInLY</code> ===
'''galacticHyperspaceFixedCoordsInLY''' : [[Oolite JavaScript Reference: Vector3D|Vector3D]] (read/write)
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.

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

=== <code>galaxyCoordinates</code> ===
'''galaxyCoordinates''' : Vector3D (read-only)
'''Discouraged in favour of <code>[[#galaxyCoordinatesInLY|galaxyCoordinatesInLY]]</code>.''' 
The player’s location in galactic space, in the internal coordinate system. The <code>z</code> coordinate is always 0.

=== <code>galaxyCoordinatesInLY</code> ===
'''galaxyCoordinatesInLY''' : Vector3D (read-only)
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.

=== <code>hud</code> ===
'''hud''' : String (read/write)
The name of the [[hud.plist|HUD plists]] defining the ship’s head up display.

=== <code>hudAllowsBigGui</code> ===
{{oolite-prop-added|1.83}}

'''hudAllowsBigGui''' : Boolean (read-only)
Whether the HUD allows a "big GUI" or not. Most useful for determining whether mission screens will have 21 or 27 lines.

If <code>hudHidden</code> is <code>true</code>, this will also be <code>true</code> even if the HUD would not normally allow a big GUI.

=== <code>hudHidden</code> ===
'''hudHidden''' : Boolean (read/write)
Whether the HUD should be visible.

=== <code>hyperspaceSpinTime</code> ===
{{oolite-prop-added|1.77}}

'''hyperspaceSpinTime''' : Number (read-only, read/write in 1.81)
The length of the ship's hyperspace countdown.

Setting this to a negative value disables the drive entirely.

=== <code>infoSystem</code> ===
{{oolite-prop-added|1.83}}

'''infoSystem''' : Number (read/write)
The ID of the system shown in the system (F7) screen.

=== <code>injectorsEngaged</code> ===
{{Oolite-prop-added|1.81}}

'''injectorsEngaged''' : Boolean(read-only)
Is the player ship currently using [[Witch Fuel Injectors|fuel injection]].

=== <code>manifest</code> ===
'''manifest''' : [[Oolite JavaScript Reference: Manifest|Manifest]] (read/write)
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.

'''Example:'''
// addressed as a property of playerShip
player.ship.manifest.food = 5
// addressed as a class of its own
manifest.food = 5

'''See also''': <code>[[#extraCargo|extraCargo]]</code>, <code>[[Oolite JavaScript Reference: Ship#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[Oolite JavaScript Reference: Ship#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[Oolite JavaScript Reference: Ship#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[#addCargoEntity|addCargoEntity()]]</code>, <code>[[Oolite JavaScript Reference: Ship#dumpCargo|dumpCargo()]]</code>, <code>[[#removeAllCargo|removeAllCargo()]]</code>

=== <code>massLockable</code> ===
{{oolite-prop-added|1.85}}
'''massLockable''' : Boolean (read/write)
Indicates whether the player ship can be mass-locked.

=== <code>maxAftShield</code> ===
'''maxAftShield''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)
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.

'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code>

=== <code>maxForwardShield</code> ===
'''maxAftShield''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)
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.

'''See also''': <code>[[#forwardShield|forwardShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code>

=== <code>missilesOnline</code> ===
{{Oolite-prop-added|1.77}}

'''missilesOnline''' : Boolean (read-only)
<code>true</code> if the ship's targeting system is currently in missile targeting mode, <code>false</code> if it is currently in identification mode.

=== <code>messageGuiTextColor</code> ===
{{oolite-prop-added|1.85}}

'''messageGuiTextColor''' : [[Materials in Oolite#Colour specifiers|Color specifier]] (read/write)
Gets/sets the color used by the message GUI component of the HUD to display text messages.

=== <code>messageGuiTextCommsColor</code> ===
{{oolite-prop-added|1.85}}

'''messageGuiTextCommsColor''' : [[Materials in Oolite#Colour specifiers|Color specifier]] (read/write)
Gets/sets the color used by the message GUI component of the HUD to display comms messages.

=== <code>multiFunctionDisplayList</code> ===
{{Oolite-prop-added|1.81}}

'''multiFunctionDisplayList''' : Array (read-only, strings)
The IDs of the currently active multi-function displays

e.g.
[null, "myoxp_mfd1"] // My OXP MFD1 in the second display, first display blank

=== <code>multiFunctionDisplays</code> ===
{{Oolite-prop-added|1.79}}

'''multiFunctionDisplays''' : Number (read-only, integer)
The number of multi-function displays available on the current HUD.

=== <code>nextSystem</code> ===
{{Oolite-prop-added|1.85}}

'''nextSystem''' : Integer (read-only)
The ID of the next hyperspace system, if the player has a multi-step course plotted on the galactic chart.

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

=== <code>price</code> ===
{{Oolite-prop-added|1.77}}

'''price''' : Number (read-only, positive integer in decicredits)
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.

=== <code>primedEquipment</code> ===
{{oolite-prop-added|1.85}}

'''primedEquipment''' : String (read/write)
Gets/sets the equipment key of current primed equipment item. When setting, the change will happen silently (i.e., there will be no console message informing the player of the change).

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

=== <code>renovationCost</code> ===
{{Oolite-prop-added|1.79}}

'''renovationCost''' : Number (read-only, positive integer in decicredits)
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.

=== <code>renovationMultiplier</code> ===
{{Oolite-prop-added|1.79}}

'''renovationMultiplier''' : Number (read-only, positive)
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]]

=== <code>reticleColorTarget</code> ===
{{oolite-prop-added|1.85}}

'''reticleColorTarget''' : [[Materials in Oolite#Colour specifiers|Color specifier]] (read/write)
Gets/sets the color used to highlight a target on the HUD.

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

=== <code>reticleColorTargetSenstive</code> ===
{{oolite-prop-added|1.85}}

'''reticleColorTargetSensitive''' : [[Materials in Oolite#Colour specifiers|Color specifier]] (read/write)
Gets/sets the color used to highlight a target on the HUD when it is lined up (the <code>reticleTargetSensitive</code> property must be <code>true</code>).

'''See also''': <code>[[#reticleColorTarget|reticleColorTarget()]]</code>, <code>[[#reticleTargetSenstive|reticleTargetSensitive]]</code>

=== <code>reticleColorWormhole</code> ===
{{oolite-prop-added|1.85}}

'''reticleColorWormhole''' : [[Materials in Oolite#Colour specifiers|Color specifier]] (read/write)
Gets/sets the color used to highlight a wormhole on the HUD.

=== <code>reticleTargetSensitive</code> ===
'''reticleTargetSensitive''' : Boolean (read/write)
If <code>true</code> and the [[Scanner Targeting Enhancement]] is installed, the selected target reticle will turn red when the target is in the player’s sights. This is equivalent to the <code>[[Hud.plist#reticle_target_sensitive|reticle_target_sensitive]]</code> key in HUD plists.

=== <code>routeMode</code> ===
{{oolite-prop-added|1.81}}
'''routeMode''' : String (read-only)
Gives the current mode of the [[Advanced Navigational Array]]. Three possible values
* <code>"OPTIMIZED_BY_NONE"</code>: off, or not fitted
* <code>"OPTIMIZED_BY_JUMPS"</code>: shortest route
* <code>"OPTIMIZED_BY_TIME"</code>: quickest route

=== <code>scannerNonLinear</code> ===
'''scannerNonLinear''' : Boolean (read/write)
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.

=== <code>scannerUltraZoom</code> ===
'''scannerUltraZoom''' : Boolean (read/write)
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.

=== <code>scoopOverride</code> ===
'''scoopOverride''' : Boolean (read/write)
If <code>true</code> and the player has a [[Fuel Scoops|fuel scoop]], the fuel scoop effect will run even if not close to a sun or scooping cargo.

=== <code>serviceLevel</code> ===
{{Oolite-prop-added|1.77}}
'''serviceLevel''' : Number (read/write, positive integer in range 75-100)
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.

=== <code>specialCargo</code> ===
'''specialCargo''' : String (read-only)
The special cargo the player is carrying, if any; otherwise <code>null</code>. This will not be listed in the manifest.

'''See also''': <code>[[#useSpecialCargo|useSpecialCargo()]]</code>, <code>[[#removeAllCargo|removeAllCargo()]]</code>

=== <code>targetSystem</code> ===
'''targetSystem''' : Integer (read-only, sometimes read/write in 1.77)
The ID of the selected hyperspace target system. In 1.77, it can be written to if the player's ship is docked. The target system is the final destination system if the player has a multi-jump course plotted on the galactic chart.

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

=== <code>torusEngaged</code> ===
{{Oolite-prop-added|1.81}}
'''torusEngaged''' : Boolean(read-only)
Is the player ship currently using [[Torus Drive|torus drive]].

=== <code>viewDirection</code> ===
'''viewDirection''' : String (read-only)
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>.

=== <code>viewPosition*</code> ===
{{Oolite-prop-added|1.79}}
'''viewPositionAft''' : Vector (read-only)
'''viewPositionForward''' : Vector (read-only)
'''viewPositionPort''' : Vector (read-only)
'''viewPositionStarboard''' : Vector (read-only)
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>.

=== <code>weaponsOnline</code> ===
'''weaponsOnline''' : Boolean (read-only)
Returns the weapon safety status. Player can toggle the status with the underscore-key.

== Methods ==
=== <code>addCargoEntity</code> ===
{{oolite-method-added|1.85}}
function '''addCargoEntity'''(cargo : ShipEntity [, processEvents : Boolean [, processMessages : Boolean]]) : Boolean
Adds a cargo entity directly to the player's cargo hold. This can be performed only under the following conditions: the player's ship is in space with enough [[Oolite JavaScript Reference: Ship#cargoSpaceAvailable|free cargo capacity]], the cargo item passed to the method must be a valid ship entity and able to be [[Fuel Scoops|scooped]]. Will return <code>true</code> if the cargo item was successfully added to the player ship, otherwise <code>false</code>.

The optional <code>processEvents</code> parameter controls whether or not standard scooping events (<code>[[Oolite JavaScript Reference: Ship script event handlers#shipWasScooped|shipWasScooped]]</code> and <code>[[Oolite JavaScript Reference: World script event handlers#shipScoopedOther|shipScoopedOther]]</code>) will be performed when the ship is added. The default is <code>false</code>.

The optional <code>processMessages</code> parameter controls whether or not any of the standard scooping messages (eg. "1t Computers") will be displayed. The default is <code>false</code>.

'''See also''': <code>[[Oolite JavaScript Reference: Ship#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[Oolite JavaScript Reference: Ship#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[#manifest|manifest]]</code>

=== <code>addParcel</code> ===
{{oolite-method-added|1.77}}
function '''addParcel'''(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean
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.

Returns <code>false</code> when there is already a parcel with that name or the arrival time is invalid.

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 <code>0</code>, <code>1</code> or <code>2</code>: the higher the number, the more likely that assassins will try to kill the player carrying this parcel.

'''See also''': <code>[[Oolite JavaScript Reference: Ship#parcelCount|parcelCount]]</code>, <code>[[Oolite JavaScript Reference: Ship#parcels|parcels]]</code>, <code>[[#removeParcel|removeParcel()]]</code>

=== <code>addPassenger</code> ===
function '''addPassenger'''(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean
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.

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.

'''Example:'''
player.ship.addPassenger("cmdr Jameson", 34, 67, clock.seconds+3*24*3600, 1500);

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

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

The risk parameter was added in Oolite 1.79. <code>risk</code> can be <code>0</code>, <code>1</code> or <code>2</code>: the higher the number, the more likely that assassins will try to kill the player carrying this passenger.

'''See also''': <code>[[Passenger Berth]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengerCapacity|passengerCapacity]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengerCount|passengerCount]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengers|passengers]]</code>, <code>[[#removePassenger|removePassenger()]]</code>

=== <code>awardContract</code> ===
function '''awardContract'''(quantity : Number, commodity : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, premium : Number]) : Boolean
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.

Returns <code>false</code> when there is no room for the cargo, the arrival time is invalid.

'''Example:'''
player.ship.awardContract(12, "Food", 34, 67, clock.seconds+7*24*3600, 5000)

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

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

'''See also''': <code>[[Oolite JavaScript Reference: Ship#contracts|contracts]]</code>, <code>[[#removeContract|removeContract()]]</code>

=== <code>awardEquipmentToCurrentPylon</code> ===
function '''awardEquipmentToCurrentPylon'''(item : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean
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.

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

'''See also:''' <code>[[Oolite JavaScript Reference: Ship#awardEquipment|Ship.awardEquipment()]]</code>

=== <code>beginHyperspaceCountdown</code> ===
{{oolite-method-added|1.77}}
function '''beginHyperspaceCountdown'''( [ length : Number ] ) : Boolean
This method begins the witchspace sequence for the player ship. It returns <code>true</code> if the sequence is started successfully, and <code>false</code> 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.

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

=== <code>cancelDockingRequest</code> ===
{{oolite-method-added|1.85}}
function '''cancelDockingRequest'''(station : Station)
Tells the station to cancel a previous request for docking. If the player isn't currently waiting for clearance, or doesn't already have clearance, this method will do nothing

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

=== <code>cancelHyperspaceCountdown</code> ===
{{oolite-method-added|1.77}}
function '''cancelHyperspaceCountdown'''() : Boolean
This method cancels the witchspace sequence for the player ship. It returns <code>true</code> if there was an ongoing sequence to cancel, and <code>false</code> otherwise.

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

=== <code>disengageAutopilot</code> ===
function '''disengageAutopilot'''()
Disenable autopilot.

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

=== <code>engageAutopilotToStation</code> ===
function '''engageAutopilotToStation'''(station : [[Oolite JavaScript Reference: Station|Station]]) : Boolean
Engage autopilot, set to dock with the specified station.

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

=== <code>hideHUDSelector</code> ===
{{oolite-method-added|1.79}}
function '''hideHUDSelector'''(selector : String)
Hide all dials using the specified [[Hud.plist#selector|selector]] on the HUD display. For example

player.ship.hideHUDSelector("drawScanner:");

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

=== <code>launch</code> ===
function '''launch'''()
Launches the player’s ship if it is currently docked.

=== <code>removeAllCargo</code> ===
function '''removeAllCargo'''()
Removes all cargo from the ship’s cargo bay that are measured in tons (including [[#specialCargo|special cargo]]). Does not affect gold, platinum or gem stones. Can only be used while docked.

'''See also''': <code>[[Oolite JavaScript Reference: Ship#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[Oolite JavaScript Reference: Ship#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[Oolite JavaScript Reference: Ship#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[Oolite JavaScript Reference: Ship#dumpCargo|dumpCargo()]]</code>, <code>[[#manifest|manifest]]</code>

=== <code>removeContract</code> ===
function '''removeContract'''(commodity : String, destination : Number)
Remove the cargo contract matching that commodity and destination.

'''See also''': <code>[[Oolite JavaScript Reference: Ship#contracts|contracts]]</code>, <code>[[#awardContract|awardContract()]]</code>

=== <code>removeParcel</code> ===
{{oolite-method-added|1.77}}
function '''removeParcel'''(name : String)
Remove a named parcel.

'''See also''': <code>[[Oolite JavaScript Reference: Ship#parcelCount|parcelCount]]</code>, <code>[[Oolite JavaScript Reference: Ship#parcels|parcels]]</code>, <code>[[#addParcel|addParcel()]]</code>

=== <code>removePassenger</code> ===
function '''removePassenger'''(name : String)
Remove a named passenger.

'''See also''': <code>[[Oolite JavaScript Reference: Ship#passengerCapacity|passengerCapacity]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengerCount|passengerCount]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengers|passengers]]</code>, <code>[[#addPassenger|addPassenger()]]</code>

=== <code>requestDockingClearance</code> ===
{{oolite-method-added|1.85}}
function '''requestDockingClearance'''(station : Station)
Sends the station a request to dock. If the station has already granted docking clearance, or is currently processing a previous request, this method will do nothing.

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

=== <code>resetCustomView</code> ===
{{oolite-method-added|1.77}}
function '''resetCustomView'''()
Resets the custom view back to the last-used setting defined in [[shipdata.plist]]

This method gives an error if used when the custom view camera is not selected.

=== <code>resetScannerZoom</code> ===
{{oolite-method-added|1.79}}
function '''resetScannerZoom'''()
Resets the scanner zoom back to 1:1

=== <code>setCustomView</code> ===
{{oolite-method-added|1.77}}
function '''setCustomView'''(Vector : position, Quaternion : orientation [,WeaponDirection weapon])
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.

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.

This method 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.

=== <code>setCustomHUDDial</code> ===
{{oolite-method-added|1.81}}
function '''setCustomHUDDial'''(key : String, value : Value)
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.

=== <code>setMultiFunctionDisplay</code> ===
{{oolite-method-added|1.79}}
function '''setMultiFunctionDisplay'''(index : Number, key : String) : Boolean
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 method will return <code>false</code> if all are currently in use.
Example:
// picks first unused one
player.ship.setMultiFunctionDisplay(player.ship.multiFunctionDisplays, "myOxp_mfd");

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 method to override a specific display except in emergencies, as this is likely to annoy the player.

=== <code>setMultiFunctionText</code> ===
{{oolite-method-added|1.79}}
function '''setMultiFunctionText'''(key : String [, contents : String [, reflow : Boolean]])
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.

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.

=== <code>setPrimedEquipment</code> ===
{{oolite-method-added|1.85}}
function '''setPrimedEquipment'''(equipmentKey : String [, showMessage : Boolean])
Sets the current primed equipment to the specified equipment key.

Returns <code>true</code> if the method was successful. If equipment key is not found, primed equipment will be set to "None".

If the showMessage parameter is left out or set to <code>true</code>, a console message will be displayed informing the player of the change in primed equipment. Setting showMessage to <code>false</code> will make the change silently.

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

=== <code>showHUDSelector</code> ===
{{oolite-method-added|1.79}}
function '''showHUDSelector'''(selector : String)
Show all dials using the specified [[Hud.plist#selector|selector]] on the HUD display if they were previously hidden. For example

player.ship.showHUDSelector("drawScanner:");

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

=== <code>takeInternalDamage</code> ===
{{oolite-method-added|1.77}}
function '''takeInternalDamage'''() : Boolean
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 method uses the same algorithm to determine the damage taken, which can be:
* damage to cargo
* damage to equipment (according to the damage_probability)
* reduction in [[#serviceLevel|service level]]
* no damage
The method will return <code>false</code> if "no damage" was selected, or <code>true</code> 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.

=== <code>useSpecialCargo</code> ===
function '''useSpecialCargo'''(description : String)
Fills the cargo bay with the cargo described, effectively disabling the use of the cargo bay until the cargo is removed. Any current cargo (except for g- and kg-based cargo) will be discarded. Use [[#removeAllCargo|removeAllCargo()]] to remove the special cargo.

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

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Player

2022-10-29T20:47:19Z

Massively Locked: /* setEscapePodDestination */ cleared up wording

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

The '''<code>Player</code>''' class is represents the player. There is always exactly one <code>Player</code> object in existence, which can be accessed through the <code>player</code> global property.

== Properties ==
=== <code>alertAltitude</code> ===
'''alertAltitude''' : Boolean (read-only)
Whether the player is dangerously close to a planet. (closer than 4000 meter to the surface)

=== <code>alertCondition</code> ===
'''alertCondition''' : Number (read-only, integer)
Returns the current alert condition. 0 = Docked, 1 = Green, 2 = Yellow, 3 = Red.

=== <code>alertEnergy</code> ===
'''alertEnergy''' : Boolean (read-only)
Whether the player’s energy level is depleted (i.e., <code>[[Oolite JavaScript Reference: Entity#energy|energy]]</code> is less than <code>[[Oolite JavaScript Reference: Entity#maxEnergy|maxEnergy]]</code>).

=== <code>alertHostiles</code> ===
'''alertHostiles''' : Boolean (read-only)
Whether there are hostile ships within scanner range.

=== <code>alertMassLocked</code> ===
'''alertMassLocked''' : Boolean (read-only)
Whether the player is mass locked.

=== <code>alertTemperature</code> ===
'''alertTemperature''' : Boolean (read-only)
Whether the cabin temperature is dangerously high.

=== <code>bounty</code> ===
'''bounty''' : Number (read/write integer)
The bounty on the player, which determines legal status. It is halved at each witchspace jump.

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

=== <code>contractReputation</code> ===
'''contractReputation''' : Number (read-only integer)
{{oolite-prop-added|1.79}}
'''contractReputationPrecise''' : Number (read-only decimal)
The player’s cargo contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards..

'''See also:''' <code>[[#decreaseContractReputation|decreaseContractReputation()]]</code>, <code>[[#increaseContractReputation|increaseContractReputation()]]</code>, <code>[[Oolite JavaScript Reference: Ship#contracts|contracts]]</code>, <code>[[#parcelReputation|parcelReputation]]</code>, <code>[[#passengerReputation|passengerReputation]]</code>

=== <code>credits</code> ===
'''credits''' : Number (read/write, float)
The amount of money the player has, in credits.

=== <code>dockingClearanceStatus</code> ===
'''dockingClearanceStatus''' : String (read-only)
A string indicating whether the player has docking clearance. (''Clarify: for which station? -[[User:Ahruman|Ahruman]] 20:34, 3 November 2008 (UTC)'') Possible values are:
* <code>"DOCKING_CLEARANCE_STATUS_NONE"</code>
* <code>"DOCKING_CLEARANCE_STATUS_REQUESTED"</code>
* <code>"DOCKING_CLEARANCE_STATUS_NOT_REQUIRED"</code>
* <code>"DOCKING_CLEARANCE_STATUS_GRANTED"</code>
* <code>"DOCKING_CLEARANCE_STATUS_TIMING_OUT"</code>

=== <code>escapePodRescueTime</code> ===
{{oolite-prop-added|1.89}}
'''escapePodRescueTime''' : Number (read-write decimal)
Number of seconds that will be added to the clock when the player uses an escape pod and is rescued. Default value is 0 (zero), which will utilise the default time calculation that can add up to eight days to the clock.
Negative numbers will be ignored (and default calculation will apply).

=== <code>legalStatus</code> ===
'''legalStatus''' : String (read-only)
A string describing the player’s legal status for display purposes, based on <code>[[#bounty|bounty]]</code>. In English, this is one of <code>"Clean"</code> (bounty = 0), <code>"Offender"</code> (0 < bounty ≤ 50) or <code>"Fugitive"</code>, but note that it can be localized.

=== <code>name</code> ===
'''name''' : String (read-only, read/write from 1.79)
The name of the player’s character (e.g., <code>"Jameson"</code>). Prior to 1.79, this was also used as the filename for the savegame and so was not writable.

=== <code>parcelReputation</code> ===
{{oolite-prop-added|1.77}}
'''parcelReputation''' : Number (read-only integer)
{{oolite-prop-added|1.79}}
'''parcelReputationPrecise''' : Number (read-only decimal)
The player’s parcel contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards.

'''See also:''' <code>[[#decreaseParcelReputation|decreaseParcelReputation()]]</code>, <code>[[#increaseParcelReputation|increaseParcelReputation()]]</code>, <code>[[Oolite JavaScript Reference: Ship#parcels|parcels]]</code>, <code>[[#contractReputation|contractReputation]]</code>, <code>[[#passengerReputation|passengerReputation]]</code>

=== <code>passengerReputation</code> ===
'''passengerReputation''' : Number (read-only integer)
{{oolite-prop-added|1.79}}
'''passengerReputationPrecise''' : Number (read-only decimal)
The player’s passenger contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards.

'''See also:''' <code>[[#decreasePassengerReputation|decreasePassengerReputation()]]</code>, <code>[[#increasePassengerReputation|increasePassengerReputation()]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengers|passengers]]</code>, <code>[[#contractReputation|contractReputation]]</code>, <code>[[#parcelReputation|parcelReputation]]</code>

=== <code>rank</code> ===
'''rank''' : String (read-only)
A string describing the player’s rank for display purposes, based on <code>[[#score|score]]</code>, such as <code>"Mostly Harmless"</code> or <code>"Dangerous"</code>. Note that it can be localized.

=== <code>roleWeights</code> ===
{{oolite-prop-added|1.79}}
'''roleWeights''' : Array (read-only)
An array of the player's current role as perceived by the game. Generally NPCs will pick a random entry from this list and treat the player as if they were an NPC of that role. The '<code>player-unknown</code>' role is the default role. The size of the list depends on the player's current Elite ranking.

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

=== <code>score</code> ===
'''score''' : Number (read/write, integer)
The player’s score; nominally the number of kills the player has made, although some missions award additional points.

=== <code>ship</code> ===
'''ship''' : [[Oolite_JavaScript_Reference:_Ship | Ship]]
The player’s ship

=== <code>trumbleCount</code> ===
'''trumbleCount''' : Number (read-only nonnegative integer)
The number of trumbles the player is currently blessed with.

== Methods ==
=== <code>addMessageToArrivalReport</code> ===
function '''addMessageToArrivalReport'''(message : String)
Adds a message to the arrival report shown immediately after docking. Oolite puts its own stuff on the list immediately after [[Oolite JavaScript Reference: World script event handlers#shipWillDockWithStation|shipWillDockWithStation]] so this is a good moment to add the messages when you know what station will be docked. [[Oolite JavaScript Reference: World script event handlers#shipDockedWithStation|shipDockedWithStation]] may also be used. Messages added while in flight or during shipWillDockWithStation will be above Oolite's own arrival messages. Those added during shipDockedWithStation will be below Oolite's own arrival messages.

'''See also''': <code>[[Oolite JavaScript Reference: Station#suppressArrivalReports|station.suppressArrivalReports]]</code>

=== <code>commsMessage</code> ===
function '''commsMessage'''(message : String [, duration: Number])
Writes the specified message in the player’s communications log, as well as displaying it as a console message. The optional <code>duration</code> parameter determines how long the message should be displayed on the console before fading out. It is clamped to the range [1, 10]. If no duration is specified, 4.5 seconds will be used.

'''Example:'''
player.commsMessage("Hello, cruel universe.", 6)
NB, this <code>commsMessage()</code> is a method of the <code>player</code> object. <code>player.ship</code> can also have a <code>[[Oolite_JavaScript_Reference:_Ship#commsMessage|commsMessage()]]</code> method, but that belongs to the ship and has a different second parameter.
*[http://aegidian.org/bb/viewtopic.php?f=4&t=10880 Formatting text msgs on a HUD] (2011)

=== <code>consoleMessage</code> ===
function '''consoleMessage'''(message : String [, duration: Number])
Displays the specified message as a console message, that is, as a message on the HUD. The optional <code>duration</code> parameter determines how long the message should be displayed before fading out. It is clamped to the range [1, 10]. If no duration is specified, 3 seconds will be used.

'''See also''': [http://aegidian.org/bb/viewtopic.php?f=4&t=10880 Formatting text msgs on a HUD] (2011)

=== <code>decreaseContractReputation</code> ===
function '''decreaseContractReputation'''()
Give the player a negative reputation point for cargo contracts. Decreases the underlying value for contractReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.

'''See also:''' <code>[[#contractReputation|contractReputation]]</code>, <code>[[#increaseContractReputation|increaseContractReputation()]]</code>

=== <code>decreaseParcelReputation</code> ===
{{oolite-method-added|1.77}}
function '''decreaseParcelReputation'''()
Give the player a negative reputation point for parcel contracts. Decreases the underlying value for parcelReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.

'''See also:''' <code>[[#parcelReputation|parcelReputation]]</code>, <code>[[#increaseParcelReputation|increaseParcelReputation()]]</code>

=== <code>decreasePassengerReputation</code> ===
function '''decreasePassengerReputation'''()
Give the player a negative reputation point for passenger contracts. Decreases the underlying value for passengerReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.

'''See also:''' <code>[[#passengerReputation|passengerReputation]]</code>, <code>[[#increasePassengerReputation|increasePassengerReputation()]]</code>

=== <code>endScenario</code> ===
{{oolite-method-added|1.79}}
function '''endScenario'''(key : String) : Boolean
End the current game immediately and return to the start game screen. Returns <code>true</code> if it succeeds (though this will shortly be irrelevant) or <code>false</code> if it fails, which it will do if the key passed in is not the same as the [[scenarios.plist#scenario|scenario key]] in the current game scenario. If the current game scenario has no scenario key, this method will always fail.

There is no way to find out what, if any, the current scenario key is. If you are calling this method, you should be doing so in a context where you already know what it is.

=== <code>increaseContractReputation</code> ===
function '''increaseContractReputation'''()
Give the player a positive reputation point for cargo contracts. Increases the underlying value for contractReputation by 1 until a maximum of 7

'''See also:''' <code>[[#contractReputation|contractReputation]]</code>, <code>[[#decreaseContractReputation|decreaseContractReputation()]]</code>

=== <code>increaseParcelReputation</code> ===
{{oolite-method-added|1.77}}
function '''increaseParcelReputation'''()
Give the player a positive reputation point for parcel contracts. Increases the underlying value for parcelReputation by 1 until a maximum of 7

'''See also:''' <code>[[#parcelReputation|parcelReputation]]</code>, <code>[[#decreaseParcelReputation|decreaseParcelReputation()]]</code>

=== <code>increasePassengerReputation</code> ===
function '''increasePassengerReputation'''()
Give the player a positive reputation point for passenger contracts. Increases the underlying value for passengerReputation by 1 until a maximum of 7

'''See also:''' <code>[[#passengerReputation|passengerReputation]]</code>, <code>[[#decreasePassengerReputation|decreasePassengerReputation()]]</code>

=== <code>setEscapePodDestination</code> ===
function '''setEscapePodDestination'''(destination)
This method can only be called after the player has launched an escape pod – mainly from the [[Oolite_JavaScript_Reference:_World_script_event_handlers#escapePodSequenceOver|<code>escapePodSequenceOver</code>]] event handler. It determines where the player will end up. The <code>destination</code> parameter may be any station/carrier, the string <code>"NEARBY_SYSTEM"</code> or <code>null</code>. If it is <code>"NEARBY_SYSTEM"</code>, the player will end up at the main station in a random nearby system. If it is <code>null</code> (which is the default in interstellar space), the player will die of life support failure.

=== <code>setPlayerRole</code> ===
{{oolite-method-added|1.79}}
function '''setPlayerRole'''(role [,index])
Sets one of the player's perceived role entries to the specified role. If index is not specified, a random entry will be chosen.

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

=== <code>replaceShip</code> ===
{{Oolite-method-added|1.77}}
function '''replaceShip'''(dataKey [, personality])
This method can only be called while the player is docked at a station. It discards the player's current ship (including all cargo, passenger contracts, and equipment), and replaces it with the ship defined by the shipyard.plist entry <code>dataKey</code> (obviously the key must also be defined in shipyard.plist as a valid player ship). The new ship will have all standard equipment for a ship of that type, and any equipment from the previous ship which was [[Oolite JavaScript Reference: EquipmentInfo#isPortableBetweenShips|isPortableBetweenShips]]. While this may not necessarily be a ship purchase, the [[Oolite JavaScript Reference: World script event handlers#playerBoughtNewShip|playerBoughtNewShip]] will fire to notify other scripts of the change, although this event is being deprecated in favour of [[Oolite JavaScript Reference: World script event handlers#playerReplacedShip|playerReplacedShip]], which was added in Oolite Test Release 1.89.

If the dataKey was not defined in both shipdata.plist and shipyard.plist, or the player is in flight, this method does nothing.

<code>personality</code> is optional, and can be between 0 and 32767. The new ship is given that specific [[Oolite_JavaScript_Reference:_Ship#entityPersonality|entityPersonality]], which for some ships may affect its appearance with shaders.

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Ship

2022-10-29T16:45:07Z

Massively Locked: /* maxSpeed */ deleted redundant link

'''Prototype:''' <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> 
'''Subtypes:''' <code>[[Oolite JavaScript Reference: Station|Station]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code>

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 an <code>Entity</code> and several others.

<code>[[Oolite JavaScript Reference: Station|Stations]]</code> and the <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code> are types of ship. Note that these more specific types have additional properties and methods.

== Properties ==
=== <code>accuracy</code> ===
{{Oolite-prop-added|1.77}}
'''accuracy''' : Number (read/write, read-only and irrelevant for player ship)
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.

For missiles, this affects the missile tracking, with 0 being the default value.

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.

=== <code>aftWeapon</code> ===
'''aftWeapon''' : EquipmentType (read-only, read/write in 1.77)
The currently equipped aft weapon, or <code>null</code>.

'''See also:''' <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code>

=== <code>AI</code> ===
'''AI''' : String (read-only)
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>"

'''See also:''' <code>[[#AIState|AIState]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AIScript|AIScript]]</code>

=== <code>AIFoundTarget</code> ===
{{oolite-prop-added|1.77}}
'''AIFoundTarget''' : Entity (read/write, read-only for player)
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.

=== <code>AIPrimaryAggressor</code> ===
{{oolite-prop-added|1.77}}
'''AIPrimaryAggressor''' : Entity (read/write, read-only for player)
The "primary aggressor" of the ship's AI. Often the last ship to attack this ship.

=== <code>AIScript</code> ===
{{oolite-prop-added|1.79}}
'''AIScript''' : String (read-only)
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>"

'''See also:''' <code>[[#AIScriptWakeTime|AIScriptWakeTime]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AI|AI]]</code>

=== <code>AIScriptWakeTime</code> ===
{{oolite-prop-added|1.79}}
'''AIScriptWaketime''' : Number (read-write)
The next game time at which the ship's Javascript-based AI script will receive an <code>aiAwoken</code> event.

=== <code>AIState</code> ===
'''AIState''' : String (read/write, read-only for player)
The ship’s plist AI’s current state.

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#reactToAIMessage|reactToAIMessage()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code>

=== <code>alertCondition</code> ===
'''alertCondition''' : Number (read-only integer)
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.

'''See also:''' [[Oolite JavaScript Reference: Station#alertCondition|station.alertCondition]]

=== <code>autoAI</code> ===
{{oolite-prop-added|1.79}}
'''autoAI''' : Boolean (read-only)
The value of the <code>"auto_ai"</code> shipdata key. If this is <code>true</code>, 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 <code>false</code>, the ship's provider would prefer you not to alter the AI of this ship but to use it as-is.

=== <code>autoWeapons</code> ===
{{oolite-prop-added|1.79}}
'''autoWeapons''' : Boolean (read-only)
The value of the <code>"auto_weapons"</code> shipdata key. If this is <code>true</code>, 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 <code>false</code>, the ship's provider would prefer you not to alter the properties of this ship but to use it as-is.

=== <code>beaconCode</code> ===
'''beaconCode''' : String (read-only in 1.76, read-write from 1.77)
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 cannot be changed by script for either the player's ship or the main station.

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

=== <code>beaconLabel</code> ===
{{oolite-prop-added|1.79}}
'''beaconLabel''' : String (read/write, read-only for player)
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.

=== <code>boundingBox</code> ===
{{Oolite-prop-added|1.77}}
'''boundingBox''' : Vector (read-only)
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.

Vector components match the standard model order - <code>x</code> is width, <code>y</code> is height, <code>z</code> is length.

=== <code>bounty</code> ===
'''bounty''' : Number (read/write integer)
The bounty on the ship.

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.

=== <code>cargoList</code> ===
{{oolite-prop-added|1.79}}
'''cargoList''' : Array (read-only)
A list of the ship's current cargo, grouped by cargo type.

An item looks like this:
{
unit: "t",
displayName: "Liquor/Wines",
commodity: "liquor_wines",
quantity: 3
}

This property is for non-player ships. For the player ship, use <code>[[Oolite JavaScript Reference: Manifest#list|manifest.list]]</code>.

'''See also''': <code>[[#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[#adjustCargo|adjustCargo()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>cargoSpaceAvailable</code> ===
'''cargoSpaceAvailable''' : Number (read-only integer)
The ship’s available cargo space, in tons.

'''See also''': <code>[[#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#manifest|manifest]]</code> (for the player ship), <code>[[#cargoList|cargoList]]</code> (for non-player ships), <code>[[#adjustCargo|adjustCargo()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>cargoSpaceCapacity</code> ===
'''cargoSpaceCapacity''' : Number (read-only in 1.80, read/write in 1.81, integer)
The ship’s cargo capacity, in tons.

'''See also''': <code>[[#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#manifest|manifest]]</code> (for the player ship), <code>[[#cargoList|cargoList]]</code> (for non-player ships), <code>[[#adjustCargo|adjustCargo()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>cargoSpaceUsed</code> ===
'''cargoSpaceUsed''' : Number (read-only integer)
The ship’s current cargo, in tons.

'''See also''': <code>[[#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#manifest|manifest]]</code> (for the player ship), <code>[[#cargoList|cargoList]]</code> (for non-player ships), <code>[[#adjustCargo|adjustCargo()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>collisionExceptions</code> ===
{{oolite-prop-added|1.81}}
'''collisionExceptions''' : Array (read-only)
A list of ships this ship is currently prevented from colliding with. See [[#addCollisionException|addCollisionException]] and [[#removeCollisionException|removeCollisionException]].

=== <code>commodity</code> ===
{{Oolite-prop-added|1.77}}
'''commodity''' : String (read-only)
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".

=== <code>commodityAmount</code> ===
{{Oolite-prop-added|1.77}}
'''commodityAmount''' : Number (read-only)
The amount of commodity in a cargo container. (not the number of containers in a ship)

=== <code>contracts</code> ===
'''contracts''' : Array (read-only NSDictionary)
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> 

For example, the information of the first contract can be obtained by:
player.ship.contracts[0].commodity
player.ship.contracts[0].quantity
player.ship.contracts[0].description
player.ship.contracts[0].start
player.ship.contracts[0].destination
player.ship.contracts[0].startName
player.ship.contracts[0].destinationName
player.ship.contracts[0].eta // Estimated Time of Arrival.
player.ship.contracts[0].etaDescription
player.ship.contracts[0].fee // The profit of the contract, paid out on successful delivery.
player.ship.contracts[0].premium // The sum paid to obtain the goods and paid back on successful delivery.

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.

'''See also''': <code>[[Oolite JavaScript Reference: PlayerShip#awardContract|awardContract()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removeContract|removeContract()]]</code>, <code>[[Oolite JavaScript Reference: Player#contractReputation|contractReputation]]</code>

=== <code>cloakAutomatic</code> ===
'''cloakAutomatic''' : Boolean (read/write)
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>.

=== <code>crew</code> ===
{{oolite-prop-added|1.79}}
'''crew''' : Array (read-only)
An array containing the ship's crew. Each crew member is represented as a dictionary:
{
"description":"a small yellow horned humanoid from Malama",
"name":"Masten Onlo",
"homeSystem":49,
"insuranceCredits":500,
"species":"small yellow horned humanoid",
"legalStatus":0
}

Note that in current Oolite versions ships only have a single crew member defined.

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

=== <code>cruiseSpeed</code> ===
'''cruiseSpeed''' : Number (read-only nonnegative)
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.

=== <code>currentWeapon</code> ===
{{oolite-prop-added|1.77}}
'''currentWeapon''' : EquipmentType (read/write)
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.

=== <code>dataKey</code> ===
{{Oolite-prop-added|1.77}}
'''dataKey''' : String (read-only)
The ship data key used to define this ship (e.g. <code>"adder-player"</code> or <code>"coriolis-station"</code>)

=== <code>defenseTargets</code> ===
{{Oolite-prop-added|1.77}}
'''defenseTargets''' : Array (read-only)
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.

'''See also:''' <code>[[#addDefenseTarget|addDefenseTarget]]</code>, <code>[[#clearDefenseTargets|clearDefenseTargets]]</code>

=== <code>desiredRange</code> ===
{{Oolite-prop-added|1.77}}
'''desiredRange''' : Number (read/write nonnegative, read-only for player)
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.

=== <code>desiredSpeed</code> ===
'''desiredSpeed''' : Number (read/write nonnegative, read-only for player)
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>.

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

=== <code>destination</code> ===
{{Oolite-prop-added|1.77}}
'''destination''' : Vector (read/write, read-only for player)
The destination coordinates for the AI, used in behaviours such as <code>performFlyToRangeFromDestination</code>.

=== <code>destinationSystem</code> ===
{{Oolite-prop-added|1.79}}
'''destinationSystem''' : Number (read/write)
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.

=== <code>displayName</code> ===
'''displayName''' : String (read/write, read-only for player)
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 <code>[[#shipClassName|shipClassName]]</code> and <code>[[#shipUniqueName|shipUniqueName]]</code>.

=== <code>dockedStation</code> ===
'''dockedStation''' : [[Oolite_JavaScript_Reference:_Station | Station]]
The Station the ship is currently docked to.

=== <code>dockingInstructions</code> ===
{{oolite-prop-added|1.79}}
'''dockingInstructions''' : Object (read-only)
If the ship is currently attempting to dock with a station, this describes the next step on its docking procedure

{
station: [Station "Coriolis Station" "Coriolis Station" position: (-31043.6, -94232.3, 619036) scanClass: CLASS_STATION status: STATUS_ACTIVE],
match_rotation: 0,
ai_message: "APPROACH_COORDINATES",
speed: 512,
destination: {
x: -28033.37401563089,
y: -92813.76688970842,
z: 622226.0625336492
},
range: 96
}

'''See also:''' <code>[[#requestDockingInstructions|requestDockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code>

=== <code>energyRechargeRate</code> ===
{{Oolite-prop-added|1.79}}
'''energyRechargeRate''' : Number (read-only, read/write from 1.81)
The rate at which energy is replenished in every second. The corresponding ''[[shipdata.plist]]'' key is <code>energy_recharge_rate</code>.

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.

=== <code>entityPersonality</code> ===
'''entityPersonality''' : Number (read-only integer, read/write in 1.81 onwards)
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]].

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.

=== <code>equipment</code> ===
'''equipment''' : Array of [[Oolite JavaScript Reference: EquipmentInfo|EquipmentInfo]] (read-only)
The equipment a ship is carrying.

=== <code>escortGroup</code> ===
'''escortGroup''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]
The ship’s deployed escorts.

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

=== <code>escorts</code> ===
'''escorts''' : Array (read-only array of [[Oolite JavaScript Reference: Entity|Entity]]s)
The ship’s deployed escorts.

=== <code>exhaustEmissiveColor</code> ===
{{Oolite-prop-added|1.79}}
'''exhaustEmissiveColor''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
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.

=== <code>exhausts</code> ===
{{Oolite-prop-added|1.79}}
'''exhausts''' : Array (read-only)
An array of the ship's [[Oolite JavaScript Reference: ExhaustPlume|ExhaustPlume]] subentities.

=== <code>flashers</code> ===
{{Oolite-prop-added|1.79}}
'''flashers''' : Array (read-only)
An array of the ship's [[Oolite JavaScript Reference: Flasher|Flasher]] subentities.

=== <code>forwardWeapon</code> ===
'''forwardWeapon''' : EquipmentType (read-only, read/write in 1.77)
The currently equipped forward weapon, or <code>null</code>.

'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code>

=== <code>fuel</code> ===
'''fuel''' : Number (read/write)
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.

'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#fuelLeakRate|PlayerShip.fuelLeakRate]]</code>

=== <code>fuelChargeRate</code> ===
'''fuelChargeRate''' : Number (read-only)
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.

=== <code>group</code> ===
'''group''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]
Contains ship’s belonging to each other. Added pirate groups are an example or a station with its launched defenders. 
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. 
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.
e.g.
this.ship.group = new ShipGroup();
this.ship.group.addShip(this.ship);

=== <code>hasHostileTarget</code> ===
'''hasHostileTarget''' : Boolean (read-only)
<code>true</code> if the ship’s AI is trying to kill something, <code>false</code> otherwise. Always <code>false</code> for the player.

=== <code>hasHyperspaceMotor</code> ===
'''hasHyperspaceMotor''' : Boolean (read-only)
<code>true</code> if the ship can make witchspace jumps. The corresponding ''[[shipdata.plist]]'' entry is <code>hyperspace_motor</code>.

=== <code>hasSuspendedAI</code> ===
'''hasSuspendedAI''' : Boolean (read-only)
<code>true</code> if the ship has suspended AIs, <code>false</code> otherwise.

=== <code>heatInsulation</code> ===
'''heatInsulation''' : Number (read/write)
The ship’s heat insulation factor. 1.0 is normal, higher values mean more resistance to heat.

Note that in 1.80 and earlier writes to this property had no effect on the player ship.

=== <code>homeSystem</code> ===
{{Oolite-prop-added|1.79}}
'''homeSystem''' : Number (read/write)
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.

=== <code>hyperspaceSpinTime</code> ===
{{oolite-prop-added|1.81}}
'''hyperspaceSpinTime''' : Number (read/write)
The length of the ship's hyperspace countdown.

Setting this to a negative value disables the drive entirely.

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.

=== <code>injectorBurnRate</code> ===
{{Oolite-prop-added|1.81}}
'''injectorBurnRate''' : Number (read/write)
The rate at which the ship's injectors burn fuel in deci-LY per second. The default is 0.25.

=== <code>injectorSpeedFactor</code> ===
{{Oolite-prop-added|1.81}}
'''injectorSpeedFactor''' : Number (read/write)
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)

=== <code>isBeacon</code> ===
'''isBeacon''' : Boolean (read-only)
<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.

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

=== <code>isBoulder</code> ===
'''isBoulder''' : Boolean (read/write)
<code>true</code> if the ship is a boulder (i.e., has the role <code>"boulder"</code> in its roleset)

=== <code>isCargo</code> ===
'''isCargo''' : Boolean (read-only)
<code>true</code> if the ship is cargo (i.e., has scan_class <code>"CLASS_CARGO"</code> and contains at least one unit)

=== <code>isCloaked</code> ===
'''isCloaked''' : Boolean (read/write)
<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>.

=== <code>isDerelict</code> ===
'''isDerelict''' : Boolean (read-only)
<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")

=== <code>isFleeing</code> ===
{{oolite-prop-added|1.79}}
'''isFleeing''' : Boolean (read-only)
<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.

=== <code>isFrangible</code> ===
'''isFrangible''' : Boolean (read-only)
<code>true</code> if the ship is frangible (i.e., its subentities can be destroyed separately from the main ship), <code>false</code> otherwise.

'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code>

=== <code>isJamming</code> ===
'''isJamming''' : Boolean (read-only)
<code>true</code> if the ship has a [[Shipdata.plist#has_military_jammer|military scanner jammer]] which is currently active, <code>false</code> otherwise.

=== <code>isMinable</code> ===
{{oolite-prop-added|1.79}}
'''isMinable''' : Boolean (read-only)
<code>true</code> if the ship will break up usefully when hit by a mining laser, <code>false</code> otherwise. By default this is <code>true</code> for anything with <code>"asteroid"</code> or <code>"boulder"</code> 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]].

=== <code>isMine</code> ===
'''isMine''' : Boolean (read-only)
<code>true</code> if the ship is a mine, <code>false</code> otherwise.

=== <code>isMissile</code> ===
'''isMissile''' : Boolean (read-only)
<code>true</code> if the ship is a missile, <code>false</code> otherwise.

=== <code>isPiloted</code> ===
'''isPiloted''' : Boolean (read-only)
<code>true</code> if the ship has a pilot on board, <code>false</code> otherwise. Generally- ships, stations and escape pods have pilots whereas cargo, rocks, missiles and buoys do not.

=== <code>isPirate</code> ===
'''isPirate''' : Boolean (read-only)
<code>true</code> if the ship is a pirate vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "pirate"</code>.

=== <code>isPirateVictim</code> ===
'''isPirateVictim''' : Boolean (read-only)
<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.

=== <code>isPolice</code> ===
'''isPolice''' : Boolean (read-only)
<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>.

=== <code>isRock</code> ===
'''isRock''' : Boolean (read-only)
<code>true</code> if the ship is a rock (i.e., has scan_class: <code>"CLASS_ROCK"</code>)

=== <code>isThargoid</code> ===
'''isThargoid''' : Boolean (read-only)
<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>.

=== <code>isTrader</code> ===
'''isTrader''' : Boolean (read-only)
<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.

=== <code>isTurret</code> ===
{{oolite-prop-added|1.79}}
'''isTurret''' : Boolean (read-only)
<code>true</code> if the ship is a plasma turret sub-entity, <code>false</code> otherwise.

=== <code>isWeapon</code> ===
'''isWeapon''' : Boolean (read-only)
<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.

=== <code>laserHeatLevel</code>* ===
{{Oolite-prop-added|1.77}}
'''laserHeatLevel''' : Number (read-only, 0 to 1)
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.
'''laserHeatLevelAft''' : Number (read-only, 0 to 1)
'''laserHeatLevelForward''' : Number (read-only, 0 to 1)
'''laserHeatLevelPort''' : Number (read-only, 0 to 1)
'''laserHeatLevelStarboard''' : Number (read-only, 0 to 1)
The temperature of specific laser mounts can also be queried.

=== <code>lightsActive</code> ===
'''lightsActive''' : Boolean (read-write)
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.

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 <code>false</code> in their ''shipdata.plist'' declarations.

=== <code>markedForFines</code> ===
{{oolite-prop-added|1.79}}
'''markedForFines''' : Boolean (read-only)
<code>true</code> if the ship has been marked for fines the next time it docks at this system's main station.

'''See also''' : [[#markTargetForFines|markTargetForFines()]]

=== <code>maxEscorts</code> ===
{{Oolite-prop-added|1.77}}
'''maxEscorts''' : Number (read/write)
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)

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

=== <code>maxPitch</code> ===
{{Oolite-prop-added|1.77}}
'''maxPitch''' : Number (read-only, read/write from 1.81)
The maximum pitch rate of the ship, in radians per second.

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

=== <code>maxRoll</code> ===
{{Oolite-prop-added|1.77}}
'''maxRoll''' : Number (read-only, read/write from 1.81)
The maximum roll rate of the ship, in radians per second.

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

=== <code>maxSpeed</code> ===
'''maxSpeed''' : Number (read-only, read/write from 1.81)
The ship’s maximum speed under normal power. Note that <code>[[#speed|speed]]</code> may exceed this when the [[Witch Fuel Injectors]] or [[Torus Drive]] are in use.

=== <code>maxThrust</code> ===
'''maxThrust''' : Number (read-only, read/write from 1.81)
The ship’s maximum <code>[[#thrust|thrust]]</code>. This value is the one defined as <code>thrust</code> in ''[[Shipdata.plist#thrust|shipdata.plist]]''.

=== <code>maxYaw</code> ===
{{Oolite-prop-added|1.77}}
'''maxYaw''' : Number (read-only, read/write from 1.81)
The maximum yaw rate of the ship, in radians per second.

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

=== <code>missileCapacity</code> ===
'''missileCapacity''' : Number (read-only integer)
The maximum number of missiles the ship can carry.

=== <code>missileLoadTime</code> ===
'''missileLoadTime''' : Number (read-write nonnegative)
The minimum amount of time between two missiles. The corresponding ''[[shipdata.plist]]'' key is <code>missile_load_time</code>.

=== <code>missiles</code> ===
'''missiles''' : Array (read-only array of [[Oolite JavaScript Reference: EquipmentInfo|EquipmentInfo]])
The ship’s loaded missiles.

=== <code>name</code> ===
'''name''' : String (read/write, read-only for player)
The name of the ship type (<code>name</code> key in [[shipdata.plist]]).

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

=== <code>parcelCount</code> ===
{{oolite-prop-added|1.77}}
'''parcelCount''' : Number (read-only integer)
The ship’s current number of parcels.

'''See also''': <code>[[Oolite JavaScript Reference: PlayerShip#addParcel|addParcel()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removeParcel|removeParcel()]]</code>

=== <code>parcels</code> ===
{{oolite-prop-added|1.77}}
'''parcels''' : Array (read-only NSDictionary)
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> 
For example, the information of the first contract can be obtained by:
player.ship.parcels[0].name
player.ship.parcels[0].start
player.ship.parcels[0].destination
player.ship.parcels[0].startName
player.ship.parcels[0].destinationName
player.ship.parcels[0].eta
player.ship.parcels[0].etaDescription
player.ship.parcels[0].fee // The final fee, paid out on successful delivery.

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.

'''See also''': <code>[[Oolite JavaScript Reference: PlayerShip#addParcel|addParcel()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removeParcel|removeParcel()]]</code>, <code>[[Oolite JavaScript Reference: Player#parcelReputation|parcelReputation]]</code>

=== <code>passengerCapacity</code> ===
'''passengerCapacity''' : Number (read-only integer)
The ship’s maximum passenger capacity.

'''See also''': <code>[[Passenger Berth]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#addPassenger|addPassenger()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removePassenger|removePassenger()]]</code>

=== <code>passengerCount</code> ===
'''passengerCount''' : Number (read-only integer)
The ship’s current number of passengers.

'''See also''': <code>[[Passenger Berth]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#addPassenger|addPassenger()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removePassenger|removePassenger()]]</code>

=== <code>passengers</code> ===
'''passengers''' : Array (read-only NSDictionary)
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> 
For example, the information of the first contract can be obtained by:
player.ship.passengers[0].name
player.ship.passengers[0].start
player.ship.passengers[0].destination
player.ship.passengers[0].startName
player.ship.passengers[0].destinationName
player.ship.passengers[0].eta
player.ship.passengers[0].etaDescription
player.ship.passengers[0].fee // The final fee, paid out on successful delivery.
player.ship.passengers[0].premium // The advance fee, already paid on acceptance of the contract.

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.

'''See also''': <code>[[Passenger Berth]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#addPassenger|addPassenger()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removePassenger|removePassenger()]]</code>, <code>[[Oolite JavaScript Reference: Player#passengerReputation|passengerReputation]]</code>

=== <code>pitch</code> ===
{{Oolite-prop-added|1.77}}
'''pitch''' : Number (read-only)
The rate of pitch of the ship in radians/second (positive for dive, negative for climb)

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

=== <code>portWeapon</code> ===
'''portWeapon''' : EquipmentType (read-only, read/write in 1.77)
The currently equipped port weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.

'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code>

=== <code>potentialCollider</code> ===
'''potentialCollider''' : [[Oolite JavaScript Reference: Entity|Entity]] (read-only)
The entity the ship is currently trying not to crash into, if any.

=== <code>primaryRole</code> ===
'''primaryRole''' : String (read/write, read-only for player)
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 <code>"pirate trader(0.5) escort"</code> and a ship of that type is spawned to be a trader, its <code>primaryRole</code> is <code>"trader"</code>, its <code>roles</code> are <code>["escort", "pirate", "trader"]</code> and its <code>roleWeights</code> are <code>{"escort":1, "pirate":1, "trader":0.5}</code>.

'''See also:''' <code>[[#roles|roles]]</code>, <code>[[#roleWeights|roleWeights]]</code>

=== <code>reportAIMessages</code> ===
'''reportAIMessages''' : Boolean (read/write)
Debugging facility: set to <code>true</code> to dump information about AI activity to the log.

=== <code>roleWeights</code> ===
'''roleWeights''' : Object (read-only)
The probabilities for each role in <code>[[#roles|roles]]</code>.

Example:
this.pirateProb = ship.roleWeights["pirate"]

'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roles|roles]]</code>

=== <code>roles</code> ===
'''roles''' : Array (read-only array of Strings)
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.

'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roleWeights|roleWeights]]</code>, <code>[[#hasRole|hasRole()]]</code>

=== <code>roll</code> ===
{{Oolite-prop-added|1.77}}
'''roll''' : Number (read-only, read/write for stations)
The rate of roll of the ship in radians/second (positive for anti-clockwise, negative for clockwise)

'''See also:''' <code>[[#maxRoll|maxRoll]]</code>, <code>[[Oolite JavaScript Reference: Station#roll|station.roll]]</code>

=== <code>savedCoordinates</code> ===
'''savedCoordinates''' : [[Oolite JavaScript Reference: Vector|Vector]] (read-write)
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>

=== <code>scanDescription</code> ===
{{Oolite-prop-added|1.81}}
'''scanDescription''' : String (read/write)
The description of the ship in the "legal status" text shown by the [[Scanner Targeting Enhancement]]. If this is <code>null</code> then the default text for the ship's scan class and bounty level will be shown.

=== <code>scannerDisplayColor1</code> ===
'''scannerDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
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.

'''See also:''' <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code>, <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code>

=== <code>scannerDisplayColor2</code> ===
'''scannerDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
The second scanner colour. If both <code>scannerDisplayColor1</code> and <code>scannerDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.

'''See also:''' <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code>, <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code>

=== <code>scannerHostileDisplayColor1</code> ===
{{oolite-prop-added|1.81}}
'''scannerHostileDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
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.

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.

'''See also:''' <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code>, <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code>

=== <code>scannerHostileDisplayColor2</code> ===
{{oolite-prop-added|1.81}}
'''scannerHostileDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
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.

'''See also:''' <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code>, <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code>

=== <code>scannerRange</code> ===
'''scannerRange''' : Number (read-only)
The range of the ship’s scanner.

=== <code>script</code> ===
'''script''' : [[Oolite JavaScript Reference: Script|Script]] (read-only)
The ship’s script.

=== <code>scriptedMisjump</code> ===
'''scriptedMisjump''' : Boolean (read/write)
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.

=== <code>scriptedMisjumpRange</code> ===
{{oolite-prop-added|1.77}}
'''scriptedMisjumpRange''' : Number (read/write)
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>.

=== <code>scriptInfo</code> ===
'''scriptInfo''' : Object (read-only)
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. 
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).

=== <code>shipClassName</code> ===
{{oolite-prop-added|1.79}}
'''shipClassName''' : String (read/write)
The name of the ship class (e.g. <code>"Python"</code>)

=== <code>shipUniqueName</code> ===
{{oolite-prop-added|1.79}}
'''shipUniqueName''' : String (read/write)
The name of this specific ship (e.g. <code>"Sunrise of Lave"</code>)

=== <code>speed</code> ===
'''speed''' : Number (read-only)
The ship’s current speed.

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

=== <code>starboardWeapon</code> ===
'''starboardWeapon''' : EquipmentType (read-only, read/write in 1.77)
The currently equipped forward weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.

'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>

=== <code>subEntities</code> ===
'''subEntities''' : Array (read-only array of Ships)
The ships subentities, or <code>null</code> if it has none. Special subentities such as flashers and exhaust plumes are not included.

'''See also:''' <code>[[#isFrangible|isFrangible]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code>

=== <code>subEntityCapacity</code> ===
'''subEntityCapacity''' : Number (read-only integer)
The original number of subentities on the ship.

'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code>

=== <code>subEntityRotation</code> ===
{{oolite-prop-added|1.81}}
'''subEntityRotation''' : Quaternion (read/write)
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.

=== <code>sunGlareFilter</code> ===
{{oolite-prop-added|1.79}}
'''sunGlareFilter''' : Number (read/write)
The strength of the sun glare filter on this ship. It must be in the range 0 to 1 (0 is no filter).

=== <code>target</code> ===
'''target''' : Ship (read-write)
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.

=== <code>temperature</code> ===
'''temperature''' : Number (read/write)
The ship’s temperature, normalized such that a temperature of 1.0 is the level at which a ship starts taking heat damage.

=== <code>thrust</code> ===
'''thrust''' : Number (read/write for NPCs, read-only for player before 1.81)
The ship’s thrust, ranging from 0 to <code>[[#maxThrust|maxThrust]]</code>. This value determines how fast the ship accelerates or decelerates, specified in m/s².

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

=== <code>thrustVector</code> ===
'''thrustVector''' : Vector3D (read-only)
The inertialess velocity generated by the engines.

'''See also:''' <code>[[#thrust|thrust]]</code>, <code>[[#velocity|velocity]]</code>

=== <code>trackCloseContacts</code> ===
'''trackCloseContacts''' : Boolean (read/write)
If <code>true</code>, AI events are generated for near collisions.

=== <code>vectorForward</code> ===
'''vectorForward''' : Vector3D (read-only)
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>.

=== <code>vectorRight</code> ===
'''vectorRight''' : Vector3D (read-only)
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>.

=== <code>vectorUp</code> ===
'''vectorUp''' : Vector3D (read-only)
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>.

=== <code>velocity</code> ===
'''velocity''' : Vector3D (read/write)
The ship’s velocity.

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

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

=== <code>weaponFacings</code> ===
{{Oolite-prop-added|1.77}}
'''weaponFacings''' : Number (read-only, integer in range 0-15)
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: 
1 - fore 
2 - aft 
4 - port 
8 - starboard

=== <code>weaponPosition*</code> ===
{{Oolite-prop-added|1.77}}
'''weaponPositionAft''' : Vector (read-only)
'''weaponPositionForward''' : Vector (read-only)
'''weaponPositionPort''' : Vector (read-only)
'''weaponPositionStarboard''' : Vector (read-only)

{{Oolite-prop-added|1.83}}
'''weaponPositionAft''' : Array of Vectors (read-only)
'''weaponPositionForward''' : Array of Vectors (read-only)
'''weaponPositionPort''' : Array of Vectors (read-only)
'''weaponPositionStarboard''' : Array of Vectors (read-only)

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.

In 1.83 this property changed syntax to become an array of vectors, as ships can now have multiple mounts per facing.

=== <code>weaponRange</code> ===
'''weaponRange''' : Number (read-only)
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. 
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. 
(Turrets are secondary weapons with a maximum range of 6000)

=== <code>withinStationAegis</code> ===
'''withinStationAegis''' : Boolean (read-only)
<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).

=== <code>yaw</code> ===
{{Oolite-prop-added|1.77}}
'''yaw''' : Number (read-only)
The rate of yaw of the ship in radians/second (positive for right, negative for left)

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

== Methods ==
=== <code>abandonShip</code> ===
function '''abandonShip'''() : Boolean
Returns <code>true</code> when the ship has an escape pod. It will launch all escape pods on board leaving the ship behind as a empty hulk (<code>scanClass === "CLASS_CARGO"</code>). This command does nothing when no escape pod is present. 
Presence of an escape pod can be tested with: <code>equipmentStatus("EQ_ESCAPE_POD") === "EQUIPMENT_OK"</code>

=== <code>addCollisionException</code> ===
{{oolite-method-added|1.81}}
function '''addCollisionException'''(exception : Ship)
Prevented this ship and the selected ship from colliding. See [[#collisionExceptions|collisionExceptions]] and [[#removeCollisionException|removeCollisionException]].

Prevention from collision will specifically prevent the following:

* the ships colliding with each other and suffering collision damage and/or momentum change
* the ships receiving collision warning events if they come close to each other
* 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

This has no useful effect when applied to a subentity.

Adding a collision exception which already exists has no effect but will not cause an error.

=== <code>addDefenseTarget</code>===
{{oolite-method-added|1.77}}
function '''addDefenseTarget'''(target : Ship)
Adds the target ship to this ship's list of point [[#defenseTargets|defense targets]], if it isn't already.

=== <code>adjustCargo</code>===
{{oolite-method-added|1.81}}
function '''adjustCargo'''(commodity : String, amount : Number) : Boolean
Adjust the quantity of the specified commodity carried by the ship. Amount may be negative to remove cargo. The method will return <code>false</code> if the operation would fail due to insufficient free space or carried cargo and will not make a partial adjustment in this case.

This method is for non-player ships. For the player ship, use <code>[[Oolite JavaScript Reference: PlayerShip#manifest|manifest]]</code>.

'''See also''': <code>[[#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[#cargoList|cargoList]]</code>, <code>[[#setCargoType|setCargoType()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>awardEquipment</code> ===
function '''awardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean
Adds the given piece of equipment to the ship, if possible, returning <code>true</code> if successful and <code>false</code> otherwise.

Example:
ship.awardEquipment("EQ_ECM");

'''See also:''' <code>[[#canAwardEquipment|canAwardEquipment()]]</code>, <code>[[#removeEquipment|removeEquipment()]]</code>

=== <code>canAwardEquipment</code> ===
function '''canAwardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean
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.

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

=== <code>becomeCascadeExplosion</code> ===
{{oolite-method-added|1.79}}
function '''becomeCascadeExplosion'''()
This method causes the ship to explode as if it were hit by a quirium cascade.

=== <code>broadcastCascadeImminent</code> ===
{{oolite-method-added|1.79}}
function '''broadcastCascadeImminent'''()
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>

=== <code>broadcastDistressMessage</code> ===
{{oolite-method-added|1.79}}
function '''broadcastDistressMessage'''()
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.

=== <code>checkCourseToDestination</code> ===
{{oolite-method-added|1.79}}
function '''checkCourseToDestination'''()
Checks the line between the ship's current position and its destination, and returns either <code>null</code> or an Entity (usually a planet, sun or other ship) that this ship would risk collision with if it travelled along that course.

'''See also''': [[#getSafeCourseToDestination|getSafeCourseToDestination()]]

=== <code>checkScanner</code> ===
{{oolite-method-added|1.79}}
function '''checkScanner'''([poweredOnly : Boolean]) : Array
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 <code>true</code>, then only powered objects will be returned (i.e. ships with a scan class other than <code>"CLASS_CARGO"</code> or <code>"CLASS_ROCK"</code>).

This method is usually considerably quicker than <code>[[Oolite JavaScript Reference: System#filteredEntities|system.filteredEntities()]]</code> and similar methods, with little loss of accuracy, though it is still advisable to cache the result for a while before re-scanning.

=== <code>clearDefenseTargets</code>===
{{oolite-method-added|1.77}}
function '''clearDefenseTargets'''()
Clears the ship's list of point [[#defenseTargets|defense targets]].

=== <code>commsMessage</code> ===
function '''commsMessage'''(message : String [,target : Ship])
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.

'''See also''': <code>[[Oolite JavaScript Reference: Player#commsMessage|player.commsMessage()]]</code>

=== <code>damageAssessment</code> ===
{{oolite-method-added|1.79}}
function '''damageAssessment'''() : Number
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.

=== <code>dealEnergyDamage</code>===
{{oolite-method-added|1.77}}
function '''dealEnergyDamage'''(damage : Number, idealRange : Number [, velocityBias : Number])
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:
* Further away than MAX_SCANNER_RANGE (25.6km): deal no damage
* 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
* 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.

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):
* 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
* 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.
* 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)2, so the Anaconda takes about 1.5 points of damage.
* A missile fired at something else detonates 500m away from a Sidewinder. The inverse-square rule divides the damage by (500 / 32.5)2, 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.

=== <code>deployEscorts</code> ===
function '''deployEscorts'''()
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 method has already been called for the current target without meanwhile being called for a different target.

=== <code>dockEscorts</code> ===
function '''dockEscorts'''()
Dock the ship’s deployed escorts, if any.

=== <code>dumpCargo</code> ===
function '''dumpCargo'''([amount : Number, commodity: String]) : Ship
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.

In 1.79 or later, multiple items may be scheduled for dumping by passing the number as a parameter.

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.

'''See also:''' <code>[[#ejectItem|ejectItem]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code>

=== <code>ejectItem</code> ===
function '''ejectItem'''(role : String) : Ship
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 <code>scanClass</code> of the ejected item will always be <code>"CLASS_CARGO"</code>.

'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code>

=== <code>ejectSpecificItem</code> ===
function '''ejectSpecificItem'''(itemKey : String) : Ship
Spawns a ship with the ''shipdata.plist'' key <code>itemKey</code> immediately behind the ship, with a slight backwards velocity. The <code>scanClass</code> of the ejected item will always be <code>"CLASS_CARGO"</code>.

'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectItem|ejectItem]]</code>

=== <code>enterWormhole</code> ===
{{oolite-method-added|1.79}}
function '''enterWormhole'''([wormhole : Wormhole])
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.

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.

=== <code>equipmentStatus</code> ===
function '''equipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]] [, multiple : Boolean]) : String or Object
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>.

In 1.81 and later, if the optional <code>multiple</code> parameter is set to <code>true</code>, it will instead return an object in this format:
{
"EQUIPMENT_OK": 3.
"EQUIPMENT_DAMAGED": 2
}
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.

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

=== <code>exitAI</code> ===
function '''exitAI'''()
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.

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code>

=== <code>exitSystem</code> ===
function '''exitSystem'''([targetSystem : Number]) : Boolean
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.

This method can fail for various reasons, in which case it returns <code>false</code>. It always fails for the player ship.

=== <code>explode</code> ===
function '''explode'''()
Causes the ship to explode. Works on all ships, including the main station and the player except when docked.

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

=== <code>fireECM</code> ===
function '''fireECM'''()
activates an ecm burst, identical as the AI command.

=== <code>findNearestStation</code> ===
function '''findNearestStation'''()
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>.

=== <code>fireMissile</code> ===
function '''fireMissile'''([missile]) : Ship
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.

=== <code>getSafeCourseToDestination</code> ===
{{oolite-method-added|1.79}}
function '''getSafeCourseToDestination'''()
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.

'''See also''': [[#checkCourseToDestination|checkCourseToDestination()]]

=== <code>getMaterials</code> ===
{{oolite-method-added|1.77}}
function '''getMaterials'''() : Object
getMaterials() returns the ship's current materials dictionary, or if none present an empty dictionary.

'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code>

=== <code>getShaders</code> ===
{{oolite-method-added|1.77}}
function '''getShaders'''() : Object
getShaders() returns the ship's current shaders dictionary, or if none present an empty dictionary.

'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code>

=== <code>hasEquipmentProviding</code> ===
{{oolite-method-added|1.81}}
function '''hasEquipmentProviding'''(key : String) : Boolean
This method returns <code>true</code> if the ship has any equipment providing the <code>key</code> equipment type, and <code>false</code> otherwise.

=== <code>hasRole</code> ===
function '''hasRole'''(role : String) : Boolean
Returns <code>true</code> if the ship has <code>role</code> among its roles, <code>false</code> otherwise.

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

=== <code>markTargetForFines</code> ===
{{oolite-method-added|1.79}}
function '''markTargetForFines()'''
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.

=== <code>notifyGroupOfWormhole</code> ===
{{oolite-method-added|1.79}}
function '''notifyGroupOfWormhole()'''
Tells the ship's group about a wormhole (usually the one this ship has just entered). Causes a <code>[[Oolite JavaScript Reference: Ship script event handlers#wormholeSuggested|wormholeSuggested]]</code> event to occur in the scripts of other group members.

=== <code>offerToEscort</code> ===
{{oolite-method-added|1.79}}
function '''offerToEscort(mother : Ship)'''
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.

=== <code>perform*</code> ===
Each of these methods 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.

==== <code>performAttack</code> ====
{{oolite-method-added|1.79}}
function '''performAttack()'''
Attack the current target with available weapons.

==== <code>performCollect</code> ====
{{oolite-method-added|1.79}}
function '''performCollect()'''
Attempt to scoop up the current target. If the current target is not scoopable, it will be lost.

==== <code>performEscort</code> ====
{{oolite-method-added|1.79}}
function '''performEscort()'''
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.

==== <code>performFaceDestination</code> ====
{{oolite-method-added|1.79}}
function '''performFaceDestination()'''
Come to a stop, and turn to face the current destination coordinates.

==== <code>performFlee</code> ====
{{oolite-method-added|1.79}}
function '''performFlee()'''
Flee from the current target, using injectors if possible, until it is out of scanner range.

==== <code>performFlyToRangeFromDestination</code> ====
{{oolite-method-added|1.79}}
function '''performFlyToRangeFromDestination()'''
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.

==== <code>performHold</code> ====
{{oolite-method-added|1.79}}
function '''performHold()'''
Come to a stop, and continually turn to face the current target

==== <code>performIdle</code> ====
{{oolite-method-added|1.79}}
function '''performIdle()'''
Cancel any current turns to return to level flight, then move forward at current speed.

==== <code>performIntercept</code> ====
{{oolite-method-added|1.79}}
function '''performIntercept()'''
Fly to intercept (i.e. ram) the current target.

==== <code>performLandOnPlanet</code> ====
{{oolite-method-added|1.79}}
function '''performLandOnPlanet()'''
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.

==== <code>performMining</code> ====
{{oolite-method-added|1.79}}
function '''performMining()'''
Attack the current target with a mining laser. This does not count as hostile behaviour, so cannot be used except on rocks.

==== <code>performScriptedAI</code> ====
{{oolite-method-added|1.79}}
function '''performScriptedAI()'''
Request flight instructions from a [[OXP_Scripted_AI|scripted AI]] callback each frame.

==== <code>performScriptedAttackAI</code> ====
{{oolite-method-added|1.79}}
function '''performScriptedAttackAI()'''
Request flight instructions, including weapons fire, from a [[OXP_Scripted_AI|scripted AI]] callback each frame.

==== <code>performStop</code> ====
{{oolite-method-added|1.79}}
function '''performStop()'''
Come to a complete halt

==== <code>performTumble</code> ====
{{oolite-method-added|1.79}}
function '''performTumble()'''
Come to a complete halt and rotate randomly.

=== <code>reactToAIMessage</code> ===
function '''reactToAIMessage'''(message : String)
Immediately perform the specified handler in the ship’s current AI state.

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

=== <code>recallDockingInstructions</code> ===
{{oolite-method-added|1.79}}
function '''recallDockingInstructions'''() : Object
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.

'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#requestDockingInstructions|requestDockingInstructions]]</code>

=== <code>remove</code> ===
function '''remove'''([suppressDeathEvent : Boolean])
Immediately removes the ship from the universe. Works on all ships except the player, including the main station. 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 <code>true</code>.

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

=== <code>removeCollisionException</code> ===
{{oolite-method-added|1.81}}
function '''removeCollisionException'''(exception : Ship)
Allow this ship and the selected ship to collide again. See [[#collisionExceptions|collisionExceptions]] and [[#addCollisionException|addCollisionException]].

Removing a collision exception which does not exist has no effect but will not cause an error.

=== <code>removeDefenseTarget</code>===
{{oolite-method-added|1.79}}
function '''removeDefenseTarget'''(target : Ship)
Ensures that the target ship is not on this ship's list of point [[#defenseTargets|defense targets]].

=== <code>removeEquipment</code> ===
function '''removeEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]])
Removes the given piece of equipment from the ship.
This method 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.

Note that in Oolite prior to 1.76.1 there was a bug which could sometimes cause the game to crash if this method 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

Example:
ship.removeEquipment("EQ_ECM");

=== <code>requestDockingInstructions</code> ===
{{oolite-method-added|1.79}}
function '''requestDockingInstructions'''() : Object
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.

'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code>

=== <code>requestHelpFromGroup</code> ===
{{oolite-method-added|1.79}}
function '''requestHelpFromGroup'''()
This method 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.

=== <code>restoreSubEntities</code> ===
function '''restoreSubEntities'''() : Boolean
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.

'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#isFrangible|isFrangible]]</code>

=== <code>selectNewMissile</code> ===
function '''selectNewMissile'''() : equipmentKey
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.
e.g.
this.ship.awardEquipment(this.ship.selectNewMissile())
will automatically add the 'right type' of missile to a ship, i.e. one that its captain would normally choose.

=== <code>sendAIMessage</code> ===
function '''sendAIMessage'''(message : String)
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.

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

=== <code>setAI</code> ===
function '''setAI'''(AIName : String)
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).

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>

=== <code>setBounty</code> ===
{{oolite-method-added|1.77}}
function '''setBounty'''(bounty : Number, reason : String)
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()]].

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

=== <code>setCargo</code> ===
function '''setCargo'''(commodity : String [, count : Number]) : Boolean
Attempts to create <code>count</code> weight units of the <code>commodity</code> specified for a cargo barrel. This cannot be used to set cargo for ships. When more units are defined than 1 ton, the count is reduced to 1 ton. It returns <code>false</code> when the selected commodity is unknown. If <code>count</code> is not specified, <code>1</code> will be assumed.

=== <code>setCargoType</code> ===
{{oolite-method-added|1.79}}
function '''setCargoType'''(commodityType : String) : Boolean
Attempts to set the ship's cargo hold to contain commodities of the specified type, discarding any cargo already present. This should generally only be used immediately after a ship is spawned. Valid commodity types are:
*<code>"SCARCE_GOODS"</code>: goods which are likely to be rare in the current system, usually legal
*<code>"PLENTIFUL_GOODS"</code>: goods which are likely to be plentiful in the current system, usually legal
*<code>"MEDICAL_GOODS"</code>: narcotics (used for the Moray Medical Boat)
*<code>"ILLEGAL_GOODS"</code>: various goods likely to be rare in the current system, with a strong bias towards contraband
*<code>"PIRATE_GOODS"</code>: similar to <code>"ILLEGAL_GOODS"</code> but the total amount carried will be lower
This will return <code>false</code> 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.

=== <code>setCrew</code> ===
{{oolite-method-added|1.79}}
function '''setCrew'''(Object) : Boolean
Sets the ship's crew to one represented by the given object (or sets the ship to uncrewed if <code>null</code> is given as a parameter). Returns <code>true</code> if this succeeds, <code>false</code> 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:
* origin system
* random seed
* role
* the rest
You can therefore set a random seed or role to get particular behaviour, and use the other keys to override it.

At the moment this method only sets the first crew member (the pilot of the ship) in [[Oolite JavaScript Reference: Ship#crew|crew]][0] .

=== <code>setEquipmentStatus</code> ===
function '''setEquipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]], statusKey : String)
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>.

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

'''See also:''' <code>[[#equipmentStatus|equipmentStatus()]]</code>, <code>[[Oolite JavaScript Reference: EquipmentInfo#canBeDamaged|EquipmentInfo.canBeDamaged]]</code>for equipment that cannot be damaged

=== <code>setMaterials</code> ===
function '''setMaterials'''(materialDictionary : Object [, shaderDictionary : Object]) : Boolean
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.

'''Example:'''
this.ship.setMaterials({"my_ship_diffuse.png": { diffuse_map: "my_ship_damaged_diffuse.png" }});

'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code>

=== <code>setScript</code> ===
function '''setScript'''(scriptName : String)
Set, or completely replace, the javascript code associated to a ship entity.

=== <code>setShaders</code> ===
function '''setShaders'''(shaderDictionary : Object) : Boolean
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.

'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code>

=== <code>spawn</code> ===
function '''spawn'''(role : String [, count : Number]) : Array
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.

<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:
* The spawned ships inherit most of the temperature of the parent.
* 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.
* <code>spawn()</code> does not set up escorts for the new ships, or generate witchspace effects, or do any special AI handling.

=== <code>spawnOne</code> ===
function '''spawnOne'''(role : String) : Ship
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.

=== <code>switchAI</code> ===
function '''switchAI'''(AIName : String)
Set the current AI, exiting the old one. Equivalent to the <code>[[AI_methods|switchAITo]]:</code> AI method. May not be used on player.

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>

=== <code>threatAssessment</code> ===
{{oolite-method-added|1.79}}
function '''threatAssessment'''(full : Boolean) : Number
Returns a number indicating the relative strength of the ship. If the 'full' parameter is <code>true</code>, 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.

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.

=== <code>throwSpark</code> ===
{{oolite-method-added|1.79}}
function '''throwSpark'''()
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.

=== <code>updateEscortFormation</code> ===
function '''updateEscortFormation'''()
Request that the game updates the target positions for the ship’s escorts by calling the ship’s script’s <code>coordinatesForEscortPosition()</code> method.

== Static Methods ==
=== <code>keys</code> ===
{{Oolite-method-added|1.79}}
function '''keys'''() : Array
Returns all dataKeys of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.

'''Example:'''
var dataKeysArray = Ship.keys();

=== <code>keysForRole</code> ===
{{Oolite-method-added|1.79}}
function '''keysForRole'''(role : String) : Array
Returns all dataKeys of ships defined in all [[shipdata.plist]] which contains the given role.

'''Example:'''
var role = "trader";
var roleKeys = Ship.keysForRole( role );
log("keysForRole", role + ": " + roleKeys );

=== <code>roleIsInCategory</code> ===
{{Oolite-method-added|1.79}}
function '''roles'''(role : String, category : String) : Boolean
Returns whether the role given is in a particular category as defined in [[role-categories.plist]]

'''Example:'''
Ship.roleIsInCategory("trader","oolite-pirate-victims"); // true

=== <code>roles</code> ===
{{Oolite-method-added|1.79}}
function '''roles'''() : Array
Returns all roles of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.

'''Example:'''
var roles = Ship.roles();
for( var i = 0; i < roles.length; i++ ) {
var roleKeys = Ship.keysForRole( roles[i] );
log("roles", i + ". "+roles[i] + ": " + roleKeys );
}

=== <code>shipDataForKey</code> ===
{{Oolite-method-added|1.79}}
function '''shipDataForKey'''(datakey : String) : Object
Returns an object containing a representation of the raw [[shipdata.plist]] entry for a given data key, or <code>null</code> 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.

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.

'''Example:'''
var shipdata = Ship.shipDataForKey("cobra3-trader");
log("test",shipdata["name"]); // "Cobra Mark III"
log("test",shipdata["ship_class_name"]); // undefined
log("test",shipdata["ship_unique_name"]); // undefined
log("test",shipdata["display_name"]); // undefined

===<code>setShipDataForKey</code>===
{{Oolite-method-added|1.91}}
function '''setShipDataForKey'''(datakey : String, newShipData : Object)
This method modifies or adds properties of a ship class specified by the datakey parameter. The newShipData parameter can be an existing property defined in shipdata.plist or a new one.

'''Example:'''
Ship.setShipDataForKey ("cobra3-trader", {name: "Cobra trader variant"})
var shipdata = Ship.shipDataForKey ("cobra3-trader")
log ("test", shipdata ["name"])

'''See also''': [http://www.aegidian.org/bb/viewtopic.php?p=274534#p274534 bulletin board post by Tsoj]

==See also==
*[[Shipdata.plist]]

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Ship

2022-10-29T16:42:56Z

Massively Locked: /* maxSpeed */ fixed link

'''Prototype:''' <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> 
'''Subtypes:''' <code>[[Oolite JavaScript Reference: Station|Station]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code>

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 an <code>Entity</code> and several others.

<code>[[Oolite JavaScript Reference: Station|Stations]]</code> and the <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code> are types of ship. Note that these more specific types have additional properties and methods.

== Properties ==
=== <code>accuracy</code> ===
{{Oolite-prop-added|1.77}}
'''accuracy''' : Number (read/write, read-only and irrelevant for player ship)
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.

For missiles, this affects the missile tracking, with 0 being the default value.

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.

=== <code>aftWeapon</code> ===
'''aftWeapon''' : EquipmentType (read-only, read/write in 1.77)
The currently equipped aft weapon, or <code>null</code>.

'''See also:''' <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code>

=== <code>AI</code> ===
'''AI''' : String (read-only)
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>"

'''See also:''' <code>[[#AIState|AIState]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AIScript|AIScript]]</code>

=== <code>AIFoundTarget</code> ===
{{oolite-prop-added|1.77}}
'''AIFoundTarget''' : Entity (read/write, read-only for player)
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.

=== <code>AIPrimaryAggressor</code> ===
{{oolite-prop-added|1.77}}
'''AIPrimaryAggressor''' : Entity (read/write, read-only for player)
The "primary aggressor" of the ship's AI. Often the last ship to attack this ship.

=== <code>AIScript</code> ===
{{oolite-prop-added|1.79}}
'''AIScript''' : String (read-only)
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>"

'''See also:''' <code>[[#AIScriptWakeTime|AIScriptWakeTime]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AI|AI]]</code>

=== <code>AIScriptWakeTime</code> ===
{{oolite-prop-added|1.79}}
'''AIScriptWaketime''' : Number (read-write)
The next game time at which the ship's Javascript-based AI script will receive an <code>aiAwoken</code> event.

=== <code>AIState</code> ===
'''AIState''' : String (read/write, read-only for player)
The ship’s plist AI’s current state.

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#reactToAIMessage|reactToAIMessage()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code>

=== <code>alertCondition</code> ===
'''alertCondition''' : Number (read-only integer)
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.

'''See also:''' [[Oolite JavaScript Reference: Station#alertCondition|station.alertCondition]]

=== <code>autoAI</code> ===
{{oolite-prop-added|1.79}}
'''autoAI''' : Boolean (read-only)
The value of the <code>"auto_ai"</code> shipdata key. If this is <code>true</code>, 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 <code>false</code>, the ship's provider would prefer you not to alter the AI of this ship but to use it as-is.

=== <code>autoWeapons</code> ===
{{oolite-prop-added|1.79}}
'''autoWeapons''' : Boolean (read-only)
The value of the <code>"auto_weapons"</code> shipdata key. If this is <code>true</code>, 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 <code>false</code>, the ship's provider would prefer you not to alter the properties of this ship but to use it as-is.

=== <code>beaconCode</code> ===
'''beaconCode''' : String (read-only in 1.76, read-write from 1.77)
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 cannot be changed by script for either the player's ship or the main station.

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

=== <code>beaconLabel</code> ===
{{oolite-prop-added|1.79}}
'''beaconLabel''' : String (read/write, read-only for player)
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.

=== <code>boundingBox</code> ===
{{Oolite-prop-added|1.77}}
'''boundingBox''' : Vector (read-only)
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.

Vector components match the standard model order - <code>x</code> is width, <code>y</code> is height, <code>z</code> is length.

=== <code>bounty</code> ===
'''bounty''' : Number (read/write integer)
The bounty on the ship.

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.

=== <code>cargoList</code> ===
{{oolite-prop-added|1.79}}
'''cargoList''' : Array (read-only)
A list of the ship's current cargo, grouped by cargo type.

An item looks like this:
{
unit: "t",
displayName: "Liquor/Wines",
commodity: "liquor_wines",
quantity: 3
}

This property is for non-player ships. For the player ship, use <code>[[Oolite JavaScript Reference: Manifest#list|manifest.list]]</code>.

'''See also''': <code>[[#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[#adjustCargo|adjustCargo()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>cargoSpaceAvailable</code> ===
'''cargoSpaceAvailable''' : Number (read-only integer)
The ship’s available cargo space, in tons.

'''See also''': <code>[[#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#manifest|manifest]]</code> (for the player ship), <code>[[#cargoList|cargoList]]</code> (for non-player ships), <code>[[#adjustCargo|adjustCargo()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>cargoSpaceCapacity</code> ===
'''cargoSpaceCapacity''' : Number (read-only in 1.80, read/write in 1.81, integer)
The ship’s cargo capacity, in tons.

'''See also''': <code>[[#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#manifest|manifest]]</code> (for the player ship), <code>[[#cargoList|cargoList]]</code> (for non-player ships), <code>[[#adjustCargo|adjustCargo()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>cargoSpaceUsed</code> ===
'''cargoSpaceUsed''' : Number (read-only integer)
The ship’s current cargo, in tons.

'''See also''': <code>[[#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#manifest|manifest]]</code> (for the player ship), <code>[[#cargoList|cargoList]]</code> (for non-player ships), <code>[[#adjustCargo|adjustCargo()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>collisionExceptions</code> ===
{{oolite-prop-added|1.81}}
'''collisionExceptions''' : Array (read-only)
A list of ships this ship is currently prevented from colliding with. See [[#addCollisionException|addCollisionException]] and [[#removeCollisionException|removeCollisionException]].

=== <code>commodity</code> ===
{{Oolite-prop-added|1.77}}
'''commodity''' : String (read-only)
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".

=== <code>commodityAmount</code> ===
{{Oolite-prop-added|1.77}}
'''commodityAmount''' : Number (read-only)
The amount of commodity in a cargo container. (not the number of containers in a ship)

=== <code>contracts</code> ===
'''contracts''' : Array (read-only NSDictionary)
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> 

For example, the information of the first contract can be obtained by:
player.ship.contracts[0].commodity
player.ship.contracts[0].quantity
player.ship.contracts[0].description
player.ship.contracts[0].start
player.ship.contracts[0].destination
player.ship.contracts[0].startName
player.ship.contracts[0].destinationName
player.ship.contracts[0].eta // Estimated Time of Arrival.
player.ship.contracts[0].etaDescription
player.ship.contracts[0].fee // The profit of the contract, paid out on successful delivery.
player.ship.contracts[0].premium // The sum paid to obtain the goods and paid back on successful delivery.

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.

'''See also''': <code>[[Oolite JavaScript Reference: PlayerShip#awardContract|awardContract()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removeContract|removeContract()]]</code>, <code>[[Oolite JavaScript Reference: Player#contractReputation|contractReputation]]</code>

=== <code>cloakAutomatic</code> ===
'''cloakAutomatic''' : Boolean (read/write)
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>.

=== <code>crew</code> ===
{{oolite-prop-added|1.79}}
'''crew''' : Array (read-only)
An array containing the ship's crew. Each crew member is represented as a dictionary:
{
"description":"a small yellow horned humanoid from Malama",
"name":"Masten Onlo",
"homeSystem":49,
"insuranceCredits":500,
"species":"small yellow horned humanoid",
"legalStatus":0
}

Note that in current Oolite versions ships only have a single crew member defined.

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

=== <code>cruiseSpeed</code> ===
'''cruiseSpeed''' : Number (read-only nonnegative)
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.

=== <code>currentWeapon</code> ===
{{oolite-prop-added|1.77}}
'''currentWeapon''' : EquipmentType (read/write)
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.

=== <code>dataKey</code> ===
{{Oolite-prop-added|1.77}}
'''dataKey''' : String (read-only)
The ship data key used to define this ship (e.g. <code>"adder-player"</code> or <code>"coriolis-station"</code>)

=== <code>defenseTargets</code> ===
{{Oolite-prop-added|1.77}}
'''defenseTargets''' : Array (read-only)
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.

'''See also:''' <code>[[#addDefenseTarget|addDefenseTarget]]</code>, <code>[[#clearDefenseTargets|clearDefenseTargets]]</code>

=== <code>desiredRange</code> ===
{{Oolite-prop-added|1.77}}
'''desiredRange''' : Number (read/write nonnegative, read-only for player)
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.

=== <code>desiredSpeed</code> ===
'''desiredSpeed''' : Number (read/write nonnegative, read-only for player)
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>.

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

=== <code>destination</code> ===
{{Oolite-prop-added|1.77}}
'''destination''' : Vector (read/write, read-only for player)
The destination coordinates for the AI, used in behaviours such as <code>performFlyToRangeFromDestination</code>.

=== <code>destinationSystem</code> ===
{{Oolite-prop-added|1.79}}
'''destinationSystem''' : Number (read/write)
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.

=== <code>displayName</code> ===
'''displayName''' : String (read/write, read-only for player)
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 <code>[[#shipClassName|shipClassName]]</code> and <code>[[#shipUniqueName|shipUniqueName]]</code>.

=== <code>dockedStation</code> ===
'''dockedStation''' : [[Oolite_JavaScript_Reference:_Station | Station]]
The Station the ship is currently docked to.

=== <code>dockingInstructions</code> ===
{{oolite-prop-added|1.79}}
'''dockingInstructions''' : Object (read-only)
If the ship is currently attempting to dock with a station, this describes the next step on its docking procedure

{
station: [Station "Coriolis Station" "Coriolis Station" position: (-31043.6, -94232.3, 619036) scanClass: CLASS_STATION status: STATUS_ACTIVE],
match_rotation: 0,
ai_message: "APPROACH_COORDINATES",
speed: 512,
destination: {
x: -28033.37401563089,
y: -92813.76688970842,
z: 622226.0625336492
},
range: 96
}

'''See also:''' <code>[[#requestDockingInstructions|requestDockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code>

=== <code>energyRechargeRate</code> ===
{{Oolite-prop-added|1.79}}
'''energyRechargeRate''' : Number (read-only, read/write from 1.81)
The rate at which energy is replenished in every second. The corresponding ''[[shipdata.plist]]'' key is <code>energy_recharge_rate</code>.

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.

=== <code>entityPersonality</code> ===
'''entityPersonality''' : Number (read-only integer, read/write in 1.81 onwards)
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]].

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.

=== <code>equipment</code> ===
'''equipment''' : Array of [[Oolite JavaScript Reference: EquipmentInfo|EquipmentInfo]] (read-only)
The equipment a ship is carrying.

=== <code>escortGroup</code> ===
'''escortGroup''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]
The ship’s deployed escorts.

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

=== <code>escorts</code> ===
'''escorts''' : Array (read-only array of [[Oolite JavaScript Reference: Entity|Entity]]s)
The ship’s deployed escorts.

=== <code>exhaustEmissiveColor</code> ===
{{Oolite-prop-added|1.79}}
'''exhaustEmissiveColor''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
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.

=== <code>exhausts</code> ===
{{Oolite-prop-added|1.79}}
'''exhausts''' : Array (read-only)
An array of the ship's [[Oolite JavaScript Reference: ExhaustPlume|ExhaustPlume]] subentities.

=== <code>flashers</code> ===
{{Oolite-prop-added|1.79}}
'''flashers''' : Array (read-only)
An array of the ship's [[Oolite JavaScript Reference: Flasher|Flasher]] subentities.

=== <code>forwardWeapon</code> ===
'''forwardWeapon''' : EquipmentType (read-only, read/write in 1.77)
The currently equipped forward weapon, or <code>null</code>.

'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code>

=== <code>fuel</code> ===
'''fuel''' : Number (read/write)
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.

'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#fuelLeakRate|PlayerShip.fuelLeakRate]]</code>

=== <code>fuelChargeRate</code> ===
'''fuelChargeRate''' : Number (read-only)
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.

=== <code>group</code> ===
'''group''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]
Contains ship’s belonging to each other. Added pirate groups are an example or a station with its launched defenders. 
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. 
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.
e.g.
this.ship.group = new ShipGroup();
this.ship.group.addShip(this.ship);

=== <code>hasHostileTarget</code> ===
'''hasHostileTarget''' : Boolean (read-only)
<code>true</code> if the ship’s AI is trying to kill something, <code>false</code> otherwise. Always <code>false</code> for the player.

=== <code>hasHyperspaceMotor</code> ===
'''hasHyperspaceMotor''' : Boolean (read-only)
<code>true</code> if the ship can make witchspace jumps. The corresponding ''[[shipdata.plist]]'' entry is <code>hyperspace_motor</code>.

=== <code>hasSuspendedAI</code> ===
'''hasSuspendedAI''' : Boolean (read-only)
<code>true</code> if the ship has suspended AIs, <code>false</code> otherwise.

=== <code>heatInsulation</code> ===
'''heatInsulation''' : Number (read/write)
The ship’s heat insulation factor. 1.0 is normal, higher values mean more resistance to heat.

Note that in 1.80 and earlier writes to this property had no effect on the player ship.

=== <code>homeSystem</code> ===
{{Oolite-prop-added|1.79}}
'''homeSystem''' : Number (read/write)
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.

=== <code>hyperspaceSpinTime</code> ===
{{oolite-prop-added|1.81}}
'''hyperspaceSpinTime''' : Number (read/write)
The length of the ship's hyperspace countdown.

Setting this to a negative value disables the drive entirely.

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.

=== <code>injectorBurnRate</code> ===
{{Oolite-prop-added|1.81}}
'''injectorBurnRate''' : Number (read/write)
The rate at which the ship's injectors burn fuel in deci-LY per second. The default is 0.25.

=== <code>injectorSpeedFactor</code> ===
{{Oolite-prop-added|1.81}}
'''injectorSpeedFactor''' : Number (read/write)
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)

=== <code>isBeacon</code> ===
'''isBeacon''' : Boolean (read-only)
<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.

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

=== <code>isBoulder</code> ===
'''isBoulder''' : Boolean (read/write)
<code>true</code> if the ship is a boulder (i.e., has the role <code>"boulder"</code> in its roleset)

=== <code>isCargo</code> ===
'''isCargo''' : Boolean (read-only)
<code>true</code> if the ship is cargo (i.e., has scan_class <code>"CLASS_CARGO"</code> and contains at least one unit)

=== <code>isCloaked</code> ===
'''isCloaked''' : Boolean (read/write)
<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>.

=== <code>isDerelict</code> ===
'''isDerelict''' : Boolean (read-only)
<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")

=== <code>isFleeing</code> ===
{{oolite-prop-added|1.79}}
'''isFleeing''' : Boolean (read-only)
<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.

=== <code>isFrangible</code> ===
'''isFrangible''' : Boolean (read-only)
<code>true</code> if the ship is frangible (i.e., its subentities can be destroyed separately from the main ship), <code>false</code> otherwise.

'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code>

=== <code>isJamming</code> ===
'''isJamming''' : Boolean (read-only)
<code>true</code> if the ship has a [[Shipdata.plist#has_military_jammer|military scanner jammer]] which is currently active, <code>false</code> otherwise.

=== <code>isMinable</code> ===
{{oolite-prop-added|1.79}}
'''isMinable''' : Boolean (read-only)
<code>true</code> if the ship will break up usefully when hit by a mining laser, <code>false</code> otherwise. By default this is <code>true</code> for anything with <code>"asteroid"</code> or <code>"boulder"</code> 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]].

=== <code>isMine</code> ===
'''isMine''' : Boolean (read-only)
<code>true</code> if the ship is a mine, <code>false</code> otherwise.

=== <code>isMissile</code> ===
'''isMissile''' : Boolean (read-only)
<code>true</code> if the ship is a missile, <code>false</code> otherwise.

=== <code>isPiloted</code> ===
'''isPiloted''' : Boolean (read-only)
<code>true</code> if the ship has a pilot on board, <code>false</code> otherwise. Generally- ships, stations and escape pods have pilots whereas cargo, rocks, missiles and buoys do not.

=== <code>isPirate</code> ===
'''isPirate''' : Boolean (read-only)
<code>true</code> if the ship is a pirate vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "pirate"</code>.

=== <code>isPirateVictim</code> ===
'''isPirateVictim''' : Boolean (read-only)
<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.

=== <code>isPolice</code> ===
'''isPolice''' : Boolean (read-only)
<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>.

=== <code>isRock</code> ===
'''isRock''' : Boolean (read-only)
<code>true</code> if the ship is a rock (i.e., has scan_class: <code>"CLASS_ROCK"</code>)

=== <code>isThargoid</code> ===
'''isThargoid''' : Boolean (read-only)
<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>.

=== <code>isTrader</code> ===
'''isTrader''' : Boolean (read-only)
<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.

=== <code>isTurret</code> ===
{{oolite-prop-added|1.79}}
'''isTurret''' : Boolean (read-only)
<code>true</code> if the ship is a plasma turret sub-entity, <code>false</code> otherwise.

=== <code>isWeapon</code> ===
'''isWeapon''' : Boolean (read-only)
<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.

=== <code>laserHeatLevel</code>* ===
{{Oolite-prop-added|1.77}}
'''laserHeatLevel''' : Number (read-only, 0 to 1)
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.
'''laserHeatLevelAft''' : Number (read-only, 0 to 1)
'''laserHeatLevelForward''' : Number (read-only, 0 to 1)
'''laserHeatLevelPort''' : Number (read-only, 0 to 1)
'''laserHeatLevelStarboard''' : Number (read-only, 0 to 1)
The temperature of specific laser mounts can also be queried.

=== <code>lightsActive</code> ===
'''lightsActive''' : Boolean (read-write)
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.

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 <code>false</code> in their ''shipdata.plist'' declarations.

=== <code>markedForFines</code> ===
{{oolite-prop-added|1.79}}
'''markedForFines''' : Boolean (read-only)
<code>true</code> if the ship has been marked for fines the next time it docks at this system's main station.

'''See also''' : [[#markTargetForFines|markTargetForFines()]]

=== <code>maxEscorts</code> ===
{{Oolite-prop-added|1.77}}
'''maxEscorts''' : Number (read/write)
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)

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

=== <code>maxPitch</code> ===
{{Oolite-prop-added|1.77}}
'''maxPitch''' : Number (read-only, read/write from 1.81)
The maximum pitch rate of the ship, in radians per second.

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

=== <code>maxRoll</code> ===
{{Oolite-prop-added|1.77}}
'''maxRoll''' : Number (read-only, read/write from 1.81)
The maximum roll rate of the ship, in radians per second.

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

=== <code>maxSpeed</code> ===
'''maxSpeed''' : Number (read-only, read/write from 1.81)
The ship’s maximum speed under normal power. Note that <code>[[#speed|speed]]</code> may exceed this when the [[Witch Fuel Injectors]] or [[Torus Drive]] are in use.

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

=== <code>maxThrust</code> ===
'''maxThrust''' : Number (read-only, read/write from 1.81)
The ship’s maximum <code>[[#thrust|thrust]]</code>. This value is the one defined as <code>thrust</code> in ''[[Shipdata.plist#thrust|shipdata.plist]]''.

=== <code>maxYaw</code> ===
{{Oolite-prop-added|1.77}}
'''maxYaw''' : Number (read-only, read/write from 1.81)
The maximum yaw rate of the ship, in radians per second.

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

=== <code>missileCapacity</code> ===
'''missileCapacity''' : Number (read-only integer)
The maximum number of missiles the ship can carry.

=== <code>missileLoadTime</code> ===
'''missileLoadTime''' : Number (read-write nonnegative)
The minimum amount of time between two missiles. The corresponding ''[[shipdata.plist]]'' key is <code>missile_load_time</code>.

=== <code>missiles</code> ===
'''missiles''' : Array (read-only array of [[Oolite JavaScript Reference: EquipmentInfo|EquipmentInfo]])
The ship’s loaded missiles.

=== <code>name</code> ===
'''name''' : String (read/write, read-only for player)
The name of the ship type (<code>name</code> key in [[shipdata.plist]]).

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

=== <code>parcelCount</code> ===
{{oolite-prop-added|1.77}}
'''parcelCount''' : Number (read-only integer)
The ship’s current number of parcels.

'''See also''': <code>[[Oolite JavaScript Reference: PlayerShip#addParcel|addParcel()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removeParcel|removeParcel()]]</code>

=== <code>parcels</code> ===
{{oolite-prop-added|1.77}}
'''parcels''' : Array (read-only NSDictionary)
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> 
For example, the information of the first contract can be obtained by:
player.ship.parcels[0].name
player.ship.parcels[0].start
player.ship.parcels[0].destination
player.ship.parcels[0].startName
player.ship.parcels[0].destinationName
player.ship.parcels[0].eta
player.ship.parcels[0].etaDescription
player.ship.parcels[0].fee // The final fee, paid out on successful delivery.

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.

'''See also''': <code>[[Oolite JavaScript Reference: PlayerShip#addParcel|addParcel()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removeParcel|removeParcel()]]</code>, <code>[[Oolite JavaScript Reference: Player#parcelReputation|parcelReputation]]</code>

=== <code>passengerCapacity</code> ===
'''passengerCapacity''' : Number (read-only integer)
The ship’s maximum passenger capacity.

'''See also''': <code>[[Passenger Berth]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#addPassenger|addPassenger()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removePassenger|removePassenger()]]</code>

=== <code>passengerCount</code> ===
'''passengerCount''' : Number (read-only integer)
The ship’s current number of passengers.

'''See also''': <code>[[Passenger Berth]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#addPassenger|addPassenger()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removePassenger|removePassenger()]]</code>

=== <code>passengers</code> ===
'''passengers''' : Array (read-only NSDictionary)
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> 
For example, the information of the first contract can be obtained by:
player.ship.passengers[0].name
player.ship.passengers[0].start
player.ship.passengers[0].destination
player.ship.passengers[0].startName
player.ship.passengers[0].destinationName
player.ship.passengers[0].eta
player.ship.passengers[0].etaDescription
player.ship.passengers[0].fee // The final fee, paid out on successful delivery.
player.ship.passengers[0].premium // The advance fee, already paid on acceptance of the contract.

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.

'''See also''': <code>[[Passenger Berth]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#addPassenger|addPassenger()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removePassenger|removePassenger()]]</code>, <code>[[Oolite JavaScript Reference: Player#passengerReputation|passengerReputation]]</code>

=== <code>pitch</code> ===
{{Oolite-prop-added|1.77}}
'''pitch''' : Number (read-only)
The rate of pitch of the ship in radians/second (positive for dive, negative for climb)

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

=== <code>portWeapon</code> ===
'''portWeapon''' : EquipmentType (read-only, read/write in 1.77)
The currently equipped port weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.

'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code>

=== <code>potentialCollider</code> ===
'''potentialCollider''' : [[Oolite JavaScript Reference: Entity|Entity]] (read-only)
The entity the ship is currently trying not to crash into, if any.

=== <code>primaryRole</code> ===
'''primaryRole''' : String (read/write, read-only for player)
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 <code>"pirate trader(0.5) escort"</code> and a ship of that type is spawned to be a trader, its <code>primaryRole</code> is <code>"trader"</code>, its <code>roles</code> are <code>["escort", "pirate", "trader"]</code> and its <code>roleWeights</code> are <code>{"escort":1, "pirate":1, "trader":0.5}</code>.

'''See also:''' <code>[[#roles|roles]]</code>, <code>[[#roleWeights|roleWeights]]</code>

=== <code>reportAIMessages</code> ===
'''reportAIMessages''' : Boolean (read/write)
Debugging facility: set to <code>true</code> to dump information about AI activity to the log.

=== <code>roleWeights</code> ===
'''roleWeights''' : Object (read-only)
The probabilities for each role in <code>[[#roles|roles]]</code>.

Example:
this.pirateProb = ship.roleWeights["pirate"]

'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roles|roles]]</code>

=== <code>roles</code> ===
'''roles''' : Array (read-only array of Strings)
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.

'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roleWeights|roleWeights]]</code>, <code>[[#hasRole|hasRole()]]</code>

=== <code>roll</code> ===
{{Oolite-prop-added|1.77}}
'''roll''' : Number (read-only, read/write for stations)
The rate of roll of the ship in radians/second (positive for anti-clockwise, negative for clockwise)

'''See also:''' <code>[[#maxRoll|maxRoll]]</code>, <code>[[Oolite JavaScript Reference: Station#roll|station.roll]]</code>

=== <code>savedCoordinates</code> ===
'''savedCoordinates''' : [[Oolite JavaScript Reference: Vector|Vector]] (read-write)
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>

=== <code>scanDescription</code> ===
{{Oolite-prop-added|1.81}}
'''scanDescription''' : String (read/write)
The description of the ship in the "legal status" text shown by the [[Scanner Targeting Enhancement]]. If this is <code>null</code> then the default text for the ship's scan class and bounty level will be shown.

=== <code>scannerDisplayColor1</code> ===
'''scannerDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
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.

'''See also:''' <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code>, <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code>

=== <code>scannerDisplayColor2</code> ===
'''scannerDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
The second scanner colour. If both <code>scannerDisplayColor1</code> and <code>scannerDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.

'''See also:''' <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code>, <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code>

=== <code>scannerHostileDisplayColor1</code> ===
{{oolite-prop-added|1.81}}
'''scannerHostileDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
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.

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.

'''See also:''' <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code>, <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code>

=== <code>scannerHostileDisplayColor2</code> ===
{{oolite-prop-added|1.81}}
'''scannerHostileDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
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.

'''See also:''' <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code>, <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code>

=== <code>scannerRange</code> ===
'''scannerRange''' : Number (read-only)
The range of the ship’s scanner.

=== <code>script</code> ===
'''script''' : [[Oolite JavaScript Reference: Script|Script]] (read-only)
The ship’s script.

=== <code>scriptedMisjump</code> ===
'''scriptedMisjump''' : Boolean (read/write)
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.

=== <code>scriptedMisjumpRange</code> ===
{{oolite-prop-added|1.77}}
'''scriptedMisjumpRange''' : Number (read/write)
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>.

=== <code>scriptInfo</code> ===
'''scriptInfo''' : Object (read-only)
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. 
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).

=== <code>shipClassName</code> ===
{{oolite-prop-added|1.79}}
'''shipClassName''' : String (read/write)
The name of the ship class (e.g. <code>"Python"</code>)

=== <code>shipUniqueName</code> ===
{{oolite-prop-added|1.79}}
'''shipUniqueName''' : String (read/write)
The name of this specific ship (e.g. <code>"Sunrise of Lave"</code>)

=== <code>speed</code> ===
'''speed''' : Number (read-only)
The ship’s current speed.

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

=== <code>starboardWeapon</code> ===
'''starboardWeapon''' : EquipmentType (read-only, read/write in 1.77)
The currently equipped forward weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.

'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>

=== <code>subEntities</code> ===
'''subEntities''' : Array (read-only array of Ships)
The ships subentities, or <code>null</code> if it has none. Special subentities such as flashers and exhaust plumes are not included.

'''See also:''' <code>[[#isFrangible|isFrangible]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code>

=== <code>subEntityCapacity</code> ===
'''subEntityCapacity''' : Number (read-only integer)
The original number of subentities on the ship.

'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code>

=== <code>subEntityRotation</code> ===
{{oolite-prop-added|1.81}}
'''subEntityRotation''' : Quaternion (read/write)
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.

=== <code>sunGlareFilter</code> ===
{{oolite-prop-added|1.79}}
'''sunGlareFilter''' : Number (read/write)
The strength of the sun glare filter on this ship. It must be in the range 0 to 1 (0 is no filter).

=== <code>target</code> ===
'''target''' : Ship (read-write)
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.

=== <code>temperature</code> ===
'''temperature''' : Number (read/write)
The ship’s temperature, normalized such that a temperature of 1.0 is the level at which a ship starts taking heat damage.

=== <code>thrust</code> ===
'''thrust''' : Number (read/write for NPCs, read-only for player before 1.81)
The ship’s thrust, ranging from 0 to <code>[[#maxThrust|maxThrust]]</code>. This value determines how fast the ship accelerates or decelerates, specified in m/s².

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

=== <code>thrustVector</code> ===
'''thrustVector''' : Vector3D (read-only)
The inertialess velocity generated by the engines.

'''See also:''' <code>[[#thrust|thrust]]</code>, <code>[[#velocity|velocity]]</code>

=== <code>trackCloseContacts</code> ===
'''trackCloseContacts''' : Boolean (read/write)
If <code>true</code>, AI events are generated for near collisions.

=== <code>vectorForward</code> ===
'''vectorForward''' : Vector3D (read-only)
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>.

=== <code>vectorRight</code> ===
'''vectorRight''' : Vector3D (read-only)
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>.

=== <code>vectorUp</code> ===
'''vectorUp''' : Vector3D (read-only)
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>.

=== <code>velocity</code> ===
'''velocity''' : Vector3D (read/write)
The ship’s velocity.

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

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

=== <code>weaponFacings</code> ===
{{Oolite-prop-added|1.77}}
'''weaponFacings''' : Number (read-only, integer in range 0-15)
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: 
1 - fore 
2 - aft 
4 - port 
8 - starboard

=== <code>weaponPosition*</code> ===
{{Oolite-prop-added|1.77}}
'''weaponPositionAft''' : Vector (read-only)
'''weaponPositionForward''' : Vector (read-only)
'''weaponPositionPort''' : Vector (read-only)
'''weaponPositionStarboard''' : Vector (read-only)

{{Oolite-prop-added|1.83}}
'''weaponPositionAft''' : Array of Vectors (read-only)
'''weaponPositionForward''' : Array of Vectors (read-only)
'''weaponPositionPort''' : Array of Vectors (read-only)
'''weaponPositionStarboard''' : Array of Vectors (read-only)

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.

In 1.83 this property changed syntax to become an array of vectors, as ships can now have multiple mounts per facing.

=== <code>weaponRange</code> ===
'''weaponRange''' : Number (read-only)
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. 
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. 
(Turrets are secondary weapons with a maximum range of 6000)

=== <code>withinStationAegis</code> ===
'''withinStationAegis''' : Boolean (read-only)
<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).

=== <code>yaw</code> ===
{{Oolite-prop-added|1.77}}
'''yaw''' : Number (read-only)
The rate of yaw of the ship in radians/second (positive for right, negative for left)

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

== Methods ==
=== <code>abandonShip</code> ===
function '''abandonShip'''() : Boolean
Returns <code>true</code> when the ship has an escape pod. It will launch all escape pods on board leaving the ship behind as a empty hulk (<code>scanClass === "CLASS_CARGO"</code>). This command does nothing when no escape pod is present. 
Presence of an escape pod can be tested with: <code>equipmentStatus("EQ_ESCAPE_POD") === "EQUIPMENT_OK"</code>

=== <code>addCollisionException</code> ===
{{oolite-method-added|1.81}}
function '''addCollisionException'''(exception : Ship)
Prevented this ship and the selected ship from colliding. See [[#collisionExceptions|collisionExceptions]] and [[#removeCollisionException|removeCollisionException]].

Prevention from collision will specifically prevent the following:

* the ships colliding with each other and suffering collision damage and/or momentum change
* the ships receiving collision warning events if they come close to each other
* 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

This has no useful effect when applied to a subentity.

Adding a collision exception which already exists has no effect but will not cause an error.

=== <code>addDefenseTarget</code>===
{{oolite-method-added|1.77}}
function '''addDefenseTarget'''(target : Ship)
Adds the target ship to this ship's list of point [[#defenseTargets|defense targets]], if it isn't already.

=== <code>adjustCargo</code>===
{{oolite-method-added|1.81}}
function '''adjustCargo'''(commodity : String, amount : Number) : Boolean
Adjust the quantity of the specified commodity carried by the ship. Amount may be negative to remove cargo. The method will return <code>false</code> if the operation would fail due to insufficient free space or carried cargo and will not make a partial adjustment in this case.

This method is for non-player ships. For the player ship, use <code>[[Oolite JavaScript Reference: PlayerShip#manifest|manifest]]</code>.

'''See also''': <code>[[#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[#cargoList|cargoList]]</code>, <code>[[#setCargoType|setCargoType()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>awardEquipment</code> ===
function '''awardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean
Adds the given piece of equipment to the ship, if possible, returning <code>true</code> if successful and <code>false</code> otherwise.

Example:
ship.awardEquipment("EQ_ECM");

'''See also:''' <code>[[#canAwardEquipment|canAwardEquipment()]]</code>, <code>[[#removeEquipment|removeEquipment()]]</code>

=== <code>canAwardEquipment</code> ===
function '''canAwardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean
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.

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

=== <code>becomeCascadeExplosion</code> ===
{{oolite-method-added|1.79}}
function '''becomeCascadeExplosion'''()
This method causes the ship to explode as if it were hit by a quirium cascade.

=== <code>broadcastCascadeImminent</code> ===
{{oolite-method-added|1.79}}
function '''broadcastCascadeImminent'''()
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>

=== <code>broadcastDistressMessage</code> ===
{{oolite-method-added|1.79}}
function '''broadcastDistressMessage'''()
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.

=== <code>checkCourseToDestination</code> ===
{{oolite-method-added|1.79}}
function '''checkCourseToDestination'''()
Checks the line between the ship's current position and its destination, and returns either <code>null</code> or an Entity (usually a planet, sun or other ship) that this ship would risk collision with if it travelled along that course.

'''See also''': [[#getSafeCourseToDestination|getSafeCourseToDestination()]]

=== <code>checkScanner</code> ===
{{oolite-method-added|1.79}}
function '''checkScanner'''([poweredOnly : Boolean]) : Array
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 <code>true</code>, then only powered objects will be returned (i.e. ships with a scan class other than <code>"CLASS_CARGO"</code> or <code>"CLASS_ROCK"</code>).

This method is usually considerably quicker than <code>[[Oolite JavaScript Reference: System#filteredEntities|system.filteredEntities()]]</code> and similar methods, with little loss of accuracy, though it is still advisable to cache the result for a while before re-scanning.

=== <code>clearDefenseTargets</code>===
{{oolite-method-added|1.77}}
function '''clearDefenseTargets'''()
Clears the ship's list of point [[#defenseTargets|defense targets]].

=== <code>commsMessage</code> ===
function '''commsMessage'''(message : String [,target : Ship])
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.

'''See also''': <code>[[Oolite JavaScript Reference: Player#commsMessage|player.commsMessage()]]</code>

=== <code>damageAssessment</code> ===
{{oolite-method-added|1.79}}
function '''damageAssessment'''() : Number
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.

=== <code>dealEnergyDamage</code>===
{{oolite-method-added|1.77}}
function '''dealEnergyDamage'''(damage : Number, idealRange : Number [, velocityBias : Number])
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:
* Further away than MAX_SCANNER_RANGE (25.6km): deal no damage
* 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
* 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.

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):
* 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
* 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.
* 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)2, so the Anaconda takes about 1.5 points of damage.
* A missile fired at something else detonates 500m away from a Sidewinder. The inverse-square rule divides the damage by (500 / 32.5)2, 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.

=== <code>deployEscorts</code> ===
function '''deployEscorts'''()
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 method has already been called for the current target without meanwhile being called for a different target.

=== <code>dockEscorts</code> ===
function '''dockEscorts'''()
Dock the ship’s deployed escorts, if any.

=== <code>dumpCargo</code> ===
function '''dumpCargo'''([amount : Number, commodity: String]) : Ship
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.

In 1.79 or later, multiple items may be scheduled for dumping by passing the number as a parameter.

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.

'''See also:''' <code>[[#ejectItem|ejectItem]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code>

=== <code>ejectItem</code> ===
function '''ejectItem'''(role : String) : Ship
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 <code>scanClass</code> of the ejected item will always be <code>"CLASS_CARGO"</code>.

'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code>

=== <code>ejectSpecificItem</code> ===
function '''ejectSpecificItem'''(itemKey : String) : Ship
Spawns a ship with the ''shipdata.plist'' key <code>itemKey</code> immediately behind the ship, with a slight backwards velocity. The <code>scanClass</code> of the ejected item will always be <code>"CLASS_CARGO"</code>.

'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectItem|ejectItem]]</code>

=== <code>enterWormhole</code> ===
{{oolite-method-added|1.79}}
function '''enterWormhole'''([wormhole : Wormhole])
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.

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.

=== <code>equipmentStatus</code> ===
function '''equipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]] [, multiple : Boolean]) : String or Object
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>.

In 1.81 and later, if the optional <code>multiple</code> parameter is set to <code>true</code>, it will instead return an object in this format:
{
"EQUIPMENT_OK": 3.
"EQUIPMENT_DAMAGED": 2
}
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.

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

=== <code>exitAI</code> ===
function '''exitAI'''()
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.

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code>

=== <code>exitSystem</code> ===
function '''exitSystem'''([targetSystem : Number]) : Boolean
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.

This method can fail for various reasons, in which case it returns <code>false</code>. It always fails for the player ship.

=== <code>explode</code> ===
function '''explode'''()
Causes the ship to explode. Works on all ships, including the main station and the player except when docked.

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

=== <code>fireECM</code> ===
function '''fireECM'''()
activates an ecm burst, identical as the AI command.

=== <code>findNearestStation</code> ===
function '''findNearestStation'''()
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>.

=== <code>fireMissile</code> ===
function '''fireMissile'''([missile]) : Ship
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.

=== <code>getSafeCourseToDestination</code> ===
{{oolite-method-added|1.79}}
function '''getSafeCourseToDestination'''()
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.

'''See also''': [[#checkCourseToDestination|checkCourseToDestination()]]

=== <code>getMaterials</code> ===
{{oolite-method-added|1.77}}
function '''getMaterials'''() : Object
getMaterials() returns the ship's current materials dictionary, or if none present an empty dictionary.

'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code>

=== <code>getShaders</code> ===
{{oolite-method-added|1.77}}
function '''getShaders'''() : Object
getShaders() returns the ship's current shaders dictionary, or if none present an empty dictionary.

'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code>

=== <code>hasEquipmentProviding</code> ===
{{oolite-method-added|1.81}}
function '''hasEquipmentProviding'''(key : String) : Boolean
This method returns <code>true</code> if the ship has any equipment providing the <code>key</code> equipment type, and <code>false</code> otherwise.

=== <code>hasRole</code> ===
function '''hasRole'''(role : String) : Boolean
Returns <code>true</code> if the ship has <code>role</code> among its roles, <code>false</code> otherwise.

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

=== <code>markTargetForFines</code> ===
{{oolite-method-added|1.79}}
function '''markTargetForFines()'''
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.

=== <code>notifyGroupOfWormhole</code> ===
{{oolite-method-added|1.79}}
function '''notifyGroupOfWormhole()'''
Tells the ship's group about a wormhole (usually the one this ship has just entered). Causes a <code>[[Oolite JavaScript Reference: Ship script event handlers#wormholeSuggested|wormholeSuggested]]</code> event to occur in the scripts of other group members.

=== <code>offerToEscort</code> ===
{{oolite-method-added|1.79}}
function '''offerToEscort(mother : Ship)'''
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.

=== <code>perform*</code> ===
Each of these methods 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.

==== <code>performAttack</code> ====
{{oolite-method-added|1.79}}
function '''performAttack()'''
Attack the current target with available weapons.

==== <code>performCollect</code> ====
{{oolite-method-added|1.79}}
function '''performCollect()'''
Attempt to scoop up the current target. If the current target is not scoopable, it will be lost.

==== <code>performEscort</code> ====
{{oolite-method-added|1.79}}
function '''performEscort()'''
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.

==== <code>performFaceDestination</code> ====
{{oolite-method-added|1.79}}
function '''performFaceDestination()'''
Come to a stop, and turn to face the current destination coordinates.

==== <code>performFlee</code> ====
{{oolite-method-added|1.79}}
function '''performFlee()'''
Flee from the current target, using injectors if possible, until it is out of scanner range.

==== <code>performFlyToRangeFromDestination</code> ====
{{oolite-method-added|1.79}}
function '''performFlyToRangeFromDestination()'''
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.

==== <code>performHold</code> ====
{{oolite-method-added|1.79}}
function '''performHold()'''
Come to a stop, and continually turn to face the current target

==== <code>performIdle</code> ====
{{oolite-method-added|1.79}}
function '''performIdle()'''
Cancel any current turns to return to level flight, then move forward at current speed.

==== <code>performIntercept</code> ====
{{oolite-method-added|1.79}}
function '''performIntercept()'''
Fly to intercept (i.e. ram) the current target.

==== <code>performLandOnPlanet</code> ====
{{oolite-method-added|1.79}}
function '''performLandOnPlanet()'''
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.

==== <code>performMining</code> ====
{{oolite-method-added|1.79}}
function '''performMining()'''
Attack the current target with a mining laser. This does not count as hostile behaviour, so cannot be used except on rocks.

==== <code>performScriptedAI</code> ====
{{oolite-method-added|1.79}}
function '''performScriptedAI()'''
Request flight instructions from a [[OXP_Scripted_AI|scripted AI]] callback each frame.

==== <code>performScriptedAttackAI</code> ====
{{oolite-method-added|1.79}}
function '''performScriptedAttackAI()'''
Request flight instructions, including weapons fire, from a [[OXP_Scripted_AI|scripted AI]] callback each frame.

==== <code>performStop</code> ====
{{oolite-method-added|1.79}}
function '''performStop()'''
Come to a complete halt

==== <code>performTumble</code> ====
{{oolite-method-added|1.79}}
function '''performTumble()'''
Come to a complete halt and rotate randomly.

=== <code>reactToAIMessage</code> ===
function '''reactToAIMessage'''(message : String)
Immediately perform the specified handler in the ship’s current AI state.

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

=== <code>recallDockingInstructions</code> ===
{{oolite-method-added|1.79}}
function '''recallDockingInstructions'''() : Object
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.

'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#requestDockingInstructions|requestDockingInstructions]]</code>

=== <code>remove</code> ===
function '''remove'''([suppressDeathEvent : Boolean])
Immediately removes the ship from the universe. Works on all ships except the player, including the main station. 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 <code>true</code>.

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

=== <code>removeCollisionException</code> ===
{{oolite-method-added|1.81}}
function '''removeCollisionException'''(exception : Ship)
Allow this ship and the selected ship to collide again. See [[#collisionExceptions|collisionExceptions]] and [[#addCollisionException|addCollisionException]].

Removing a collision exception which does not exist has no effect but will not cause an error.

=== <code>removeDefenseTarget</code>===
{{oolite-method-added|1.79}}
function '''removeDefenseTarget'''(target : Ship)
Ensures that the target ship is not on this ship's list of point [[#defenseTargets|defense targets]].

=== <code>removeEquipment</code> ===
function '''removeEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]])
Removes the given piece of equipment from the ship.
This method 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.

Note that in Oolite prior to 1.76.1 there was a bug which could sometimes cause the game to crash if this method 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

Example:
ship.removeEquipment("EQ_ECM");

=== <code>requestDockingInstructions</code> ===
{{oolite-method-added|1.79}}
function '''requestDockingInstructions'''() : Object
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.

'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code>

=== <code>requestHelpFromGroup</code> ===
{{oolite-method-added|1.79}}
function '''requestHelpFromGroup'''()
This method 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.

=== <code>restoreSubEntities</code> ===
function '''restoreSubEntities'''() : Boolean
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.

'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#isFrangible|isFrangible]]</code>

=== <code>selectNewMissile</code> ===
function '''selectNewMissile'''() : equipmentKey
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.
e.g.
this.ship.awardEquipment(this.ship.selectNewMissile())
will automatically add the 'right type' of missile to a ship, i.e. one that its captain would normally choose.

=== <code>sendAIMessage</code> ===
function '''sendAIMessage'''(message : String)
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.

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

=== <code>setAI</code> ===
function '''setAI'''(AIName : String)
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).

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>

=== <code>setBounty</code> ===
{{oolite-method-added|1.77}}
function '''setBounty'''(bounty : Number, reason : String)
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()]].

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

=== <code>setCargo</code> ===
function '''setCargo'''(commodity : String [, count : Number]) : Boolean
Attempts to create <code>count</code> weight units of the <code>commodity</code> specified for a cargo barrel. This cannot be used to set cargo for ships. When more units are defined than 1 ton, the count is reduced to 1 ton. It returns <code>false</code> when the selected commodity is unknown. If <code>count</code> is not specified, <code>1</code> will be assumed.

=== <code>setCargoType</code> ===
{{oolite-method-added|1.79}}
function '''setCargoType'''(commodityType : String) : Boolean
Attempts to set the ship's cargo hold to contain commodities of the specified type, discarding any cargo already present. This should generally only be used immediately after a ship is spawned. Valid commodity types are:
*<code>"SCARCE_GOODS"</code>: goods which are likely to be rare in the current system, usually legal
*<code>"PLENTIFUL_GOODS"</code>: goods which are likely to be plentiful in the current system, usually legal
*<code>"MEDICAL_GOODS"</code>: narcotics (used for the Moray Medical Boat)
*<code>"ILLEGAL_GOODS"</code>: various goods likely to be rare in the current system, with a strong bias towards contraband
*<code>"PIRATE_GOODS"</code>: similar to <code>"ILLEGAL_GOODS"</code> but the total amount carried will be lower
This will return <code>false</code> 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.

=== <code>setCrew</code> ===
{{oolite-method-added|1.79}}
function '''setCrew'''(Object) : Boolean
Sets the ship's crew to one represented by the given object (or sets the ship to uncrewed if <code>null</code> is given as a parameter). Returns <code>true</code> if this succeeds, <code>false</code> 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:
* origin system
* random seed
* role
* the rest
You can therefore set a random seed or role to get particular behaviour, and use the other keys to override it.

At the moment this method only sets the first crew member (the pilot of the ship) in [[Oolite JavaScript Reference: Ship#crew|crew]][0] .

=== <code>setEquipmentStatus</code> ===
function '''setEquipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]], statusKey : String)
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>.

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

'''See also:''' <code>[[#equipmentStatus|equipmentStatus()]]</code>, <code>[[Oolite JavaScript Reference: EquipmentInfo#canBeDamaged|EquipmentInfo.canBeDamaged]]</code>for equipment that cannot be damaged

=== <code>setMaterials</code> ===
function '''setMaterials'''(materialDictionary : Object [, shaderDictionary : Object]) : Boolean
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.

'''Example:'''
this.ship.setMaterials({"my_ship_diffuse.png": { diffuse_map: "my_ship_damaged_diffuse.png" }});

'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code>

=== <code>setScript</code> ===
function '''setScript'''(scriptName : String)
Set, or completely replace, the javascript code associated to a ship entity.

=== <code>setShaders</code> ===
function '''setShaders'''(shaderDictionary : Object) : Boolean
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.

'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code>

=== <code>spawn</code> ===
function '''spawn'''(role : String [, count : Number]) : Array
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.

<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:
* The spawned ships inherit most of the temperature of the parent.
* 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.
* <code>spawn()</code> does not set up escorts for the new ships, or generate witchspace effects, or do any special AI handling.

=== <code>spawnOne</code> ===
function '''spawnOne'''(role : String) : Ship
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.

=== <code>switchAI</code> ===
function '''switchAI'''(AIName : String)
Set the current AI, exiting the old one. Equivalent to the <code>[[AI_methods|switchAITo]]:</code> AI method. May not be used on player.

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>

=== <code>threatAssessment</code> ===
{{oolite-method-added|1.79}}
function '''threatAssessment'''(full : Boolean) : Number
Returns a number indicating the relative strength of the ship. If the 'full' parameter is <code>true</code>, 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.

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.

=== <code>throwSpark</code> ===
{{oolite-method-added|1.79}}
function '''throwSpark'''()
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.

=== <code>updateEscortFormation</code> ===
function '''updateEscortFormation'''()
Request that the game updates the target positions for the ship’s escorts by calling the ship’s script’s <code>coordinatesForEscortPosition()</code> method.

== Static Methods ==
=== <code>keys</code> ===
{{Oolite-method-added|1.79}}
function '''keys'''() : Array
Returns all dataKeys of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.

'''Example:'''
var dataKeysArray = Ship.keys();

=== <code>keysForRole</code> ===
{{Oolite-method-added|1.79}}
function '''keysForRole'''(role : String) : Array
Returns all dataKeys of ships defined in all [[shipdata.plist]] which contains the given role.

'''Example:'''
var role = "trader";
var roleKeys = Ship.keysForRole( role );
log("keysForRole", role + ": " + roleKeys );

=== <code>roleIsInCategory</code> ===
{{Oolite-method-added|1.79}}
function '''roles'''(role : String, category : String) : Boolean
Returns whether the role given is in a particular category as defined in [[role-categories.plist]]

'''Example:'''
Ship.roleIsInCategory("trader","oolite-pirate-victims"); // true

=== <code>roles</code> ===
{{Oolite-method-added|1.79}}
function '''roles'''() : Array
Returns all roles of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.

'''Example:'''
var roles = Ship.roles();
for( var i = 0; i < roles.length; i++ ) {
var roleKeys = Ship.keysForRole( roles[i] );
log("roles", i + ". "+roles[i] + ": " + roleKeys );
}

=== <code>shipDataForKey</code> ===
{{Oolite-method-added|1.79}}
function '''shipDataForKey'''(datakey : String) : Object
Returns an object containing a representation of the raw [[shipdata.plist]] entry for a given data key, or <code>null</code> 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.

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.

'''Example:'''
var shipdata = Ship.shipDataForKey("cobra3-trader");
log("test",shipdata["name"]); // "Cobra Mark III"
log("test",shipdata["ship_class_name"]); // undefined
log("test",shipdata["ship_unique_name"]); // undefined
log("test",shipdata["display_name"]); // undefined

===<code>setShipDataForKey</code>===
{{Oolite-method-added|1.91}}
function '''setShipDataForKey'''(datakey : String, newShipData : Object)
This method modifies or adds properties of a ship class specified by the datakey parameter. The newShipData parameter can be an existing property defined in shipdata.plist or a new one.

'''Example:'''
Ship.setShipDataForKey ("cobra3-trader", {name: "Cobra trader variant"})
var shipdata = Ship.shipDataForKey ("cobra3-trader")
log ("test", shipdata ["name"])

'''See also''': [http://www.aegidian.org/bb/viewtopic.php?p=274534#p274534 bulletin board post by Tsoj]

==See also==
*[[Shipdata.plist]]

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Ship script event handlers

2022-10-29T16:20:35Z

Massively Locked: /* willOpenDockingPortFor */ replaced "function"

This page provides a list of event handlers which can be implemented by [[Scripting Oolite with JavaScript|JavaScript scripts for Oolite]].

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.

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.

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

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 Reference: PriorityAI Documentation|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''.

=== Docking ===

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

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

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

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

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

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

==== <code>shipWillLaunchFromStation</code> ====
This handler was added for npc ships with test release 1.75, before it was a worldScript only handler.

The <code>shipWillLaunchFromStation</code> handler is called for ship scripts on ship creation, before the shipSpawned event.

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

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

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.

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

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

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

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

=== Witchspace Jumps ===

==== <code>playerWillEnterWitchspace</code> ====

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)

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

==== <code>shipExitedWormhole</code> ====

The <code>shipExitedWormhole</code> handler is called when a ship exits a wormhole.

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

==== <code>shipWillEnterWormhole</code> ====

The <code>shipWillEnterWormhole</code> handler is called when a ship enters a wormhole. only

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

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

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

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

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

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.

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

=== Enter/Exit Aegis ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Combat ===

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

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.

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

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

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.

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

==== <code>escortAttack</code> ====

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.

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

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

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.

this.helpRequestReceived = function(ally, enemy)
{
// Your code here
}

==== <code>shipAttackedOther</code> ====
{{oolite-method-added|1.74.2}}

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.

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

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

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

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

==== <code>shipAttackerDistracted</code> ====

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.

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

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

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

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

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

The <code>shipBeingAttackedByCloaked</code> handler is called when a laser shot from a cloaked ship hits. There is no parameter provided to identify the cloaked ship.

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

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

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.

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

==== <code>shipCloakActivated</code> ====
{{oolite-method-added|1.74}}

The <code>shipCloakActivated</code> handler is called whenever the script's target ship activates its cloaking device. No parameters are required for this handler.

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

==== <code>shipCloakDeactivated</code> ====
{{oolite-method-added|1.74}}

The <code>shipCloakDeactivated</code> handler is called whenever the script's target ship deactivates its cloaking device. No parameters are required for this handler.

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

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

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.

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

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

The <code>shipDied</code> handler is called when the ship or player dies.

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

==== <code>shipEnergyBecameFull </code> ====

The <code>shipEnergyBecameFull </code> handler is called when the energy level reaches its maximum value again.

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

==== <code>shipEnergyIsLow</code> ====

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.

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

==== <code>shipHitByECM</code> ====
{{oolite-method-added|1.71}}

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.

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

==== <code>shipFiredMissile</code> ====
{{oolite-method-added|1.74}}

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

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

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

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

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

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

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

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

==== <code>shipTargetAcquired</code> ====
{{oolite-method-added|1.74}}

The <code>shipTargetAcquired</code> handler is called whenever a new target is selected.

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

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

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

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

==== <code>shipTargetLost</code> ====
{{oolite-method-added|1.74}}

The <code>shipTargetLost</code> handler is called when the target gets lost. <code>target</code> contains the lost target entity. (Handler introduced in 1.74 as replacement with consistent name for the old handler: 'shipLostTarget'.)

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

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

The <code>shipTakingDamage</code> handler is called when a ship sustains damage. 
It transfers the <code>amount</code> of damage, <code>who</code> caused the damage and a string indicating the <code>type</code> of damage:

* "scrape damage" (collisions with other entities, <code>who</code> will be other entity involved)
* "heat damage" (see [[Shipdata.plist#heat_insulation]] for more information about this, <code>who</code> will be nil in this case)
* "energy damage" (default / catch-all including weapons damage and missile detonations, <code>who</code> will be nil if the entity causing the damage is cloaked, and if the damage is caused by a missile then <code>who</code> will be the entity that launched the missile, if it is damage from a direct laser or from a sub-entity weapon, <code>who</code> will be the ship or station mounting the weapon, etc.)
* "cascade weapon" (caught in Quirium Cascade Mine effect, <code>who</code> will be the entity that launched the weapon)
* "hit a planet"
* "hit a sun"
* "removed" (corresponds to the <code>Ship.remove()</code> method, regardless of the suppressDeathEvent parameter)

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.

this.shipTakingDamage = function(amount, whom, type)
{
// Your code here
}

=== Miscellaneous ===

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

The <code>cargoDumpedNearby</code> handler is sent when a nearby ship - not this ship - dumps a cargo pod.

this.cargoDumpedNearby = function(cargo: ship, releasedBy: ship)
{
// Your code here
}

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

The <code>commsMessageReceived</code> handler is sent when receiving a message from other ships.

this.commsMessageReceived = function(message: string, sender: ship)
{
// Your code here
}

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

The <code>distressMessageReceived</code> handler is sent when receiving a distress message from other ships.

this.distressMessageReceived = function(aggressor: ship, sender: ship)
{
// Your code here
}

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

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.

this.equipmentAdded = function(equipmentKey)
{
// Your code here
}

==== <code>equipmentRemoved</code> ====
{{Oolite-method-added|1.81}}

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.

this.equipmentAdded = function(equipmentKey)
{
// Your code here
}

==== <code>shipAchievedDesiredRange</code> ====
{{Oolite-method-added|1.79}}

The <code>shipAchievedDesiredRange</code> handler is called when the ship reaches the desired range from its destination during certain flight behaviours.

this.shipAchievedDesiredRange = function()
{
// Your code here
}

==== <code>shipAIFrustrated</code> ====
{{Oolite-method-added|1.79}}

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.

this.shipAIFrustrated = function(context)
{
// Your code here
}

==== <code>shipBountyChanged</code> ====
{{Oolite-method-added|1.77}}

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:
* '''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.
* '''scripted''': OXP scripted changes to bounties, with no specified cause.
* '''attacked police''': The ship attacked a police ship
* '''attacked main station''': The ship attacked the main station
* '''attacked innocent''': The ship attacked a Clean ship and was seen doing so
* '''seen by police''': The ship was seen by police committing a crime
* '''distress call''': A police ship responded to a distress call from a ship that this ship is attacking
* '''illegal exports''': The ship launched from a main station while carrying illegal goods (player only)
* '''assisting offenders''': The bounty adjustment applied when a clean ship escorts an offender, or vice versa (NPC only)
* '''new galaxy''': The ship entered a new galaxy (player only)
* '''new system''': The ship entered a new system
* '''paid fine''': The ship was marked for fines by police, and then paid them on docking (player only)
* '''escape pod''': The ship is a replacement ship from escape pod insurance (player only)
* '''assisting police''': The ship helped out a police ship in combat
* '''unknown''': The bounty changed for an unknown reason. This should not occur.

this.shipBountyChanged = function(delta,reason)
{
// Your code here
}

==== <code>shipCloseContact</code> ====

The <code>shipCloseContact</code> handler is sent when approaching otherShip and when "track_contacts" in shipData is <code>true</code>.

this.shipCloseContact = function(otherShip)
{
// Your code here
}

==== <code>shipCollided</code> ====

The <code>shipCollided</code> handler is sent after a collision with otherShip.

this.shipCollided = function(otherShip)
{
// Your code here
}

==== <code>shipDumpedCargo</code> ====
{{oolite-method-added|1.83}}

The <code>shipDumpedCargo</code> handler is sent when this ship dumps a cargo pod.

this.shipDumpedCargo = function(cargo: ship)
{
// Your code here
}

==== <code>shipNowFacingDestination</code> ====
{{Oolite-method-added|1.79}}

The <code>shipNowFacingDestination</code> handler is called when the ship is facing its destination during certain flight behaviours.

this.shipNowFacingDestination = function()
{
// Your code here
}

==== <code>shipReachedEndPoint</code> ====

The <code>shipReachedEndPoint</code> handler is sent after reaching the last navigation point when in mode <code>performFlyRacepoints</code>.

shipReachedEndPoint = function()
{
// Your code here
}

==== <code>shipReachedNavPoint</code> ====

The <code>shipReachedNavPoint</code> handler is sent after reaching a navigation point when in mode <code>performFlyRacepoints</code>.

this.shipReachedNavPoint = function()
{
// Your code here
}

==== <code>shipScoopedOther</code> ====

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. 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.

this.shipScoopedOther = function(whom)
{
// Your code here
}

==== <code>shipLaunchedEscapePod</code> ====

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.

this.shipLaunchedEscapePod = function(escapepod, passengers)
{
// Your code here
}

<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.

=== NPC only ===

==== <code>aiAwoken</code> ====
{{oolite-method-added|1.79}}

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.

==== <code>aiStarted</code> ====
{{oolite-method-added|1.79}}

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.

==== <code>coordinatesForEscortPosition</code> ====

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.

coordinatesForEscortPosition = function(num,max)
{
// Your code here
return escort_position;
}

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.

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.

==== <code>entityDestroyed</code> ====
{{oolite-method-added|1.75.1}}

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.

entityDestroyed = function()
{
// Your code here
}

==== <code>escortAccepted</code> ====

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.

this.escortAccepted = function(mothership)
{
// Your code here
}

==== <code>escortDock</code> ====

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.

this.escortDock = function(delay)
{
// Your code here
}

==== <code>escortRejected</code> ====
{{oolite-method-added|1.79}}

The <code>escortRejected</code> handler is called when a mother ship rejects this ship as an escort.

this.escortRejected = function(mothership)
{
// Your code here
}

==== <code>offenceCommittedNearby</code> ====

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.

this.offenceCommittedNearby = function(attacker, victim)
{
// Your code here
}

==== <code>scriptedAI</code> ====
{{oolite-method-added|1.77}}

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]]

this.scriptedAI = function(delta)
{
// Your code here
return flightParameters;
}

==== <code>shipAcceptedEscort</code> ====

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.

this.shipAcceptedEscort = function(newEscort)
{
// Your code here
}

==== <code>shipLandedOnPlanet</code> ====
{{oolite-method-added|1.77}}

The <code>shipLandedOnPlanet</code> handler is called for ships landing on a planet. It transfers the <code>planet</code> parameter.

shipLandedOnPlanet = function(planet)
{
// Your code here
}

==== <code>shipRemoved</code> ====

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.

shipRemoved = function(suppressDeathEvent)
{
// Your code here
}

==== <code>shipSpawned</code> ====

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.

this.shipSpawned = function()
{
// Your code here
}

==== <code>spawnedAsEscort</code> ====

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.

this.spawnedAsEscort = function(mother)
{
// Your code here
}

==== <code>shipWasDumped</code> ====

The <code>shipWasDumped</code> handler is sent to the cargopod when a ship jettisons it. The dumping ship is transferred as the argument.

this.shipWasDumped = function(dumper)
{
// Your code here
}

==== <code>shipWasScooped</code> ====

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>.

this.shipWasScooped = function(scooper)
{
// Your code here
}

=== Stations only ===

==== <code>alertConditionChanged</code> ====

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]].

this.alertConditionChanged = function(newCondition, oldCondition)
{
// Your code here
}

==== <code>otherShipDocked</code> ====

The <code>otherShipDocked</code> handler is called with a station script only, when an ship docks. It has the docked ship as argument.

this.otherShipDocked = function(whom)
{
// Your code here
}

==== <code>stationDockingQueuesAreEmpty</code> ====
{{oolite-method-added|1.79}}

The <code>stationDockingQueuesAreEmpty</code> handler is called when the last ship in the queues docks with the station (or gives up docking and leaves).

this.stationDockingQueuesAreEmpty = function()
{
// Your code here
}

==== <code>stationLaunchedShip</code> ====

The <code>stationLaunchedShip</code> handler is called with a station script only, when a ship launches. It has the launched ship as argument. 

this.stationLaunchedShip = function(whom)
{
// Your code here
}

==== <code>stationAcceptedDockingRequest</code> ====
{{oolite-method-added|1.81}}

The <code>stationAcceptedDockingRequest</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.

this.stationAcceptedDockingRequest = function(whom)
{
// Your code here
}

==== <code>stationReceivedDockingRequest</code> ====
{{oolite-method-added|1.81}}

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.

this.stationReceivedDockingRequest = function(whom)
{
// Your code here
}

(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)

==== <code>willOpenDockingPortFor</code> ====
{{oolite-method-added|1.77}}

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 <code>false</code>). It returns a boolean:
* if it returns <code>false</code> (or this handler isn't defined), this dock will not be opened later for the requesting ship, and it should not try again.
* if it returns <code>true</code>, 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.
The handler is passed the identity of the dock and the requesting ship

this.willOpenDockingPortFor = function(dock, ship)
{
// Your code here
return allow;
}

=== Docks Only ===
{{oolite-method-added|1.77}}

==== acceptDockingRequestFrom ====
{{oolite-method-added|1.77}}

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 <code>[[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsDocking]] = true</code> and be large enough to physically fit the ship.

It returns a boolean: <code>true</code> 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) or <code>false</code> to reject the request. <code>true</code> is assumed if this handler is not defined.

This handler may be called multiple times for the same ship if the ship is having difficulty finding a suitable docking queue.

this.acceptDockingRequestFrom = function(ship)
{
// Your code here
return allow;
}

==== acceptLaunchingRequestFrom ====
{{oolite-method-added|1.77}}

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 <code>[[Oolite_JavaScript_Reference:_Dock#allowsLaunching|allowsLaunching]] = true</code> and be large enough to physically fit the ship (unless the ship is the player).

It returns a boolean: <code>true</code> to accept the request (which, depending on launching queue lengths will not necessarily mean that this dock is the one that the ship uses) or <code>false</code> to reject the request. <code>true</code> is assumed if this handler is not defined.

this.acceptLaunchingRequestFrom = function(ship)
{
// Your code here
return allow;
}

=== Missing Events ===

All initially planned events have a corresponding event handler in v1.74.

If there are other events you would like to be able to respond to, please write a request [http://www.aegidian.org/bb/viewtopic.php?t=3296 on the forum].

'''See also:''' [[Oolite JavaScript Reference: World script event handlers|world script event handlers]]

----
== Links ==
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=3865 distant effects of a ship's mass or energy?] - analysis of '''collisions''' at vast distance back in 2007.

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: World script event handlers

2022-10-29T16:10:12Z

Massively Locked: replaced "function" / reworded (x7)

This page provides a list of event handlers which can be implemented inside world scripts [[Scripting Oolite with JavaScript|JavaScript scripts for Oolite]]. Additionally, ship script handlers called on the player's ship will cause an equivalent world script event.

Most event handlers can be used both in world scripts and in ship scripts. Generally speaking, handlers starting with "ship" can be used for both scripts and those starting with "player" are meant only for the player (= can only be used in a world script). Exceptions on this rule are mentioned with the individual handlers below.

World scripts can be either found inside Config\script.js, or be distinctly named .js files inside the Scripts directory - in the latter case, the worldScript.plist will list the active world scripts.

World scripts are always active.

The list of event handlers will change from version to version (usually additions of extra handlers). For this reason, any variables or functions you create as <code>this.variable</code> should have a name beginning with '_' or '$' - e.g. <code>this._variable</code> or <code>this.$variable</code> - to avoid potential conflicts with future event handlers (which will never start with '_' or '$').

=== Game State ===

==== <code>gamePaused</code> ====
{{oolite-method-added|1.81}}

This event is called when the game is paused. This is mainly useful for pausing sound playback which should not continue while the game is paused.

this.gamePaused = function()
{
// Your code here
}

==== <code>gameResumed</code> ====
{{oolite-method-added|1.81}}

This event is called when the game is resumed from pause. This is mainly useful for resuming sound playback paused in a <code>gamePaused</code> handler.

this.gameResumed = function()
{
// Your code here
}

==== <code>playerWillSaveGame</code> ====

The <code>playerWillSaveGame</code> handler is called whenever the player saves a game. The transferred message is one of the following strings: 'standardSave', 'autoSave' or 'quickSave'

this.playerWillSaveGame = function(message : String)
{
// Your code here
}

Using this event is useful for storing temporary variables in missionVariables, just before the game gets saved. missionVariables are slow in use compared to normal JS variables, therefore their use should be minimised for efficient code. The main benefit of using missionVariables is that they are saved in a saved game.

==== <code>startUp</code> ====

The <code>startUp</code> handler is called after all OXPs have been loaded. This also means that it is called every time the player loads a game, begins a new game or presses space after dying. It can be used to do one-off initialisation such as copying mission variables into <code>this.*</code> properties for efficiency or setting up data arrays to be used by the script in other handlers. (world script only)

this.startUp = function()
{
// Your code here
}

Note that from Oolite 1.79 onwards the player is in the main station while this handler runs but may be moved to another station soon after.

==== <code>startUpComplete</code> ====
{{oolite-method-added|1.79}}

The <code>startUpComplete</code> handler is run at game startup after the initial population of the system has been complete, and after the player has been moved to the station recorded in their save game. The order of world events at game start is therefore:
* <code>startUp</code>
* <code>systemWillPopulate</code> (or an alternative handler specified by the system info)
* <code>startUpComplete</code>

=== Docking ===

==== <code>shipWillDockWithStation</code> ====

The <code>shipWillDockWithStation</code> handler is called at the beginning of the docking tunnel effect.

this.shipWillDockWithStation = function(station)
{
// Your code here
}
At this moment <code>ship.dockedStation == null</code>, <code>ship.docked == true</code>, <code>ship.status == "STATUS_DOCKING"</code>

==== <code>shipDockedWithStation</code> ====

The <code>shipDockedWithStation</code> handler is called at the end of the docking tunnel effect.

this.shipDockedWithStation = function(station)
{
// Your code here
}
At this moment <code>ship.dockedStation == station</code>, <code>ship.docked == true</code>, <code>ship.status == "STATUS_DOCKED"</code> and <code>guiScreen</code> is either <code>"GUI_SCREEN_STATUS"</code> or <code>"GUI_SCREEN_REPORT"</code>. However, any identical handler from an other oxp could have changed those values. Never count on it but double check when important.

==== <code>shipWillLaunchFromStation</code> ====

The <code>shipWillLaunchFromStation</code> handler is called at the beginning of the launch tunnel effect.

this.shipWillLaunchFromStation = function(station)
{
// Your code here
}
At this moment <code>ship.dockedStation == station</code>, <code>ship.docked == false</code>, <code>ship.status == "STATUS_LAUNCHING"</code>.

==== <code>shipLaunchedFromStation</code> ====

The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect. The handler's argument is the station which launched the ship.

this.shipLaunchedFromStation = function(stationLaunchedFrom)
{
// Your code here
}

At this moment <code>ship.dockedStation == null</code>, <code>ship.docked == false</code>, <code>ship.status == "STATUS_IN_FLIGHT"</code>.

==== <code>playerStartedAutoPilot</code> ====

The <code>playerStartedAutoPilot</code> handler is called when the player starts autopilot docking. It is not called for the instantaneous dock command. The handler is called with an argument containing the station entity that is the docking target.

this.playerStartedAutoPilot = function(stationForDocking)
{
// Your code here
}

==== <code>playerCancelledAutoPilot</code> ====

The <code>playerCancelledAutoPilot</code> handler is called when the player cancels autopilot docking.

this.playerCancelledAutoPilot = function()
{
// Your code here
}

==== <code>playerDockingClearanceCancelled</code> ====
{{oolite-method-added|1.85}}

The <code>playerDockingClearanceCancelled</code> handler is called when the player withdraws their request to dock at a station.

this.playerDockingClearanceCancelled = function()
{
// Your code here
}

==== <code>playerDockingClearanceExpired</code> ====
{{oolite-method-added|1.83}}

The <code>playerDockingClearanceExpired</code> handler is called when the player exceeds the two minute window without requesting an extension

this.playerDockingClearanceExpired = function()
{
// Your code here
}

==== <code>playerDockingClearanceGranted</code> ====
{{oolite-method-added|1.85}}

The <code>playerDockingClearanceGranted</code> handler is called when the player is given permission to dock at a station. If the player is given immediate clearance to dock, this event will be called immediately after the <code>playerRequestedDockingClearance</code> event. If, however, the station is unable to give immediate clearance, then there will be some delay between the request to dock and permission being granted. This event will be called when the station actually gives docking clearance.

this.playerDockingClearanceGranted = function()
{
// Your code here
}

==== <code>playerDockingRefused</code> ====

The <code>playerDockingRefused</code> handler is called when a station refuses to provide autopilot docking instructions.

this.playerDockingRefused = function()
{
// Your code here
}

==== <code>playerRequestedDockingClearance</code> ====

The <code>playerRequestedDockingClearance</code> handler is called when a station answers on a docking request of the player by targeting the station and pressing L (shift-l).

this.playerRequestedDockingClearance = function(message)
{
// Your code here
}

Message is a string and can take the values: "DOCKING_CLEARANCE_GRANTED", "DOCKING_CLEARANCE_DENIED_TRAFFIC_OUTBOUND", "DOCKING_CLEARANCE_DENIED_TRAFFIC_INBOUND", "DOCKING_CLEARANCE_DENIED_SHIP_FUGITIVE", "DOCKING_CLEARANCE_NOT_REQUIRED", "DOCKING_CLEARANCE_EXTENDED" or "DOCKING_CLEARANCE_CANCELLED".

==== <code>playerRescuedEscapePod</code> ====
{{oolite-method-added|1.81}}

The <code>playerRescuedEscapePod</code> handler is called when the player rescues an escape pod which does not have scripted content (all consequences of scripted content escape pods are assumed to be dealt with by the specified script instead). It has three parameters:
# the rescue fee, in decicredits
# the fee reason, which can be "insurance", "bounty" or "slave" (in the latter case, the fee will always be zero)
# a dictionary like those in the <code>ship.crew</code> property describing the pod occupant

this.playerRescuedEscapePod = function(fee, reason, occupant)
{
// Your code here
}

This method is called after the escape pod has been processed, but slightly before the arrival report screen giving the results of the processing is displayed to the player.

==== <code>playerCompletedContract</code> ====
{{oolite-method-added|1.81}}

The <code>playerCompletedContract</code> handler is called when a passenger, parcel or cargo contract ends, either successfully or by defaulting on it. It is not called when all contracts are cancelled on a galactic jump. It has four parameters:
# The type of contract, which can be "cargo", "parcel" or "passenger"
# The result of the contract, which can be "success", "late", "failed", or for cargo contracts only "short"
# The fee paid for the contract in decicredits
# The contract information dictionary
Note that the fee actually paid for the contract will often ''not'' match the originally agreed fee in the contract information dictionary, as penalties for late delivery or bonuses for good service are included in the fee parameter.

this.playerCompletedContract = function(type, result, fee, contract)
{
// Your code here
}

This method is called after the contract has been processed, but slightly before the arrival report screen giving the results of the processing is displayed to the player.

==== <code>playerEnteredContract</code> ====
{{oolite-method-added|1.81}}

The <code>playerEnteredContract</code> handler is called when a passenger, parcel or cargo contract starts, just after the items have been transferred to the player ship. It has two parameters:
# The type of contract, which can be "cargo", "parcel" or "passenger"
# The contract information dictionary

this.playerEnteredContract = function(type, contract)
{
// Your code here
}

=== Witchspace Jumps ===

==== <code>playerStartedJumpCountdown</code> ====

The <code>playerStartedJumpCountdown</code> handler is called when the user starts a witchspace or galactic witchspace jump countdown. The <code>type</code> parameter is a string specifying which type of jump is occuring; currently, the possible values are “standard” and “galactic”. Other values may be added in future. The <code>seconds</code> parameter is a number specifying the number of seconds the countdown is running for.

this.playerStartedJumpCountdown = function(type, seconds)
{
// Your code here
}

==== <code>playerCancelledJumpCountdown</code> ====

The <code>playerCancelledJumpCountdown</code> handler is called when the user cancels a witchspace or galactic witchspace jump countdown.

this.playerCancelledJumpCountdown = function()
{
// Your code here
}

==== <code>playerJumpFailed</code> ====

The <code>playerJumpFailed</code> handler is called at the end of a witchspace or galactic witchspace countdown, if the jump is not possible. The <code>reason</code> parameter is a string specifying why the jump failed. The current values are:
* '''"insufficient fuel"''' - the ship no longer has enough fuel to make the jump (e.g. injector use or fuel leak).
* '''"blocked"''' - a heavy ship is near the player (specifically <code>object mass</code> / <code>object distance</code>2 >= 10.0, and <code>object distance</code> <= scanner range).
* '''"malfunction"''' - the jump malfunctioned in a way that leaves the player ship in the current system.
* '''"malfunction"''' - the Galactic Hyperdrive is damaged or removed during a galactic jump countdown.

Also theoretically possible but unlikely in current Oolite:
* '''"too far"''' - the jump destination is outside the 7LY range (but wasn't when the countdown started).
* '''"no target"''' - the jump destination is the current location (but wasn't when the countdown started).

this.playerJumpFailed = function(reason)
{
// Your code here
}

==== <code>shipWillEnterWitchspace</code> ====

The <code>shipWillEnterWitchspace</code> handler is called immediately before a witchspace jump, while the player is still in the starting system. The <code>cause</code> parameter is a string specifying what sort of jump is occuring; currently, the possible values are “standard jump”, “galactic jump” and “wormhole”. Other values may be added in future.

// 1.80 or earlier
this.shipWillEnterWitchspace = function(cause)
{
// Your code here
}

In 1.81 or later the handler gains a second parameter, describing the jump destination. For standard and wormhole jumps, this will be the system ID of the destination system. For galactic jumps, this will be the galaxy ID of the destination galaxy. (As [[Oolite JavaScript Reference: PlayerShip#galacticHyperspaceBehaviour|player.ship.galacticHyperspaceBehaviour]] may be changed during <code>shipWillEnterWitchspace</code>, it is not possible to predict in advance of a galactic jump being made what the resulting system ID in the destination galaxy will be)

// 1.81 or later
this.shipWillEnterWitchspace = function(cause, destination)
{
// Your code here
}

==== <code>shipWillExitWitchspace</code> ====

The <code>shipWillExitWitchspace</code> handler is called as a witchspace jump concludes. When it is called, the player is (from a program perspective) in the destination system, but the tunnel effect has not yet been shown. Use this event to set up elements which need to be present in-system after the player exits witchspace.

this.shipWillExitWitchspace = function()
{
// Your code here
}

==== <code>shipExitedWitchspace</code> ====

The <code>shipExitedWitchspace</code> handler is called after a witchspace jump has concluded and the tunnel effect has been shown.

this.shipExitedWitchspace = function()
{
// Your code here
}

==== <code>playerEnteredNewGalaxy</code> ====

The <code>playerEnteredNewGalaxy</code> handler is called just before shipWillExitWitchspace.

the sequence of events for a player jumping to a different galaxy is as follows:

shipWillEnterWitchspace (world event) 
playerWillEnterWitchspace (NPC ship event) 
playerEnteredNewGalaxy (world event) 
shipWillExitWitchspace (world event) 
shipExitedWitchspace (world event) 

this.playerEnteredNewGalaxy = function(galaxyNumber)
{
// Your code here
}

=== Enter/Exit Aegis ===

==== <code>shipEnteredStationAegis</code> ====

The <code>shipEnteredStationAegis</code> handler is called when the player enters the aegis of the main-station (2x scanner range from main-station). Other stations than the main-station don't give aegis messages.

this.shipEnteredStationAegis = function(station)
{
// Your code here
}

==== <code>shipExitedStationAegis</code> ====

The <code>shipExitedStationAegis</code> handler is called when the player leaves the aegis of the main-station (2x scanner range from main-station).

this.shipExitedStationAegis = function(station)
{
// Your code here
}

==== <code>shipEnteredPlanetaryVicinity</code> ====

The <code>shipEnteredPlanetaryVicinity</code> handler is called when the player enters the planet aegis (3x planet radius).

this.shipEnteredPlanetaryVicinity = function(planet)
{
// Your code here
}

==== <code>shipExitedPlanetaryVicinity</code> ====

The <code>shipExitedPlanetaryVicinity</code> handler is called when the player leaves the planet aegis (3x planet radius).

this.shipExitedPlanetaryVicinity = function(planet)
{
// Your code here
}

==== <code>shipApproachingPlanetSurface</code> ====

The <code>shipApproachingPlanetSurface</code> handler is called when the player is very close to the planet (crosses a border ± 500 meter above the surface).

this.shipApproachingPlanetSurface = function(planet)
{
// Your code here
}

==== <code>shipLeavingPlanetSurface</code> ====

The <code>shipLeavingPlanetSurface</code> handler is called when the player leaves the planet (crosses a border ± 500 meter above the surface).

this.shipLeavingPlanetSurface = function(planet)
{
// Your code here
}

=== Combat ===

==== <code>alertConditionChanged</code> ====

The <code>alertConditionChanged</code> handler is called when the player’s alert status (<code>[[Oolite JavaScript Reference: Player#alertCondition|player.alertCondition]]</code>) changes. Only the player and stations have an alert condition. (world script and station scripts)

this.alertConditionChanged = function(newCondition, oldCondition)
{
// Your code here
}

==== <code>playerTargetedMissile</code> ====

The <code>playerTargetedMissile</code> handler is called when the player targets the nearest missile by pressing "T" (shift-t).

this.playerTargetedMissile = function(missile)
{
// Your code here
}

==== <code>shipAttackedOther</code> ====

The <code>shipAttackedOther</code> handler is called when the player hits another with a laser shot. <code>other</code> is the identity of the ship being hit.

this.shipAttackedOther = function(other)
{
// Your code here
}

==== <code>shipAttackedWithMissile</code> ====

The <code>shipAttackedWithMissile</code> handler is called when a missile is fired. <code>missile</code> contains the missile entity and <code>whom</code> the identity of the ship that launched the missile.

this.shipAttackedWithMissile = function(missile, whom)
{
// Your code here
}

==== <code>shipBeingAttacked</code> ====

The <code>shipBeingAttacked</code> handler is called when a laser shot hits. <code>whom</code> the identity of the ship that attacked.

this.shipBeingAttacked = function(whom)
{
// Your code here
}

==== <code>shipBeingAttackedByCloaked</code> ====

The <code>shipBeingAttackedByCloaked</code> handler is called when a laser shot from a cloaked ship hits. Guess what, there is no parameter because he is cloaked!

this.shipBeingAttackedByCloaked = function()
{
// Your code here
}

==== <code>shipKilledOther</code> ====
{{oolite-method-added|1.75}}

The <code>shipKilledOther</code> handler is called when a ship kills an other ship. <code>whom</code> the identity of the ship that was killed. <code>damageType</code> is the type of damage.

this.shipKilledOther = function(whom : ship, damageType : string)
{
// Your code here
}

==== <code>shipReleasedEquipment</code> ====

The <code>shipReleasedEquipment</code> handler is called when a ship launches a mine (a pylon-mounted equipment item whose key ends with "_MINE"). <code>mine</code> contains the launched mine entity.

this.shipReleasedEquipment = function(mine)
{
// Your code here
}

==== <code>shipTargetDestroyed</code> ====

The <code>shipTargetDestroyed</code> handler is called when the target gets destroyed by the player. <code>target</code> contains the destroyed target entity. This command is always preceded by the <code>shipTargetLost</code> handler.

this.shipTargetDestroyed = function(target)
{
// Your code here
}

==== <code>shipDied</code> ====

The <code>shipDied</code> handler is called when the ship or player dies. Expect a <code>reset()</code> shortly when it is the player ship.

this.shipDied = function(whom, why)
{
// Your code here
}
'''whom''' contains the entity that caused the kill. '''why''' is the cause written as string and is one of: "removed", "hit a planet", "energy damage", "scrape damage", "heat damage", "cascade weapon". 
("cascade weapon" is new in 1.74 and "removed" / "energy damage" were accidentally switched in 1.73)

==== <code>shipFiredMissile</code> ====

The <code>shipFiredMissile</code> handler is called when a missile is fired. <code>missile</code> contains the missile entity and <code>target</code> the identity of the target. The handler is send to the ship that launched the missile.

this.shipFiredMissile = function(missile, target)
{
// Your code here
}

==== <code>shipTargetLost</code> ====

The <code>shipTargetLost</code> handler is called when the target gets lost. <code>target</code> contains the lost target entity.

this.shipTargetLost = function(target)
{
// Your code here
}

==== <code>shipTargetCloaked</code> ====

The <code>shipTargetCloaked</code> handler is called when the target cloakes.

this.shipTargetCloaked = function()
{
// Your code here
}

==== <code>weaponsSystemsToggled</code> ====
{{oolite-method-added|1.85}}

The <code>weaponsSystemsToggled</code> handler is called whenever the player toggles their weapons systems on or off. The <code>state</code> parameter contains the new state of the weapons systems

this.weaponsSystemsToggled = function(state : boolean)
{
// Your code here
}

=== Equipment and Cargo ===

==== <code>equipmentAdded</code> ====
{{Oolite-method-added|1.81}}

The <code>equipmentAdded</code> handler is called whenever the player ship gains an item of equipment. This includes "gaining" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is damaged. This event will fire regardless of the reason for the equipment being added to the ship.

this.equipmentAdded = function(equipmentKey)
{
// Your code here
}

This is often more convenient than monitoring both <code>equipmentRepaired</code> and <code>playerBoughtEquipment</code>, and will also detect equipment addition by script.

==== <code>equipmentDamaged</code> ====

The <code>equipmentDamaged</code> handler is called when equipment gets damaged. (world script only)

this.equipmentDamaged = function(equipmentKey)
{
// Your code here
}

==== <code>equipmentRemoved</code> ====
{{Oolite-method-added|1.81}}

The <code>equipmentRemoved</code> handler is called whenever the player ship loses an item of equipment. This includes "losing" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is repaired. This event will fire regardless of the reason for the equipment being removed from the ship.

this.equipmentRemoved = function(equipmentKey)
{
// Your code here
}

==== <code>equipmentRepaired</code> ====
{{Oolite-method-added|1.77}}

The <code>equipmentRepaired</code> handler is called when equipment gets repaired. (world script only)

this.equipmentRepaired = function(equipmentKey)
{
// Your code here
}

==== <code>playerBoughtCargo</code> ====
{{Oolite-method-added|1.77}}

The <code>playerBoughtCargo</code> handler is called when cargo is bought at the market screen. <code>commodity</code> contains the non-localised name for the cargo. You can get the localised name using <code>expandDescription("[commodity-name "+commodity+"]");</code>. <code>price</code> is price per unit in tenths of a credit.

this.playerBoughtCargo = function(commodity, units, price)
{
// Your code here
}

==== <code>playerBoughtEquipment</code> ====

The <code>playerBoughtEquipment</code> handler is called when equipment is bought at the outfit screen.

this.playerBoughtEquipment = function(equipment, paid)
{
// Your code here
}

The 'paid' parameter is added from 1.89 onwards. This is the amount of credits the player paid for the equipment, including any refunds that might have been applied during the purchase (eg when purchasing a laser and installing it in a position where a laser is already fitted, the cost of the current laser will be refunded to the player during the purchase).

==== <code>playerBoughtNewShip</code> ====

The <code>playerBoughtNewShip</code> handler is called when a new ship is bought. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerBoughtNewShip = function(ship, price)
{
// Your code here
}

The 'price' parameter is added from 1.81 onwards. It is the cost of the ship (not counting any trade-in value of the player's old ship) in credits, or zero for changes using [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip()</code>]]

'''Note:''' In a future release of Oolite, <code>playerBoughtNewShip</code> will no longer be fired when the ship is replaced using [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip()</code>]]. Instead, the <code>[[#playerReplacedShip|playerReplacedShip]]</code> event should be used. At the moment, both events (<code>playerBoughtNewShip</code> and <code>playerReplacedShip</code>) will fire.

'''See also:''' <code>[[#playerWillBuyNewShip|playerWillBuyNewShip]]</code>

==== <code>playerChangedPrimedEquipment</code> ====
{{Oolite-method-added|1.85}}

The <code>playerChangedPrimedEquipment</code> handler is called whenever the player changes the currently primed equipment (either with shift-n or ctrl-shift-n). The equipment key of the newly primed equipment will be passed as an argument.

this.playerChangedPrimedEquipment = function(equipmentKey)
{
// Your code here
}

==== <code>playerReplacedShip</code> ====
{{Oolite-method-added|1.89}}

The <code>playerReplacedShip</code> handler is called when the player ship is replaced via the JS method [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip</code>]]. May be needed to re-evaluate the old equipment as replacing a ship does not trigger equipment removal.

this.playerReplacedShip = function(ship)
{
// Your code here
}

'''See also:''' <code>[[#playerWillReplaceShip|playerWillReplaceShip]]</code>

==== <code>playerSoldCargo</code> ====
{{Oolite-method-added|1.77}}

The <code>playerSoldCargo</code> handler is called when cargo is sold at the market screen. <code>commodity</code> contains the non-localised name for the cargo. You can get the localised name using <code>expandDescription("[commodity-name "+commodity+"]");</code>. <code>price</code> is price per unit in tenths of a credit.

this.playerSoldCargo = function(commodity, units, price)
{
// Your code here
}

==== <code>shipScoopedFuel</code> ====
{{Oolite-method-added|1.77}}

The <code>shipScoopedFuel</code> handler is called whenever the player's ship transfers 0.1LY of fuel from the scoops to the tank.

this.shipScoopedFuel = function()
{
// Your code here
}

==== <code>shipScoopedOther</code> ====

The <code>shipScoopedOther</code> handler is called when a ship scoops cargo. The scooped item is transferred as argument. If the cargo is scripted cargo, but not otherwise, then the scooped cargo itself gets the handler <code>shipWasScooped</code> with the scooper as argument.

this.shipScoopedOther = function(whom)
{
// Your code here
}

==== <code>playerWillBuyNewShip</code> ====
{{Oolite-method-added|1.89}}

The <code>playerWillBuyNewShip</code> handler is called just before a new ship is bought. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerWillBuyNewShip = function(dataKey, shipyard, price, tradeIn)
{
// Your code here
}

<code>dataKey</code> is the shipdata.plist <code>dataKey</code> for the ship being purchased.

<code>shipyard</code> is a dictionary object containing details about the ship being purchased, with information similar to the following:
{
short_description: "Python: Plus Galactic Hyperdrive. Extra Energy Unit. Docking Computers. E.C.M. System. Forward weapon upgraded to military laser. Price 215 000 ₢.",
shipdata_key: "python-player",
id: "675b6b-c60a74",
price: 215000,
ship: {
...''[[shipdata.plist]]'' details of ship...
},
personality: 9807,
extras: ["EQ_GAL_DRIVE", "EQ_FUEL_SCOOPS", "EQ_ENERGY_UNIT", "EQ_FUEL_INJECTION", "EQ_DOCK_COMP", "EQ_ECM"]
}

<code>price</code> is the amount being paid the for ship.

<code>tradeIn</code> is the trade in value of the current ship.

'''See also:''' <code>[[#playerBoughtNewShip|playerBoughtNewShip]]</code>

==== <code>playerWillReplaceShip</code> ====
{{Oolite-method-added|1.89}}

The <code>playerWillReplaceShip</code> handler is called just before a ship is replaced using [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip()</code>]]. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerWillReplaceShip = function(dataKey)
{
// Your code here
}

<code>dataKey</code> is the shipdata.plist <code>dataKey</code> for the ship being purchased.

'''See also:''' <code>[[#playerReplacedShip|playerReplacedShip]]</code>

=== Other ===

==== <code>chartHightlightModeChanged</code> ====
{{oolite-method-added|1.87}}

The <code>chartHighlightModeChanged</code> handler is called whenever the highlight mode of the galactic chart is changed either manually (from player input) or programmatically (by setting the mode with <code>[[Oolite JavaScript Reference: PlayerShip#chartHighlightMode|player.ship.chartHightlightMode]]</code>). The "newMode" parameter will be one of the following:
* <code>"OOLRC_MODE_SUNCOLOR"</code>
* <code>"OOLRC_MODE_ECONOMY"</code>
* <code>"OOLRC_MODE_GOVERNMENT"</code>
* <code>"OOLRC_MODE_TECHLEVEL"</code>

this.chartHightlightModeChanged = function(newMode)
{
// Your code here
}

==== <code>compassTargetChanged</code> ====

The <code>compassTargetChanged</code> handler is called when a new target is selected. Mode can be any of the following:

COMPASS_MODE_BASIC
COMPASS_MODE_PLANET
COMPASS_MODE_STATION
COMPASS_MODE_SUN
COMPASS_MODE_TARGET
COMPASS_MODE_BEACONS

script example

this.compassTargetChanged = function(whom, mode)
{
log(' Now targeting ' + whom);
// Your code here
}

==== <code>dayChanged</code> ====
{{oolite-method-added|1.77}}

The <code>dayChanged</code> handler is called each time a new day starts. At very low frame rates while the clock is updating, it is possible for this handler to be called twice in the same frame. Therefore, clock.days will not be correct for one of the calls. Use the day number (newday parameter) passed to the handler instead.

this.dayChanged = function(newday)
{
// Your code here
}

==== <code>escapePodSequenceOver</code> ====

The <code>escapePodSequenceOver</code> handler is called at the end of the escape pod sequence, after the <code>shipLaunchedEscapePod</code> event and just prior to the <code>shipWillDockWithStation</code> and <code>shipDockedWithStation</code> events.

Use this handler if you need to override the destination for the escape pod with [[Oolite_JavaScript_Reference:_Player#setEscapePodDestination|<code>player.setEscapePodDestination()</code>]].

this.escapePodSequenceOver = function()
{
// Your code here
}

==== <code>guiScreenChanged</code> ====

The <code>guiScreenChanged</code> handler is called when the <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> changes. The ''from'' parameter is the screen it is leaving and ''to'' is the screen initially being switched to. Note that the screen can have changed again in the meantime by the action of other oxps. Therefore, it is generally better to test the global <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> to see which page is really on display instead of using the ''to'' parameter. (world script only)

This handler will only fire when switched to/from any of the following:

1.76: <code>"GUI_SCREEN_MAIN"</code>, <code>"GUI_SCREEN_STATUS"</code>(F5), <code>"GUI_SCREEN_MANIFEST"</code>(F5F5), <code>"GUI_SCREEN_SYSTEM_DATA"</code>(F7), <code>"GUI_SCREEN_OPTIONS"</code>, <code>"GUI_SCREEN_EQUIP_SHIP"</code>(F3), <code>"GUI_SCREEN_SHIPYARD"</code>(F3F3), <code>"GUI_SCREEN_SHORT_RANGE_CHART"</code>(F6), <code>"GUI_SCREEN_LONG_RANGE_CHART"</code>(F6F6), <code>"GUI_SCREEN_MARKET"</code>(F8), <code>"GUI_SCREEN_CONTRACTS"</code>, <code>"GUI_SCREEN_REPORT"</code>

1.77: adds <code>"GUI_SCREEN_INTERFACES"</code>(F4) and removes <code>"GUI_SCREEN_CONTRACTS"</code>

1.81: adds <code>"GUI_SCREEN_MARKETINFO"</code>(F8F8)

this.guiScreenChanged = function(to, from)
{
// Your code here
}

==== <code>guiScreenWillChange</code> ====

The <code>guiScreenWillChange</code> handler is called when the <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> is about to change. On these screens, a script could change the content of the page to be displayed. (world script only)

This handler will only fire when switching to/from any of the following:

<code>"GUI_SCREEN_EQUIP_SHIP"</code>(F3), <code>"GUI_SCREEN_MANIFEST"</code>(F5F5), <code>"GUI_SCREEN_MARKET"</code>(F8), <code>"GUI_SCREEN_SHIPYARD"</code>(F3F3), <code>"GUI_SCREEN_SYSTEM_DATA"</code>(F7)

1.77: adds <code>"GUI_SCREEN_INTERFACES"</code>(F4), <code>"GUI_SCREEN_STATUS"</code>(F5)

1.81: adds <code>"GUI_SCREEN_MARKETINFO"</code>(F8F8)

this.guiScreenWillChange = function(to, from)
{
// Your code here
}

==== <code>infoSystemChanged</code> ====
{{oolite-method-added|1.83}}

The <code>infoSystemChanged</code> handler is called when the system displayed in F7 is changed, e.g. by moving the small blue cursor along the planned route in the chart.

this.infoSystemChanged = function(to, from)
{
// Your code here
}

==== <code>infoSystemWillChange</code> ====
{{oolite-method-added|1.85}}

The <code>infoSystemWChange</code> handler is called just before the system displayed in F7 is updated, e.g. by moving the small blue cursor along the planned route in the chart.

this.infoSystemWillChange = function(to, from)
{
// Your code here
}

==== <code>mfdKeyChanged</code> ====
{{oolite-method-added|1.85}}

The <code>mfdKeyChanged</code> handler is called whenever the player changes the content of an MFD slot. The <code>activeMFD</code> parameter identifies which MFD slot is being changed, and the <code>mfdKey</code> specifies the key code now in use in this slot.

this.mfdKeyChanged = function(activeMFD : integer, mfdKey : string)
{
// Your code here
}

'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#setMultiFunctionDisplay|PlayerShip.setMultiFunctionDisplay()]]</code>

==== <code>missionChoiceWasReset</code> ====

The <code>missionChoiceWasReset</code> handler is called when the mission choice is set to null via script (either using the legacy script method resetMissionChice, or using mission.choice = null; in javascript)

this.missionChoiceWasReset= function()
{
// Your code here
}

==== <code>missionScreenEnded</code> ====

The <code>missionScreenEnded</code> handler is called when a mission screen ends. Note that another script may have put up a new mission screen in the meantime. (world script only)

this.missionScreenEnded = function()
{
// Your code here
}

==== <code>missionScreenOpportunity</code> ====

The <code>missionScreenOpportunity</code> handler is called if there are no mission/report screens active and the player's ship is docked. It gets fired at game startup, upon docking and after an arrival report or previous mission screen has ended. (world script only)

this.missionScreenOpportunity= function()
{
// Your code here
}

This handler works a bit different from other handlers. It fires for every installed OXP/OXZ until one creates a mission screen during this handler, and then it stops. When the mission screen ends and there is no callback function that creates a new mission screen, the <code>missionScreenOpportunity</code> is sent again to all installed OXPs/OXZs starting with the one that created the last mission screen. All this means is that when this handler fires, it is safe to show a mission screen and no further tests are needed.

==== <code>reportScreenEnded</code> ====

The <code>reportScreenEnded</code> handler is called when the last arrival-report screen ends. This is a screen that should not be written by a missionscreen. The code should wait until this eventhandler fires. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

this.reportScreenEnded = function()
{
// Your code here
}

==== <code>selectedMFDChanged</code> ====
{{oolite-method-added|1.85}}

The <code>selectedMFDChanged</code> handler is send whenever the player selects a new MFD slot (normally using the default keypress ";"). The <code>activeMFD</code> paramater is the index of the MFD which is now active.

this.selectedMFDChanged = function(activeMFD : integer)
{
// Your code here
}

==== <code>shipCollided</code> ====

The <code>shipCollided</code> handler is send after a collision with otherShip.

this.shipCollided = function(otherShip)
{
// Your code here
}

==== <code>shipSpawned</code> ====

The <code>shipSpawned</code> handler is called after an NPC ship has been added to the system. After a witchspace jump it means that first all ships are added to the system, then all the relevant shipSpawned events are triggered. 
This handler for the worldScript is new since Oolite 1.74. After the event is sent to the shipScript, it is now also send to the worldScript with the added entity as argument.

this.shipSpawned = function(ship)
{
// Your code here
}

==== <code>shipLaunchedEscapePod</code> ====

The <code>shipLaunchedEscapePod</code> handler is called when the player bails out. This will be followed by the <code>escapePodSequenceOver</code> event, and then a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds.

this.shipLaunchedEscapePod = function(escapepod)
{
// Your code here
}

==== <code>systemInformationChanged</code> ====
{{oolite-method-added|1.79}}

The <code>systemInformationChanged</code> handler is called when system information is modified. It is passed the galaxy and system ID which were changed, and the key and new value in the SystemInfo object.

To avoid problems with recursion, attempting to change the value of any system information property from within this handler will fail and log an error. Also note that changes which take place while Oolite is not running (from OXP planetinfo.plist files) will not cause this handler to be called when the game is reloaded.

this.systemInformationChanged = function(galaxy,system,key,newValue)
{
// Your code here
}

==== <code>viewDirectionChanged</code> ====

The <code>viewDirectionChanged</code> handler is called when the player view changes, with a string to indicate which view the player is facing. Amongst its possible values are "VIEW_FORWARD", "VIEW_AFT", "VIEW_PORT", "VIEW_STARBOARD",
"VIEW_CUSTOM",
"VIEW_GUI_DISPLAY".

this.viewDirectionChanged = function(viewString)
{
if (viewString == "VIEW_PORT")
{
// Your code here
}
}

=== System population ===

In Oolite 1.79 and later, functions are called to populate and repopulate the system. These functions do not have fixed names, as they depend on the system, but otherwise act like normal worldscript functions. [[Oolite System Populator|The populator page]] has more documentation on these functions.

=== Defunct ===

==== <code>equipmentDestroyed</code> ====
''Handler no longer exists in current stable version 1.80''

The <code>equipmentDestroyed</code> handler is called when equipment gets destroyed completely beyond repair. (in strict mode, 1.77 or earlier only) (world script only)

this.equipmentDestroyed = function(equipment)
{
// Your code here
}

==== <code>tickle</code> (removed in 1.77) ====

The <code>tickle</code> handler is called periodically-ish, whenever the old [[property list|plist]] scripts are updated. <code>tickle()</code> is deprecated. In new code, use appropriate event handlers or [[Oolite JavaScript Reference: Timer|timers]] instead.

=== Missing Events ===

All the initially planned events have been implemented in 1.74.

If there are other events you would like to be able to respond to, please write a request [http://www.aegidian.org/bb/viewtopic.php?t=3296 on the forum].

'''See also:''' [[Oolite JavaScript Reference: Ship script event handlers|ship script event handlers]]

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Market Scripts

2022-10-29T15:04:53Z

Massively Locked: /* updateLocalCommodityDefinition */ replaced "function"

'''Note: this page describes functionality currently only in the 1.81 development code. It may change further before being part of a stable release.'''

From Oolite 1.81 it is possible for Javascript to be used to modify station, system and trade good prices. It is possible that a single trade good price/quantity calculation may be affected by more than one script. The order of events in the calculation is as follows:

# Firstly, the primary system market is calculated
## The trade good price and quantity are generated from the values in [[trade-goods.plist]]
## The <code>updateGeneralCommodityDefinition</code> handler of the commodity's [[Trade-goods.plist#market_script|market_script]] will be called to set primary market data for the trade good
## The <code>updateLocalCommodityDefinition</code> handler of the system's [[Planetinfo.plist#market_script|market_script]] will be called to modify primary market data for the trade good.
# Secondary markets are then calculated for each non-main station
## The primary system market is copied into the secondary market, and then quantities are scaled to the station's market capacity
## If the station does not have a market script, the rules in its [[shipdata.plist#market_definition|market_definition]] are applied.
## The <code>updateGeneralCommodityDefinition</code> handler of the commodity's [[Trade-goods.plist#market_script|market_script]] will be called again to set secondary market data for the trade good.
## The <code>updateLocalCommodityDefinition</code> handler of the station's [[shipdata.plist#market_script|market_script]] will be called to modify secondary market data for the trade good.

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_Station|Station]], system : Int) : Object
This method takes an object containing the current good definition (keys as in [[trade-goods.plist]], with an additional "price" key for the current price, "quantity" for the current quantity, and "key" for the identifier of the trade good in the plist), carries out modifications to it based on the station and system, and returns the object in the same format.

In general this method should only modify the "price", "quantity", "capacity", "legality_export" and "legality_import" keys of the goodDefinition object. Modifying other keys is possible but significant caution should be used when doing so.

This method is called for scripts defined for the trade good, and is applied once for each market that good appears at. It may be called twice for the same good - once with station = <code>false</code> to set the primary market, and once with station = (Station) for each secondary market. In general distinguishing between these two cases and performing different modifications will be necessary.

=== updateLocalCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_Station|Station]], system : Int) : Object
This method takes an object containing the current good definition (keys as in [[trade-goods.plist]], with an additional "price" key for the current price, "quantity" for the current quantity, and "key" for the identifier of the trade good in the plist), carries out modifications to it based on the station and system, and returns the object in the same format.

In general this method should only modify the "price", "quantity", "capacity", "legality_export" and "legality_import" keys of the goodDefinition object. Modifying other keys is possible but significant caution should be used when doing so.

This method is called for scripts defined for the system or station, and is called once for each good in that market. To allow the same script to be applied to multiple systems or stations, the station and system parameters will give the current context.

[http://aegidian.org/bb/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==
*[[Trade-goods.plist]] which combined the following two .plists:
:*Legacy script: [[Commodities.plist]]
:*Legacy script: [[Misc_plists#illegal_goods.plist|illegal goods.plist]]

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Condition scripts

2022-10-29T14:59:24Z

Massively Locked: replaced "function" (x7)

== Condition scripts ==
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).

Conditions scripts may define any or all of the following methods. 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>

In 1.81 the scripts are extended slightly to modify ''how'' things may appear as well as whether they may appear.

=== allowAwardEquipment ===
{{oolite-method-added|1.77}}

In order for this method to be called, the <code>condition_script</code> property of an equipment item (as declared in the [[Equipment.plist]] file) must be specified, it must declare the name of the Javascript file where the method exists, and the method must exist in the referenced JavaScript file. The method will only be called for the equipment items which reference the condition script.

This method is called when the game engine needs to know whether a particular ship can have equipment fitted. In other words, it is asking whether to allow equipment to be awarded to a ship. This may be because the player is looking at possible upgrades at a station (on the F3 Equip Ship screen), 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. You would use this method to control if, and under what conditions, a piece of equipment is offered for purchase and installation. Returning a value of <code>true</code> would indicate that the equipment can be installed; returning a value of <code>false</code> indicates the equipment can't be installed and so it won't appear on the F3 Equip Ship screen, and any of the JavaScript methods to add the equipment item would fail. If the method does not exist, or returns a value other than <code>false</code>, then a value of <code>true</code> is assumed and the equipment may be added or offered for sale (subject to other conditions, of course, like TL constraints)

<code>context</code> will be one of:
* "newShip" - equipment for a ship in a station shipyard (F3 F3)
* "npc" - awarding equipment to NPC on ship setup
* "purchase" - equipment for purchase on the F3 screen
* "scripted" - equipment added by JS or legacy scripts
(Context can in theory also be "loading", "damage" or "portable", but if you see one of these, it's a bug)

this.allowAwardEquipment = function(eqKey, ship, context)
{
// your code here
return bool;
}

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:

script_info = {
"oolite-barred-equipment" = ("EQ_WEAPON_MILITARY_LASER");
}

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.

=== allowOfferShip ===
{{oolite-method-added|1.77}}

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.

this.allowOfferShip = function(shipKey)
{
// your code here
return bool;
}

=== allowShowLibraryShip ===
{{oolite-method-added|1.81}}

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 <code>true</code>.

this.allowShowLibraryShip = function(shipKey)
{
// your code here
return bool;
}

=== allowSpawnShip ===
{{oolite-method-added|1.77}}

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.

this.allowSpawnShip = function(shipKey)
{
// your code here
return bool;
}

=== updateEquipmentPrice ===
{{oolite-method-added|1.81}}

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.

this.updateEquipmentPrice = function(equipmentKey, currentPrice)
{
// your code here
return newPrice;
}

This method is called before [[Shipdata.plist#equipment_price_factor|equipment_price_factor]] is considered.

== Links ==
There is an extended bulletin board discussion with a couple of examples [http://www.aegidian.org/bb/viewtopic.php?p=286037#p286037 here] (2022).

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Mission

2022-10-28T20:43:02Z

Massively Locked: /* unmarkSystem */ added wbr tags, replaced "function"

'''Prototype:''' <code>Object</code> 
'''Subtypes:''' none

The '''mission''' global object is used to run mission screens, and perform other actions related to mission scripting.

== Properties ==

=== <code>displayModel</code> ===
'''displayModel''' : {{oojsclass|Ship}}
If currently running a mission screen with a <code>model</code>, the ship entity used to display the model. This can be animated by setting its position and orientation from a [[Oolite JavaScript Reference: Global#addFrameCallback|frame callback]]. Uses role to identify ship, so be sure to use a unique role if you want a specific ship to be showed.

=== <code>exitScreen</code> ===
{{oolite-prop-added|1.77}}
'''exitScreen''' : [[Oolite JavaScript Reference: Global#guiScreen|guiScreen]] (read/write)

This can be used to set a new exit screen for the current mission screen. Outside of a callback function, the value of this is meaningless, and setting it has no useful effect.

=== <code>markedSystems</code> ===
{{oolite-prop-added|1.77}}
'''markedSystems''' : Array (read-only)

An array of the objects currently being used to mark systems. The objects will have the same properties as those used by <code>markSystem</code> and <code>unmarkSystem</code>.

=== <code>screenID</code> ===
{{oolite-prop-added|1.77}}
'''screenID''' : String (read-only)

If there is currently a mission screen running, and it defined a screenID, then that screenID. Otherwise, this is <code>null</code>.

== Methods ==

=== <code>addMessageText</code> ===
function '''addMessageText'''(message : String)

Appends text to the currently running mission screen. Can also be used to add text to other screens like the system data (F7) screen.

=== <code>addMessageTextKey</code> ===
function '''addMessageTextKey'''(messageKey : String)

Like <code>[[#addMessageText|addMessageText()]]</code>, but looks up the specified <code>messageKey</code> in [[missiontext.plist]].

=== <code>markSystem</code> ===
function '''markSystem'''(systemNumber : Number)

Mark a system on the long range chart. Multiple systems may be marked at once, as in <code>mission.markSystem(4, 54, 222)</code>. In 1.76 and earlier a system cannot be marked twice, so:
mission.markSystem(7);
mission.markSystem(7);
mission.unmarkSystem(7);
will leave the system unmarked.

In 1.77 or later, the parameters may be objects instead of numbers. This allows control over the marker's appearance, and allows multiple markers to be placed on the same system. The object takes the following parameters:
* <code>system</code> : The system ID. This is the only required parameter.
* <code>name</code> : A string identifying the group this marker belongs to (which may be the script's name, or something more specific). If omitted, which is not recommended, this defaults to "__oolite_legacy_destinations" which is also used for marking with numbers and marking carried out by legacy scripts.
* <code>markerColor</code> : A string specifying a colour. e.g. "redColor" or "1.0 0.5 0.0". If omitted, "redColor" will be used.
* <code>markerScale</code> : A number between 0.5 and 2.0 specifying the relative size of the marker. Defaults to 1.0.
* <code>markerShape</code> : A string describing the shape of the marker. Valid values are MARKER_X, MARKER_PLUS, MARKER_SQUARE and MARKER_DIAMOND. If this value is invalid or omitted, MARKER_X will be used.

Multiple markers may be placed on the same system, provided that they have different names. If a marker with the same system and name already exists, it will be replaced.

mission.markSystem({
system: 55,
name: "my_oxp",
markerColor: "cyanColor",
markerScale: 1.5,
markerShape: "MARKER_DIAMOND"
});

'''See also:''' <code>[[#unmarkSystem|unmarkSystem()]]</code>

=== <code>runShipLibrary</code> ===
{{oolite-method-added|1.81}}
function '''runShipLibrary'''()
Display the ship library based on [[shiplibrary.plist]], including processing of condition scripts.

This is mainly useful for scenarios which override the standard scripts.

=== <code>runScreen</code> ===
function '''runScreen'''(parameters : Object [, callback : Function [, this : Object]])
Present a mission screen.

The appearance of the mission screen is defined by the properties of the <code>parameters</code> object. The currently defined properties are:
* <code>title : String</code>
* <code>titleKey : String</code> (Key in [[missiontext.plist]])
* <code>music : String</code> (name of a music file)
* <code>overlay : ''guiTextureSpecifier''</code> (name of an image used as overlay)
* <code>background : ''guiTextureSpecifier''</code> (name of a picture used as background)
* <code>backgroundSpecial: String</code> ({{oolite-prop-added|1.77}}, special background layer)
* <code>model : String</code> (Role of a ship that will be shown as rotating ship)
* <code>modelPersonality : Int</code> ({{oolite-prop-added|1.77}}, the entityPersonality assigned to the <code>model</code>. If unspecified, or in 1.76 or earlier, a random personality is used)
* <code>message : String</code>
* <code>messageKey : String</code> (Key in [[missiontext.plist]])
* <code>spinModel: Boolean</code> (If <code>false</code>, the model is shown from the top with no automatic animation.)
* <code>choices: Object</code> ({{oolite-prop-added|1.77}}, Object describing [[Oolite_JavaScript_Reference:_Mission#Advanced_choices_.281.77_or_later_only.29|advanced choices]])
* <code>choicesKey : String</code> (Key in [[missiontext.plist]])
* <code>initialChoicesKey : String</code> ({{oolite-prop-added|1.77}}, the key from <code>choicesKey</code> which is initially selected)
* <code>allowInterrupt : Boolean</code> ({{oolite-prop-added|1.77}}. If <code>true</code> (default: <code>false</code>), the mission screen can be interrupted with function keys, which does not call the callback function. Mainly intended for interfaces.)
* <code>exitScreen : ''guiScreen''</code> ({{oolite-prop-added|1.77}}, a GUI screen to exit on. If omitted, an invalid value is given, or the player is not docked, this will revert to "GUI_SCREEN_STATUS". Not all GUI screens are selectable for this: only those reachable with function keys F3 to F8)
* <code>screenID : String</code> ({{oolite-prop-added|1.77}}, an optional string which can be read later from <code>[[#screenID|mission.screenID]]</code>)
* <code>textEntry : Boolean</code> ({{oolite-prop-added|1.79}}, if it's <code>true</code>, then you get the text prompt and 'choices' and 'choicesKey' are ignored. Whatever's typed there gets passed as the parameter to the callback function. The [https://github.com/OoliteProject/oolite/blob/master/Resources/Scripts/oolite-registership.js ship registry code] has a simple example.)
* <code>customChartZoom : decimal</code> ({{oolite-prop-added|1.87}}, zoom level of the 'CUSTOM_CHART' backgroundSpecial map)
* <code>customChartCentre: Vector3D</code> ({{oolite-prop-added|1.87}}, centre position of the 'CUSTOM_CHART' backgroundSpecial map, using the internal coordinate system. The z component is always zero. Discouraged in favour of customChartCentreInLY)
* <code>customChartCentreLY: Vector3D</code> ({{oolite-prop-added|1.87}}, centre position of the 'CUSTOM_CHART' backgroundSpecial map, in LY. e.g. for Lave: (8, 34.6, 0). The z component is always zero.)
Some of these are mutually exclusive; for instance, “title” overrides “titleKey”. See [[Oolite JavaScript Reference: Global#setScreenBackground|setScreenBackground()]] for a discussion of ''guiTextureSpecifier''.

There are 21 lines available for display of the message and choices combined. (In 1.77, this is extended to 27 lines if the player's HUD is hidden)

==== runScreen callbacks ====
The callback function is a function that is called when the player makes a choice. Every runScreen can have its own specific callback function, or you can design a single function to handle multiple mission screens instead. The optional <code>this</code> parameter will be used as the <code>this</code> property of the mission screen callback. It is usually unnecessary to specify this, but if you intend the function which calls runScreen to be called from a different script, and the callback references <code>this</code>, you will need to use it.

'''Example:''' 
A simple mission screen:
mission.runScreen({
title: "My first mission screen",
message: "This am a mission screen wot is good",
choicesKey: "me_firstmission_choices"
},
function (choice)
{
if (choice === "1_YES") player.commsMessage("Yay!");
else if (choice === "2_NO") player.commsMessage("Boo.");
else player.commsMessage("Whut?");
});
In [[missiontext.plist]], you’ll need the following. The numbers are used because choices are sorted by key.
{
"me_firstmission_choices" =
{
"1_YES" = "Yes.";
"2_NO" = "No.";
"3_MAYBE" = "Maybe.";
};
}

The call does not have to be laid out as above. The parameters object can be manipulated in any way you want beforehand, and the callback function can be written out of line. For example, the following is equivalent:
var parameters = new Object();
parameters.title = "My first mission screen";
parameters.message = "This am";
parameters.choicesKey = "me_firstmission_choices";
parameters.message += " a mission screen wot is good";

function callback(choice)
{
if (choice === "1_YES") player.commsMessage("Yay!");
else if (choice === "2_NO") player.commsMessage("Boo.");
else player.commsMessage("Whut?");
}

mission.runScreen(parameters, callback);

This form is more complicated, and the ordering is less intuitive. However, it does allow you to make complex decisions about the parameters in code, and writing the callback out of line can be preferable if it’s long. It is recommended that you start out with the first approach, but keep in mind that there are other options if it becomes too limiting.

In 1.77, if <code>allowInterrupt</code> is set to <code>true</code>, it is possible that the callback function will not be called. It should therefore only be set for mission screens which can safely be interrupted without the callback. Regardless of this setting, all mission screens may be interrupted by the player launching from the station, and this possibility should be considered (in such case callback function will be called with <code>null</code> argument).

==== runScreen special backgrounds (1.77 or later only) ====

In 1.77 or later, 'backgroundSpecial' may be given the following special string values:
* <code>SHORT_RANGE_CHART</code>: Uses the short range chart (as if the player had pressed F6). The first 18 lines of the mission text will overlap the chart if used.
* <code>LONG_RANGE_CHART</code>: Uses the current long range chart (as if the player had pressed F6 twice). The first 16 lines of the mission text will overlap the chart if used.
* <code>LONG_RANGE_CHART_SHORTEST</code>: As LONG_RANGE_CHART, but if the player has a working [[Advanced Navigational Array]] then the shortest (fewest jumps, not necessarily shortest distance) route to their current destination system will be displayed.
* <code>LONG_RANGE_CHART_QUICKEST</code>: As LONG_RANGE_CHART, but if the player has a working [[Advanced Navigational Array]] then the quickest route to their current destination system will be displayed.

In 1.87 or later, 'backgroundSpecial' has these additional special string values:
* <code>SHORT_RANGE_CHART_SHORTEST</code>: As SHORT_RANGE_CHART, but if the player has a working [[Advanced Navigational Array]] then the shortest (fewest jumps, not necessarily shortest distance) route to their current destination system will be displayed.
* <code>SHORT_RANGE_CHART_QUICKEST</code>: As SHORT_RANGE_CHART, but if the player has a working [[Advanced Navigational Array]] then the quickest route to their current destination system will be displayed.
* <code>CUSTOM_CHART</code>: Displays a chart where zoom and centre position can be customised using the 'customChartZoom' and 'customChartCentreInLY' properties. The first 18 lines of the mission text will overlap the chart if used.
* <code>CUSTOM_CHART_SHORTEST</code>: As CUSTOM_CHART, but if the player has a working [[Advanced Navigational Array]] then the shortest (fewest jumps, not necessarily shortest distance) route to their current destination system will be displayed.
* <code>CUSTOM_CHART_QUICKEST</code>: As CUSTOM_CHART, but if the player has a working [[Advanced Navigational Array]] then the quickest route to their current destination system will be displayed.

With all special chart backgrounds, changes made to destination system, or to markers, will be updated immediately. 
These backgrounds will be displayed above the '<code>background</code>' (if any) but below everything else.

==== Advanced choices (1.77 or later only) ====

In 1.77 or later, choices may be set either with the 'choicesKey' parameter from missiontext.plist as before, or with the 'choices' parameter. (If both are set, 'choicesKey' will be ignored)
'''Example''' 
var options = {
"01_AGREE" : "Take the job",
"02_DECLINE" : "Politely decline"
};
if (player.bounty == 0) // only clean players have this option
{
options["03_REPORT"] = "Call the police";
}

mission.runScreen({
// title, message, etc.
choices: options
},function(choice) {
// choice handling
});

This is useful where the options available (perhaps depending on the player's ship or equipment, or on previous events in the mission) may vary in a complex fashion, to avoid the need to have a separate missiontext.plist entry for every possibility.

The value (either in <code>choicesKey</code>'s missiontext entry or <code>choices</code>) may either be a text string as in previous versions, or an object itself. If it is an object, it can take four parameters:
* 'text' is the displayed text for this key.
* 'alignment' can be 'LEFT', 'RIGHT' or 'CENTER' (the default).
* 'unselectable' can be <code>true</code> or <code>false</code> (the default for non-blank text). Unselectable rows are printed, but are skipped when moving through the options. This can be useful for keeping a consistent interface.
* 'color' can be any color specification (e.g. "orangeColor"). The default is "yellowColor", or "darkGrayColor" for unselectable rows.
For example (missiontext.plist):
"my_choice_1" = {
"01_AGREE" = {
text = "Take the job";
alignment = "LEFT";
unselectable = false;
color = "greenColor";
};
// more options
};

In 1.77, the behaviour for choices which have no text is slightly changed. These will now leave a blank and unselectable line in the option list.

==== Safe usage of runScreen ====

One warning: <code>runScreen()</code> will overwrite any existing missionscreen or GUI screen. The only safe place is using it inside a <code>missionScreenOpportunity</code> handler or the callback function from a previous mission screen (or in 1.77 onwards, inside an interface callback function), because that handler only fires when it is allowed to show such a screen. When using the command at other places, first make sure with <code>guiScreen != "GUI_SCREEN_MISSION"</code> that there is currently no missionscreen on display by another oxp.

==== Known issues ====

From Oolite 1.79, only the A-Z, a-z, 0-9 and (space) characters may be reliably entered in the 'textEntry' field. A wider selection, for boring internal reasons, is available on the Mac, and is hoped to also be available on other platforms in later releases.

=== <code>setInstructions</code> ===
function '''setInstructions'''(instructions : String, [worldScriptName : String])

Specify a message to put on the Manifest screen (usually short instructions for current mission), under the title “Missions”.

When not called from within a world script, the name of a world script must be specified so that Oolite knows which script the message belongs to. Clear the message by calling <code>setInstructions(null)</code>.

Note: the "\n" token does not provide a line break (verified in v1.9).

It is recommended that <code>setInstructions()</code> is used only when you need to customise the text for a specific scenario. For static text, use <code>[[#setInstructionsKey|setInstructionsKey()]]</code> instead.

In Oolite 1.81 onwards, the following variant is available

{{oolite-method-added|1.81}}
function '''setInstructions'''(instructions : Array, [worldScriptName : String])

If this version is used, the first array element will be a heading on the Manifest screen, and the remaining elements will be entered underneath it, rather than being entered under the "Missions" heading.

'''Example''':
mission.setInstructions(["Ship Companion:", expandMissionText ("myoxp_currentpet"),...]);
This will display Ship Companion: in yellow text on the F5F5 screen, and beneath it will show the [[String expansion|expanded]] value of the key "myoxp_currentpet" from the [[missiontext.plist]] associated with the calling world script. If not called from a world script, the worldScriptName (this.name from the script) must be provided also:
mission.setInstructions(["Ship companion:", expandMissionText ("myoxp_currentpet"),...], "myoxp's script name");

Note that because the first parameter is now an array, the line(s) to be added must be enclosed in brackets and comma separated. Also note the optional use of <code>[[Oolite JavaScript Reference: Global#expandMissionText|expandMissionText()]]</code> to retrieve text from [[missiontext.plist]]. It is also possible to construct the array before calling setInstructions, for example:<pre>
if(myoxp_petslist.length == 0) {
mission.setInstructions(null); // clear any text previously displayed by this world script on the F5F5 screen
} else {
var textArray = [];
textArray.push("Ship Companion" + (myoxp_petslist.length > 1 ? "s:" : ":")); // "Ship Companion:" or "Ship Companions:" if more than one
var i = myoxp_petslist.length - 1; // pointer to last entry in myoxp_petslist
while(i--) { // for each pet in the list, starting from the bottom (probably newest to oldest)
textArray.push(myoxp_petslist[i].name); // add the name of the pet to the text we will show on the F5F5 screen
}
mission.setInstructions(textArray); // our pets list will now be visible on the F5F5 screen until further notice (the next time we call setInstructions or one of its variants, it will replace this)
}
</pre>

'''See also:''' <code>[[#setInstructionsKey|setInstructionsKey()]]</code>

=== <code>setInstructionsKey</code> ===
function '''setInstructionsKey'''(messageKey : String, [worldScript : String])

Like <code>[[#setInstructions|setInstructions()]]</code>, but looks up the specified <code>messageKey</code> in [[missiontext.plist]].

'''See also:''' <code>[[#setInstructions|setInstructions()]]</code>

=== <code>unmarkSystem</code> ===
function '''unmarkSystem'''(systemNumbers : Number)

Remove a mark set with <code>[[#markSystem|markSystem()]]</code>. Multiple systems may be unmarked at once, as in <code>mission.unmarkSystem(4, 54, 222)</code>.

In 1.76 and earlier versions, any script can unmark a system, regardless of which script marked it or how many times it was previously marked.

In 1.77, each marker has a name, and if a system has multiple markers each marker must be removed separately. Parameters in 1.77 may be numbers or objects. Numbers remove the "__oolite_legacy_destinations" markers. Objects are the same format as in <code>markSystem</code> and remove the marker of the corresponding name (the marker style options are ignored when unmarking). In 1.77, this method will return <code>true</code> if all requested markers existed and were removed, or <code>false</code> if any of the requested markers did not exist.

'''See also:''' <code>[[#markSystem|markSystem()]]</code>

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Ship

2022-10-28T20:16:40Z

Massively Locked: /* Methods */ replaced "function" (x6)

'''Prototype:''' <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> 
'''Subtypes:''' <code>[[Oolite JavaScript Reference: Station|Station]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code>

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 an <code>Entity</code> and several others.

<code>[[Oolite JavaScript Reference: Station|Stations]]</code> and the <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code> are types of ship. Note that these more specific types have additional properties and methods.

== Properties ==
=== <code>accuracy</code> ===
{{Oolite-prop-added|1.77}}
'''accuracy''' : Number (read/write, read-only and irrelevant for player ship)
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.

For missiles, this affects the missile tracking, with 0 being the default value.

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.

=== <code>aftWeapon</code> ===
'''aftWeapon''' : EquipmentType (read-only, read/write in 1.77)
The currently equipped aft weapon, or <code>null</code>.

'''See also:''' <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code>

=== <code>AI</code> ===
'''AI''' : String (read-only)
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>"

'''See also:''' <code>[[#AIState|AIState]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AIScript|AIScript]]</code>

=== <code>AIFoundTarget</code> ===
{{oolite-prop-added|1.77}}
'''AIFoundTarget''' : Entity (read/write, read-only for player)
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.

=== <code>AIPrimaryAggressor</code> ===
{{oolite-prop-added|1.77}}
'''AIPrimaryAggressor''' : Entity (read/write, read-only for player)
The "primary aggressor" of the ship's AI. Often the last ship to attack this ship.

=== <code>AIScript</code> ===
{{oolite-prop-added|1.79}}
'''AIScript''' : String (read-only)
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>"

'''See also:''' <code>[[#AIScriptWakeTime|AIScriptWakeTime]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>, <code>[[#AI|AI]]</code>

=== <code>AIScriptWakeTime</code> ===
{{oolite-prop-added|1.79}}
'''AIScriptWaketime''' : Number (read-write)
The next game time at which the ship's Javascript-based AI script will receive an <code>aiAwoken</code> event.

=== <code>AIState</code> ===
'''AIState''' : String (read/write, read-only for player)
The ship’s plist AI’s current state.

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#reactToAIMessage|reactToAIMessage()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code>

=== <code>alertCondition</code> ===
'''alertCondition''' : Number (read-only integer)
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.

'''See also:''' [[Oolite JavaScript Reference: Station#alertCondition|station.alertCondition]]

=== <code>autoAI</code> ===
{{oolite-prop-added|1.79}}
'''autoAI''' : Boolean (read-only)
The value of the <code>"auto_ai"</code> shipdata key. If this is <code>true</code>, 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 <code>false</code>, the ship's provider would prefer you not to alter the AI of this ship but to use it as-is.

=== <code>autoWeapons</code> ===
{{oolite-prop-added|1.79}}
'''autoWeapons''' : Boolean (read-only)
The value of the <code>"auto_weapons"</code> shipdata key. If this is <code>true</code>, 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 <code>false</code>, the ship's provider would prefer you not to alter the properties of this ship but to use it as-is.

=== <code>beaconCode</code> ===
'''beaconCode''' : String (read-only in 1.76, read-write from 1.77)
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 cannot be changed by script for either the player's ship or the main station.

'''See also:''' <code>[[#isBeacon|isBeacon]]</code>

=== <code>beaconLabel</code> ===
{{oolite-prop-added|1.79}}
'''beaconLabel''' : String (read/write, read-only for player)
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.

=== <code>boundingBox</code> ===
{{Oolite-prop-added|1.77}}
'''boundingBox''' : Vector (read-only)
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.

Vector components match the standard model order - <code>x</code> is width, <code>y</code> is height, <code>z</code> is length.

=== <code>bounty</code> ===
'''bounty''' : Number (read/write integer)
The bounty on the ship.

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.

=== <code>cargoList</code> ===
{{oolite-prop-added|1.79}}
'''cargoList''' : Array (read-only)
A list of the ship's current cargo, grouped by cargo type.

An item looks like this:
{
unit: "t",
displayName: "Liquor/Wines",
commodity: "liquor_wines",
quantity: 3
}

This property is for non-player ships. For the player ship, use <code>[[Oolite JavaScript Reference: Manifest#list|manifest.list]]</code>.

'''See also''': <code>[[#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[#adjustCargo|adjustCargo()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>cargoSpaceAvailable</code> ===
'''cargoSpaceAvailable''' : Number (read-only integer)
The ship’s available cargo space, in tons.

'''See also''': <code>[[#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#manifest|manifest]]</code> (for the player ship), <code>[[#cargoList|cargoList]]</code> (for non-player ships), <code>[[#adjustCargo|adjustCargo()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>cargoSpaceCapacity</code> ===
'''cargoSpaceCapacity''' : Number (read-only in 1.80, read/write in 1.81, integer)
The ship’s cargo capacity, in tons.

'''See also''': <code>[[#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#manifest|manifest]]</code> (for the player ship), <code>[[#cargoList|cargoList]]</code> (for non-player ships), <code>[[#adjustCargo|adjustCargo()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>cargoSpaceUsed</code> ===
'''cargoSpaceUsed''' : Number (read-only integer)
The ship’s current cargo, in tons.

'''See also''': <code>[[#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#manifest|manifest]]</code> (for the player ship), <code>[[#cargoList|cargoList]]</code> (for non-player ships), <code>[[#adjustCargo|adjustCargo()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>collisionExceptions</code> ===
{{oolite-prop-added|1.81}}
'''collisionExceptions''' : Array (read-only)
A list of ships this ship is currently prevented from colliding with. See [[#addCollisionException|addCollisionException]] and [[#removeCollisionException|removeCollisionException]].

=== <code>commodity</code> ===
{{Oolite-prop-added|1.77}}
'''commodity''' : String (read-only)
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".

=== <code>commodityAmount</code> ===
{{Oolite-prop-added|1.77}}
'''commodityAmount''' : Number (read-only)
The amount of commodity in a cargo container. (not the number of containers in a ship)

=== <code>contracts</code> ===
'''contracts''' : Array (read-only NSDictionary)
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> 

For example, the information of the first contract can be obtained by:
player.ship.contracts[0].commodity
player.ship.contracts[0].quantity
player.ship.contracts[0].description
player.ship.contracts[0].start
player.ship.contracts[0].destination
player.ship.contracts[0].startName
player.ship.contracts[0].destinationName
player.ship.contracts[0].eta // Estimated Time of Arrival.
player.ship.contracts[0].etaDescription
player.ship.contracts[0].fee // The profit of the contract, paid out on successful delivery.
player.ship.contracts[0].premium // The sum paid to obtain the goods and paid back on successful delivery.

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.

'''See also''': <code>[[Oolite JavaScript Reference: PlayerShip#awardContract|awardContract()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removeContract|removeContract()]]</code>, <code>[[Oolite JavaScript Reference: Player#contractReputation|contractReputation]]</code>

=== <code>cloakAutomatic</code> ===
'''cloakAutomatic''' : Boolean (read/write)
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>.

=== <code>crew</code> ===
{{oolite-prop-added|1.79}}
'''crew''' : Array (read-only)
An array containing the ship's crew. Each crew member is represented as a dictionary:
{
"description":"a small yellow horned humanoid from Malama",
"name":"Masten Onlo",
"homeSystem":49,
"insuranceCredits":500,
"species":"small yellow horned humanoid",
"legalStatus":0
}

Note that in current Oolite versions ships only have a single crew member defined.

'''See also:''' <code>[[#setCrew|setCrew()]]</code>

=== <code>cruiseSpeed</code> ===
'''cruiseSpeed''' : Number (read-only nonnegative)
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.

=== <code>currentWeapon</code> ===
{{oolite-prop-added|1.77}}
'''currentWeapon''' : EquipmentType (read/write)
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.

=== <code>dataKey</code> ===
{{Oolite-prop-added|1.77}}
'''dataKey''' : String (read-only)
The ship data key used to define this ship (e.g. <code>"adder-player"</code> or <code>"coriolis-station"</code>)

=== <code>defenseTargets</code> ===
{{Oolite-prop-added|1.77}}
'''defenseTargets''' : Array (read-only)
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.

'''See also:''' <code>[[#addDefenseTarget|addDefenseTarget]]</code>, <code>[[#clearDefenseTargets|clearDefenseTargets]]</code>

=== <code>desiredRange</code> ===
{{Oolite-prop-added|1.77}}
'''desiredRange''' : Number (read/write nonnegative, read-only for player)
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.

=== <code>desiredSpeed</code> ===
'''desiredSpeed''' : Number (read/write nonnegative, read-only for player)
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>.

'''See also:''' <code>[[#cruiseSpeed|cruiseSpeed]]</code>

=== <code>destination</code> ===
{{Oolite-prop-added|1.77}}
'''destination''' : Vector (read/write, read-only for player)
The destination coordinates for the AI, used in behaviours such as <code>performFlyToRangeFromDestination</code>.

=== <code>destinationSystem</code> ===
{{Oolite-prop-added|1.79}}
'''destinationSystem''' : Number (read/write)
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.

=== <code>displayName</code> ===
'''displayName''' : String (read/write, read-only for player)
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 <code>[[#shipClassName|shipClassName]]</code> and <code>[[#shipUniqueName|shipUniqueName]]</code>.

=== <code>dockedStation</code> ===
'''dockedStation''' : [[Oolite_JavaScript_Reference:_Station | Station]]
The Station the ship is currently docked to.

=== <code>dockingInstructions</code> ===
{{oolite-prop-added|1.79}}
'''dockingInstructions''' : Object (read-only)
If the ship is currently attempting to dock with a station, this describes the next step on its docking procedure

{
station: [Station "Coriolis Station" "Coriolis Station" position: (-31043.6, -94232.3, 619036) scanClass: CLASS_STATION status: STATUS_ACTIVE],
match_rotation: 0,
ai_message: "APPROACH_COORDINATES",
speed: 512,
destination: {
x: -28033.37401563089,
y: -92813.76688970842,
z: 622226.0625336492
},
range: 96
}

'''See also:''' <code>[[#requestDockingInstructions|requestDockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code>

=== <code>energyRechargeRate</code> ===
{{Oolite-prop-added|1.79}}
'''energyRechargeRate''' : Number (read-only, read/write from 1.81)
The rate at which energy is replenished in every second. The corresponding ''[[shipdata.plist]]'' key is <code>energy_recharge_rate</code>.

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.

=== <code>entityPersonality</code> ===
'''entityPersonality''' : Number (read-only integer, read/write in 1.81 onwards)
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]].

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.

=== <code>equipment</code> ===
'''equipment''' : Array of [[Oolite JavaScript Reference: EquipmentInfo|EquipmentInfo]] (read-only)
The equipment a ship is carrying.

=== <code>escortGroup</code> ===
'''escortGroup''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]
The ship’s deployed escorts.

'''See also:''' <code>[[#maxEscorts|maxEscorts]]</code>

=== <code>escorts</code> ===
'''escorts''' : Array (read-only array of [[Oolite JavaScript Reference: Entity|Entity]]s)
The ship’s deployed escorts.

=== <code>exhaustEmissiveColor</code> ===
{{Oolite-prop-added|1.79}}
'''exhaustEmissiveColor''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
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.

=== <code>exhausts</code> ===
{{Oolite-prop-added|1.79}}
'''exhausts''' : Array (read-only)
An array of the ship's [[Oolite JavaScript Reference: ExhaustPlume|ExhaustPlume]] subentities.

=== <code>flashers</code> ===
{{Oolite-prop-added|1.79}}
'''flashers''' : Array (read-only)
An array of the ship's [[Oolite JavaScript Reference: Flasher|Flasher]] subentities.

=== <code>forwardWeapon</code> ===
'''forwardWeapon''' : EquipmentType (read-only, read/write in 1.77)
The currently equipped forward weapon, or <code>null</code>.

'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code>

=== <code>fuel</code> ===
'''fuel''' : Number (read/write)
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.

'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#fuelLeakRate|PlayerShip.fuelLeakRate]]</code>

=== <code>fuelChargeRate</code> ===
'''fuelChargeRate''' : Number (read-only)
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.

=== <code>group</code> ===
'''group''' : [[Oolite JavaScript Reference: ShipGroup|ShipGroup]]
Contains ship’s belonging to each other. Added pirate groups are an example or a station with its launched defenders. 
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. 
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.
e.g.
this.ship.group = new ShipGroup();
this.ship.group.addShip(this.ship);

=== <code>hasHostileTarget</code> ===
'''hasHostileTarget''' : Boolean (read-only)
<code>true</code> if the ship’s AI is trying to kill something, <code>false</code> otherwise. Always <code>false</code> for the player.

=== <code>hasHyperspaceMotor</code> ===
'''hasHyperspaceMotor''' : Boolean (read-only)
<code>true</code> if the ship can make witchspace jumps. The corresponding ''[[shipdata.plist]]'' entry is <code>hyperspace_motor</code>.

=== <code>hasSuspendedAI</code> ===
'''hasSuspendedAI''' : Boolean (read-only)
<code>true</code> if the ship has suspended AIs, <code>false</code> otherwise.

=== <code>heatInsulation</code> ===
'''heatInsulation''' : Number (read/write)
The ship’s heat insulation factor. 1.0 is normal, higher values mean more resistance to heat.

Note that in 1.80 and earlier writes to this property had no effect on the player ship.

=== <code>homeSystem</code> ===
{{Oolite-prop-added|1.79}}
'''homeSystem''' : Number (read/write)
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.

=== <code>hyperspaceSpinTime</code> ===
{{oolite-prop-added|1.81}}
'''hyperspaceSpinTime''' : Number (read/write)
The length of the ship's hyperspace countdown.

Setting this to a negative value disables the drive entirely.

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.

=== <code>injectorBurnRate</code> ===
{{Oolite-prop-added|1.81}}
'''injectorBurnRate''' : Number (read/write)
The rate at which the ship's injectors burn fuel in deci-LY per second. The default is 0.25.

=== <code>injectorSpeedFactor</code> ===
{{Oolite-prop-added|1.81}}
'''injectorSpeedFactor''' : Number (read/write)
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)

=== <code>isBeacon</code> ===
'''isBeacon''' : Boolean (read-only)
<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.

'''See also:''' <code>[[#beaconCode|beaconCode]]</code>

=== <code>isBoulder</code> ===
'''isBoulder''' : Boolean (read/write)
<code>true</code> if the ship is a boulder (i.e., has the role <code>"boulder"</code> in its roleset)

=== <code>isCargo</code> ===
'''isCargo''' : Boolean (read-only)
<code>true</code> if the ship is cargo (i.e., has scan_class <code>"CLASS_CARGO"</code> and contains at least one unit)

=== <code>isCloaked</code> ===
'''isCloaked''' : Boolean (read/write)
<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>.

=== <code>isDerelict</code> ===
'''isDerelict''' : Boolean (read-only)
<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")

=== <code>isFleeing</code> ===
{{oolite-prop-added|1.79}}
'''isFleeing''' : Boolean (read-only)
<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.

=== <code>isFrangible</code> ===
'''isFrangible''' : Boolean (read-only)
<code>true</code> if the ship is frangible (i.e., its subentities can be destroyed separately from the main ship), <code>false</code> otherwise.

'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code>

=== <code>isJamming</code> ===
'''isJamming''' : Boolean (read-only)
<code>true</code> if the ship has a [[Shipdata.plist#has_military_jammer|military scanner jammer]] which is currently active, <code>false</code> otherwise.

=== <code>isMinable</code> ===
{{oolite-prop-added|1.79}}
'''isMinable''' : Boolean (read-only)
<code>true</code> if the ship will break up usefully when hit by a mining laser, <code>false</code> otherwise. By default this is <code>true</code> for anything with <code>"asteroid"</code> or <code>"boulder"</code> 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]].

=== <code>isMine</code> ===
'''isMine''' : Boolean (read-only)
<code>true</code> if the ship is a mine, <code>false</code> otherwise.

=== <code>isMissile</code> ===
'''isMissile''' : Boolean (read-only)
<code>true</code> if the ship is a missile, <code>false</code> otherwise.

=== <code>isPiloted</code> ===
'''isPiloted''' : Boolean (read-only)
<code>true</code> if the ship has a pilot on board, <code>false</code> otherwise. Generally- ships, stations and escape pods have pilots whereas cargo, rocks, missiles and buoys do not.

=== <code>isPirate</code> ===
'''isPirate''' : Boolean (read-only)
<code>true</code> if the ship is a pirate vessel, <code>false</code> otherwise. Currently equivalent to <code>[[#primaryRole|primaryRole]] == "pirate"</code>.

=== <code>isPirateVictim</code> ===
'''isPirateVictim''' : Boolean (read-only)
<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.

=== <code>isPolice</code> ===
'''isPolice''' : Boolean (read-only)
<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>.

=== <code>isRock</code> ===
'''isRock''' : Boolean (read-only)
<code>true</code> if the ship is a rock (i.e., has scan_class: <code>"CLASS_ROCK"</code>)

=== <code>isThargoid</code> ===
'''isThargoid''' : Boolean (read-only)
<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>.

=== <code>isTrader</code> ===
'''isTrader''' : Boolean (read-only)
<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.

=== <code>isTurret</code> ===
{{oolite-prop-added|1.79}}
'''isTurret''' : Boolean (read-only)
<code>true</code> if the ship is a plasma turret sub-entity, <code>false</code> otherwise.

=== <code>isWeapon</code> ===
'''isWeapon''' : Boolean (read-only)
<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.

=== <code>laserHeatLevel</code>* ===
{{Oolite-prop-added|1.77}}
'''laserHeatLevel''' : Number (read-only, 0 to 1)
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.
'''laserHeatLevelAft''' : Number (read-only, 0 to 1)
'''laserHeatLevelForward''' : Number (read-only, 0 to 1)
'''laserHeatLevelPort''' : Number (read-only, 0 to 1)
'''laserHeatLevelStarboard''' : Number (read-only, 0 to 1)
The temperature of specific laser mounts can also be queried.

=== <code>lightsActive</code> ===
'''lightsActive''' : Boolean (read-write)
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.

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 <code>false</code> in their ''shipdata.plist'' declarations.

=== <code>markedForFines</code> ===
{{oolite-prop-added|1.79}}
'''markedForFines''' : Boolean (read-only)
<code>true</code> if the ship has been marked for fines the next time it docks at this system's main station.

'''See also''' : [[#markTargetForFines|markTargetForFines()]]

=== <code>maxEscorts</code> ===
{{Oolite-prop-added|1.77}}
'''maxEscorts''' : Number (read/write)
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)

'''See also:''' <code>[[#escortGroup|escortGroup]]</code>

=== <code>maxPitch</code> ===
{{Oolite-prop-added|1.77}}
'''maxPitch''' : Number (read-only, read/write from 1.81)
The maximum pitch rate of the ship, in radians per second.

'''See also:''' <code>[[#pitch|pitch]]</code>

=== <code>maxRoll</code> ===
{{Oolite-prop-added|1.77}}
'''maxRoll''' : Number (read-only, read/write from 1.81)
The maximum roll rate of the ship, in radians per second.

'''See also:''' <code>[[#roll|roll]]</code>

=== <code>maxSpeed</code> ===
'''maxSpeed''' : Number (read-only, read/write from 1.81)
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.

'''See also:''' <code>[[#speed|speed]]</code>

=== <code>maxThrust</code> ===
'''maxThrust''' : Number (read-only, read/write from 1.81)
The ship’s maximum <code>[[#thrust|thrust]]</code>. This value is the one defined as <code>thrust</code> in ''[[Shipdata.plist#thrust|shipdata.plist]]''.

=== <code>maxYaw</code> ===
{{Oolite-prop-added|1.77}}
'''maxYaw''' : Number (read-only, read/write from 1.81)
The maximum yaw rate of the ship, in radians per second.

'''See also:''' <code>[[#yaw|yaw]]</code>

=== <code>missileCapacity</code> ===
'''missileCapacity''' : Number (read-only integer)
The maximum number of missiles the ship can carry.

=== <code>missileLoadTime</code> ===
'''missileLoadTime''' : Number (read-write nonnegative)
The minimum amount of time between two missiles. The corresponding ''[[shipdata.plist]]'' key is <code>missile_load_time</code>.

=== <code>missiles</code> ===
'''missiles''' : Array (read-only array of [[Oolite JavaScript Reference: EquipmentInfo|EquipmentInfo]])
The ship’s loaded missiles.

=== <code>name</code> ===
'''name''' : String (read/write, read-only for player)
The name of the ship type (<code>name</code> key in [[shipdata.plist]]).

''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.

=== <code>parcelCount</code> ===
{{oolite-prop-added|1.77}}
'''parcelCount''' : Number (read-only integer)
The ship’s current number of parcels.

'''See also''': <code>[[Oolite JavaScript Reference: PlayerShip#addParcel|addParcel()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removeParcel|removeParcel()]]</code>

=== <code>parcels</code> ===
{{oolite-prop-added|1.77}}
'''parcels''' : Array (read-only NSDictionary)
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> 
For example, the information of the first contract can be obtained by:
player.ship.parcels[0].name
player.ship.parcels[0].start
player.ship.parcels[0].destination
player.ship.parcels[0].startName
player.ship.parcels[0].destinationName
player.ship.parcels[0].eta
player.ship.parcels[0].etaDescription
player.ship.parcels[0].fee // The final fee, paid out on successful delivery.

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.

'''See also''': <code>[[Oolite JavaScript Reference: PlayerShip#addParcel|addParcel()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removeParcel|removeParcel()]]</code>, <code>[[Oolite JavaScript Reference: Player#parcelReputation|parcelReputation]]</code>

=== <code>passengerCapacity</code> ===
'''passengerCapacity''' : Number (read-only integer)
The ship’s maximum passenger capacity.

'''See also''': <code>[[Passenger Berth]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#addPassenger|addPassenger()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removePassenger|removePassenger()]]</code>

=== <code>passengerCount</code> ===
'''passengerCount''' : Number (read-only integer)
The ship’s current number of passengers.

'''See also''': <code>[[Passenger Berth]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#addPassenger|addPassenger()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removePassenger|removePassenger()]]</code>

=== <code>passengers</code> ===
'''passengers''' : Array (read-only NSDictionary)
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> 
For example, the information of the first contract can be obtained by:
player.ship.passengers[0].name
player.ship.passengers[0].start
player.ship.passengers[0].destination
player.ship.passengers[0].startName
player.ship.passengers[0].destinationName
player.ship.passengers[0].eta
player.ship.passengers[0].etaDescription
player.ship.passengers[0].fee // The final fee, paid out on successful delivery.
player.ship.passengers[0].premium // The advance fee, already paid on acceptance of the contract.

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.

'''See also''': <code>[[Passenger Berth]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#addPassenger|addPassenger()]]</code>, <code>[[Oolite JavaScript Reference: PlayerShip#removePassenger|removePassenger()]]</code>, <code>[[Oolite JavaScript Reference: Player#passengerReputation|passengerReputation]]</code>

=== <code>pitch</code> ===
{{Oolite-prop-added|1.77}}
'''pitch''' : Number (read-only)
The rate of pitch of the ship in radians/second (positive for dive, negative for climb)

'''See also:''' <code>[[#maxPitch|maxPitch]]</code>

=== <code>portWeapon</code> ===
'''portWeapon''' : EquipmentType (read-only, read/write in 1.77)
The currently equipped port weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.

'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code>

=== <code>potentialCollider</code> ===
'''potentialCollider''' : [[Oolite JavaScript Reference: Entity|Entity]] (read-only)
The entity the ship is currently trying not to crash into, if any.

=== <code>primaryRole</code> ===
'''primaryRole''' : String (read/write, read-only for player)
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 <code>"pirate trader(0.5) escort"</code> and a ship of that type is spawned to be a trader, its <code>primaryRole</code> is <code>"trader"</code>, its <code>roles</code> are <code>["escort", "pirate", "trader"]</code> and its <code>roleWeights</code> are <code>{"escort":1, "pirate":1, "trader":0.5}</code>.

'''See also:''' <code>[[#roles|roles]]</code>, <code>[[#roleWeights|roleWeights]]</code>

=== <code>reportAIMessages</code> ===
'''reportAIMessages''' : Boolean (read/write)
Debugging facility: set to <code>true</code> to dump information about AI activity to the log.

=== <code>roleWeights</code> ===
'''roleWeights''' : Object (read-only)
The probabilities for each role in <code>[[#roles|roles]]</code>.

Example:
this.pirateProb = ship.roleWeights["pirate"]

'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roles|roles]]</code>

=== <code>roles</code> ===
'''roles''' : Array (read-only array of Strings)
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.

'''See also:''' <code>[[#primaryRole|primaryRole]]</code>, <code>[[#roleWeights|roleWeights]]</code>, <code>[[#hasRole|hasRole()]]</code>

=== <code>roll</code> ===
{{Oolite-prop-added|1.77}}
'''roll''' : Number (read-only, read/write for stations)
The rate of roll of the ship in radians/second (positive for anti-clockwise, negative for clockwise)

'''See also:''' <code>[[#maxRoll|maxRoll]]</code>, <code>[[Oolite JavaScript Reference: Station#roll|station.roll]]</code>

=== <code>savedCoordinates</code> ===
'''savedCoordinates''' : [[Oolite JavaScript Reference: Vector|Vector]] (read-write)
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>

=== <code>scanDescription</code> ===
{{Oolite-prop-added|1.81}}
'''scanDescription''' : String (read/write)
The description of the ship in the "legal status" text shown by the [[Scanner Targeting Enhancement]]. If this is <code>null</code> then the default text for the ship's scan class and bounty level will be shown.

=== <code>scannerDisplayColor1</code> ===
'''scannerDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
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.

'''See also:''' <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code>, <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code>

=== <code>scannerDisplayColor2</code> ===
'''scannerDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
The second scanner colour. If both <code>scannerDisplayColor1</code> and <code>scannerDisplayColor2</code> are specified, the scanner lollipop will alternate between the two colours.

'''See also:''' <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code>, <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code>

=== <code>scannerHostileDisplayColor1</code> ===
{{oolite-prop-added|1.81}}
'''scannerHostileDisplayColor1''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
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.

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.

'''See also:''' <code>[[#scannerHostileDisplayColor2|scannerHostileDisplayColor2]]</code>, <code>[[#scannerDisplayColor1|scannerDisplayColor1]]</code>

=== <code>scannerHostileDisplayColor2</code> ===
{{oolite-prop-added|1.81}}
'''scannerHostileDisplayColor2''' : [[Materials in Oolite#Colour specifiers|Colour specifier]] (read/write)
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.

'''See also:''' <code>[[#scannerHostileDisplayColor1|scannerHostileDisplayColor1]]</code>, <code>[[#scannerDisplayColor2|scannerDisplayColor2]]</code>

=== <code>scannerRange</code> ===
'''scannerRange''' : Number (read-only)
The range of the ship’s scanner.

=== <code>script</code> ===
'''script''' : [[Oolite JavaScript Reference: Script|Script]] (read-only)
The ship’s script.

=== <code>scriptedMisjump</code> ===
'''scriptedMisjump''' : Boolean (read/write)
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.

=== <code>scriptedMisjumpRange</code> ===
{{oolite-prop-added|1.77}}
'''scriptedMisjumpRange''' : Number (read/write)
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>.

=== <code>scriptInfo</code> ===
'''scriptInfo''' : Object (read-only)
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. 
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).

=== <code>shipClassName</code> ===
{{oolite-prop-added|1.79}}
'''shipClassName''' : String (read/write)
The name of the ship class (e.g. <code>"Python"</code>)

=== <code>shipUniqueName</code> ===
{{oolite-prop-added|1.79}}
'''shipUniqueName''' : String (read/write)
The name of this specific ship (e.g. <code>"Sunrise of Lave"</code>)

=== <code>speed</code> ===
'''speed''' : Number (read-only)
The ship’s current speed.

'''See also:''' <code>[[#maxSpeed|maxSpeed]]</code>

=== <code>starboardWeapon</code> ===
'''starboardWeapon''' : EquipmentType (read-only, read/write in 1.77)
The currently equipped forward weapon, or <code>null</code>. This is always <code>null</code> for non-player ships in 1.76.

'''See also:''' <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>

=== <code>subEntities</code> ===
'''subEntities''' : Array (read-only array of Ships)
The ships subentities, or <code>null</code> if it has none. Special subentities such as flashers and exhaust plumes are not included.

'''See also:''' <code>[[#isFrangible|isFrangible]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code>

=== <code>subEntityCapacity</code> ===
'''subEntityCapacity''' : Number (read-only integer)
The original number of subentities on the ship.

'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#restoreSubEntities|restoreSubEntities()]]</code>

=== <code>subEntityRotation</code> ===
{{oolite-prop-added|1.81}}
'''subEntityRotation''' : Quaternion (read/write)
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.

=== <code>sunGlareFilter</code> ===
{{oolite-prop-added|1.79}}
'''sunGlareFilter''' : Number (read/write)
The strength of the sun glare filter on this ship. It must be in the range 0 to 1 (0 is no filter).

=== <code>target</code> ===
'''target''' : Ship (read-write)
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.

=== <code>temperature</code> ===
'''temperature''' : Number (read/write)
The ship’s temperature, normalized such that a temperature of 1.0 is the level at which a ship starts taking heat damage.

=== <code>thrust</code> ===
'''thrust''' : Number (read/write for NPCs, read-only for player before 1.81)
The ship’s thrust, ranging from 0 to <code>[[#maxThrust|maxThrust]]</code>. This value determines how fast the ship accelerates or decelerates, specified in m/s².

'''See also:''' <code>[[#thrustVector|thrustVector]]</code>

=== <code>thrustVector</code> ===
'''thrustVector''' : Vector3D (read-only)
The inertialess velocity generated by the engines.

'''See also:''' <code>[[#thrust|thrust]]</code>, <code>[[#velocity|velocity]]</code>

=== <code>trackCloseContacts</code> ===
'''trackCloseContacts''' : Boolean (read/write)
If <code>true</code>, AI events are generated for near collisions.

=== <code>vectorForward</code> ===
'''vectorForward''' : Vector3D (read-only)
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>.

=== <code>vectorRight</code> ===
'''vectorRight''' : Vector3D (read-only)
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>.

=== <code>vectorUp</code> ===
'''vectorUp''' : Vector3D (read-only)
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>.

=== <code>velocity</code> ===
'''velocity''' : Vector3D (read/write)
The ship’s velocity.

'''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.

'''See also:''' <code>[[#thrustVector|thrustVector]]</code>

=== <code>weaponFacings</code> ===
{{Oolite-prop-added|1.77}}
'''weaponFacings''' : Number (read-only, integer in range 0-15)
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: 
1 - fore 
2 - aft 
4 - port 
8 - starboard

=== <code>weaponPosition*</code> ===
{{Oolite-prop-added|1.77}}
'''weaponPositionAft''' : Vector (read-only)
'''weaponPositionForward''' : Vector (read-only)
'''weaponPositionPort''' : Vector (read-only)
'''weaponPositionStarboard''' : Vector (read-only)

{{Oolite-prop-added|1.83}}
'''weaponPositionAft''' : Array of Vectors (read-only)
'''weaponPositionForward''' : Array of Vectors (read-only)
'''weaponPositionPort''' : Array of Vectors (read-only)
'''weaponPositionStarboard''' : Array of Vectors (read-only)

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.

In 1.83 this property changed syntax to become an array of vectors, as ships can now have multiple mounts per facing.

=== <code>weaponRange</code> ===
'''weaponRange''' : Number (read-only)
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. 
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. 
(Turrets are secondary weapons with a maximum range of 6000)

=== <code>withinStationAegis</code> ===
'''withinStationAegis''' : Boolean (read-only)
<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).

=== <code>yaw</code> ===
{{Oolite-prop-added|1.77}}
'''yaw''' : Number (read-only)
The rate of yaw of the ship in radians/second (positive for right, negative for left)

'''See also:''' <code>[[#maxYaw|maxYaw]]</code>

== Methods ==
=== <code>abandonShip</code> ===
function '''abandonShip'''() : Boolean
Returns <code>true</code> when the ship has an escape pod. It will launch all escape pods on board leaving the ship behind as a empty hulk (<code>scanClass === "CLASS_CARGO"</code>). This command does nothing when no escape pod is present. 
Presence of an escape pod can be tested with: <code>equipmentStatus("EQ_ESCAPE_POD") === "EQUIPMENT_OK"</code>

=== <code>addCollisionException</code> ===
{{oolite-method-added|1.81}}
function '''addCollisionException'''(exception : Ship)
Prevented this ship and the selected ship from colliding. See [[#collisionExceptions|collisionExceptions]] and [[#removeCollisionException|removeCollisionException]].

Prevention from collision will specifically prevent the following:

* the ships colliding with each other and suffering collision damage and/or momentum change
* the ships receiving collision warning events if they come close to each other
* 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

This has no useful effect when applied to a subentity.

Adding a collision exception which already exists has no effect but will not cause an error.

=== <code>addDefenseTarget</code>===
{{oolite-method-added|1.77}}
function '''addDefenseTarget'''(target : Ship)
Adds the target ship to this ship's list of point [[#defenseTargets|defense targets]], if it isn't already.

=== <code>adjustCargo</code>===
{{oolite-method-added|1.81}}
function '''adjustCargo'''(commodity : String, amount : Number) : Boolean
Adjust the quantity of the specified commodity carried by the ship. Amount may be negative to remove cargo. The method will return <code>false</code> if the operation would fail due to insufficient free space or carried cargo and will not make a partial adjustment in this case.

This method is for non-player ships. For the player ship, use <code>[[Oolite JavaScript Reference: PlayerShip#manifest|manifest]]</code>.

'''See also''': <code>[[#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[#cargoList|cargoList]]</code>, <code>[[#setCargoType|setCargoType()]]</code>, <code>[[#dumpCargo|dumpCargo()]]</code>

=== <code>awardEquipment</code> ===
function '''awardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean
Adds the given piece of equipment to the ship, if possible, returning <code>true</code> if successful and <code>false</code> otherwise.

Example:
ship.awardEquipment("EQ_ECM");

'''See also:''' <code>[[#canAwardEquipment|canAwardEquipment()]]</code>, <code>[[#removeEquipment|removeEquipment()]]</code>

=== <code>canAwardEquipment</code> ===
function '''canAwardEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean
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.

'''See also:''' <code>[[#awardEquipment|awardEquipment()]]</code>

=== <code>becomeCascadeExplosion</code> ===
{{oolite-method-added|1.79}}
function '''becomeCascadeExplosion'''()
This method causes the ship to explode as if it were hit by a quirium cascade.

=== <code>broadcastCascadeImminent</code> ===
{{oolite-method-added|1.79}}
function '''broadcastCascadeImminent'''()
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>

=== <code>broadcastDistressMessage</code> ===
{{oolite-method-added|1.79}}
function '''broadcastDistressMessage'''()
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.

=== <code>checkCourseToDestination</code> ===
{{oolite-method-added|1.79}}
function '''checkCourseToDestination'''()
Checks the line between the ship's current position and its destination, and returns either <code>null</code> or an Entity (usually a planet, sun or other ship) that this ship would risk collision with if it travelled along that course.

'''See also''': [[#getSafeCourseToDestination|getSafeCourseToDestination()]]

=== <code>checkScanner</code> ===
{{oolite-method-added|1.79}}
function '''checkScanner'''([poweredOnly : Boolean]) : Array
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 <code>true</code>, then only powered objects will be returned (i.e. ships with a scan class other than <code>"CLASS_CARGO"</code> or <code>"CLASS_ROCK"</code>).

This method is usually considerably quicker than <code>[[Oolite JavaScript Reference: System#filteredEntities|system.filteredEntities()]]</code> and similar methods, with little loss of accuracy, though it is still advisable to cache the result for a while before re-scanning.

=== <code>clearDefenseTargets</code>===
{{oolite-method-added|1.77}}
function '''clearDefenseTargets'''()
Clears the ship's list of point [[#defenseTargets|defense targets]].

=== <code>commsMessage</code> ===
function '''commsMessage'''(message : String [,target : Ship])
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.

'''See also''': <code>[[Oolite JavaScript Reference: Player#commsMessage|player.commsMessage()]]</code>

=== <code>damageAssessment</code> ===
{{oolite-method-added|1.79}}
function '''damageAssessment'''() : Number
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.

=== <code>dealEnergyDamage</code>===
{{oolite-method-added|1.77}}
function '''dealEnergyDamage'''(damage : Number, idealRange : Number [, velocityBias : Number])
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:
* Further away than MAX_SCANNER_RANGE (25.6km): deal no damage
* 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
* 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.

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):
* 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
* 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.
* 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)2, so the Anaconda takes about 1.5 points of damage.
* A missile fired at something else detonates 500m away from a Sidewinder. The inverse-square rule divides the damage by (500 / 32.5)2, 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.

=== <code>deployEscorts</code> ===
function '''deployEscorts'''()
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 method has already been called for the current target without meanwhile being called for a different target.

=== <code>dockEscorts</code> ===
function '''dockEscorts'''()
Dock the ship’s deployed escorts, if any.

=== <code>dumpCargo</code> ===
function '''dumpCargo'''([amount : Number, commodity: String]) : Ship
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.

In 1.79 or later, multiple items may be scheduled for dumping by passing the number as a parameter.

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.

'''See also:''' <code>[[#ejectItem|ejectItem]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code>

=== <code>ejectItem</code> ===
function '''ejectItem'''(role : String) : Ship
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 <code>scanClass</code> of the ejected item will always be <code>"CLASS_CARGO"</code>.

'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectSpecificItem|ejectSpecificItem]]</code>

=== <code>ejectSpecificItem</code> ===
function '''ejectSpecificItem'''(itemKey : String) : Ship
Spawns a ship with the ''shipdata.plist'' key <code>itemKey</code> immediately behind the ship, with a slight backwards velocity. The <code>scanClass</code> of the ejected item will always be <code>"CLASS_CARGO"</code>.

'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectItem|ejectItem]]</code>

=== <code>enterWormhole</code> ===
{{oolite-method-added|1.79}}
function '''enterWormhole'''([wormhole : Wormhole])
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.

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.

=== <code>equipmentStatus</code> ===
function '''equipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]] [, multiple : Boolean]) : String or Object
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>.

In 1.81 and later, if the optional <code>multiple</code> parameter is set to <code>true</code>, it will instead return an object in this format:
{
"EQUIPMENT_OK": 3.
"EQUIPMENT_DAMAGED": 2
}
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.

'''See also:''' <code>[[#setEquipmentStatus|setEquipmentStatus()]]</code>

=== <code>exitAI</code> ===
function '''exitAI'''()
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.

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code>

=== <code>exitSystem</code> ===
function '''exitSystem'''([targetSystem : Number]) : Boolean
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.

This method can fail for various reasons, in which case it returns <code>false</code>. It always fails for the player ship.

=== <code>explode</code> ===
function '''explode'''()
Causes the ship to explode. Works on all ships, including the main station and the player except when docked.

'''See also:''' <code>[[#remove|remove()]]</code>

=== <code>fireECM</code> ===
function '''fireECM'''()
activates an ecm burst, identical as the AI command.

=== <code>findNearestStation</code> ===
function '''findNearestStation'''()
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>.

=== <code>fireMissile</code> ===
function '''fireMissile'''([missile]) : Ship
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.

=== <code>getSafeCourseToDestination</code> ===
{{oolite-method-added|1.79}}
function '''getSafeCourseToDestination'''()
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.

'''See also''': [[#checkCourseToDestination|checkCourseToDestination()]]

=== <code>getMaterials</code> ===
{{oolite-method-added|1.77}}
function '''getMaterials'''() : Object
getMaterials() returns the ship's current materials dictionary, or if none present an empty dictionary.

'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code>

=== <code>getShaders</code> ===
{{oolite-method-added|1.77}}
function '''getShaders'''() : Object
getShaders() returns the ship's current shaders dictionary, or if none present an empty dictionary.

'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code>

=== <code>hasEquipmentProviding</code> ===
{{oolite-method-added|1.81}}
function '''hasEquipmentProviding'''(key : String) : Boolean
This method returns <code>true</code> if the ship has any equipment providing the <code>key</code> equipment type, and <code>false</code> otherwise.

=== <code>hasRole</code> ===
function '''hasRole'''(role : String) : Boolean
Returns <code>true</code> if the ship has <code>role</code> among its roles, <code>false</code> otherwise.

'''See also:''' <code>[[#roles|roles]]</code>

=== <code>markTargetForFines</code> ===
{{oolite-method-added|1.79}}
function '''markTargetForFines()'''
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.

=== <code>notifyGroupOfWormhole</code> ===
{{oolite-method-added|1.79}}
function '''notifyGroupOfWormhole()'''
Tells the ship's group about a wormhole (usually the one this ship has just entered). Causes a <code>[[Oolite JavaScript Reference: Ship script event handlers#wormholeSuggested|wormholeSuggested]]</code> event to occur in the scripts of other group members.

=== <code>offerToEscort</code> ===
{{oolite-method-added|1.79}}
function '''offerToEscort(mother : Ship)'''
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.

=== <code>perform*</code> ===
Each of these methods 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.

==== <code>performAttack</code> ====
{{oolite-method-added|1.79}}
function '''performAttack()'''
Attack the current target with available weapons.

==== <code>performCollect</code> ====
{{oolite-method-added|1.79}}
function '''performCollect()'''
Attempt to scoop up the current target. If the current target is not scoopable, it will be lost.

==== <code>performEscort</code> ====
{{oolite-method-added|1.79}}
function '''performEscort()'''
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.

==== <code>performFaceDestination</code> ====
{{oolite-method-added|1.79}}
function '''performFaceDestination()'''
Come to a stop, and turn to face the current destination coordinates.

==== <code>performFlee</code> ====
{{oolite-method-added|1.79}}
function '''performFlee()'''
Flee from the current target, using injectors if possible, until it is out of scanner range.

==== <code>performFlyToRangeFromDestination</code> ====
{{oolite-method-added|1.79}}
function '''performFlyToRangeFromDestination()'''
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.

==== <code>performHold</code> ====
{{oolite-method-added|1.79}}
function '''performHold()'''
Come to a stop, and continually turn to face the current target

==== <code>performIdle</code> ====
{{oolite-method-added|1.79}}
function '''performIdle()'''
Cancel any current turns to return to level flight, then move forward at current speed.

==== <code>performIntercept</code> ====
{{oolite-method-added|1.79}}
function '''performIntercept()'''
Fly to intercept (i.e. ram) the current target.

==== <code>performLandOnPlanet</code> ====
{{oolite-method-added|1.79}}
function '''performLandOnPlanet()'''
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.

==== <code>performMining</code> ====
{{oolite-method-added|1.79}}
function '''performMining()'''
Attack the current target with a mining laser. This does not count as hostile behaviour, so cannot be used except on rocks.

==== <code>performScriptedAI</code> ====
{{oolite-method-added|1.79}}
function '''performScriptedAI()'''
Request flight instructions from a [[OXP_Scripted_AI|scripted AI]] callback each frame.

==== <code>performScriptedAttackAI</code> ====
{{oolite-method-added|1.79}}
function '''performScriptedAttackAI()'''
Request flight instructions, including weapons fire, from a [[OXP_Scripted_AI|scripted AI]] callback each frame.

==== <code>performStop</code> ====
{{oolite-method-added|1.79}}
function '''performStop()'''
Come to a complete halt

==== <code>performTumble</code> ====
{{oolite-method-added|1.79}}
function '''performTumble()'''
Come to a complete halt and rotate randomly.

=== <code>reactToAIMessage</code> ===
function '''reactToAIMessage'''(message : String)
Immediately perform the specified handler in the ship’s current AI state.

'''See also:''' <code>[[#sendAIMessage|sendAIMessage()]]</code>

=== <code>recallDockingInstructions</code> ===
{{oolite-method-added|1.79}}
function '''recallDockingInstructions'''() : Object
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.

'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#requestDockingInstructions|requestDockingInstructions]]</code>

=== <code>remove</code> ===
function '''remove'''([suppressDeathEvent : Boolean])
Immediately removes the ship from the universe. Works on all ships except the player, including the main station. 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 <code>true</code>.

'''See also:''' <code>[[#explode|explode()]]</code>

=== <code>removeCollisionException</code> ===
{{oolite-method-added|1.81}}
function '''removeCollisionException'''(exception : Ship)
Allow this ship and the selected ship to collide again. See [[#collisionExceptions|collisionExceptions]] and [[#addCollisionException|addCollisionException]].

Removing a collision exception which does not exist has no effect but will not cause an error.

=== <code>removeDefenseTarget</code>===
{{oolite-method-added|1.79}}
function '''removeDefenseTarget'''(target : Ship)
Ensures that the target ship is not on this ship's list of point [[#defenseTargets|defense targets]].

=== <code>removeEquipment</code> ===
function '''removeEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]])
Removes the given piece of equipment from the ship.
This method 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.

Note that in Oolite prior to 1.76.1 there was a bug which could sometimes cause the game to crash if this method 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

Example:
ship.removeEquipment("EQ_ECM");

=== <code>requestDockingInstructions</code> ===
{{oolite-method-added|1.79}}
function '''requestDockingInstructions'''() : Object
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.

'''See also:''' <code>[[#dockingInstructions|dockingInstructions]]</code>, <code>[[#recallDockingInstructions|recallDockingInstructions]]</code>

=== <code>requestHelpFromGroup</code> ===
{{oolite-method-added|1.79}}
function '''requestHelpFromGroup'''()
This method 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.

=== <code>restoreSubEntities</code> ===
function '''restoreSubEntities'''() : Boolean
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.

'''See also:''' <code>[[#subEntities|subEntities]]</code>, <code>[[#isFrangible|isFrangible]]</code>

=== <code>selectNewMissile</code> ===
function '''selectNewMissile'''() : equipmentKey
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.
e.g.
this.ship.awardEquipment(this.ship.selectNewMissile())
will automatically add the 'right type' of missile to a ship, i.e. one that its captain would normally choose.

=== <code>sendAIMessage</code> ===
function '''sendAIMessage'''(message : String)
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.

'''See also:''' <code>[[#reactToAIMessage|reactToAIMessage()]]</code>

=== <code>setAI</code> ===
function '''setAI'''(AIName : String)
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).

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>

=== <code>setBounty</code> ===
{{oolite-method-added|1.77}}
function '''setBounty'''(bounty : Number, reason : String)
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()]].

'''See also:''' <code>[[#bounty|bounty]]</code>

=== <code>setCargo</code> ===
function '''setCargo'''(commodity : String [, count : Number]) : Boolean
Attempts to create <code>count</code> weight units of the <code>commodity</code> specified for a cargo barrel. This cannot be used to set cargo for ships. When more units are defined than 1 ton, the count is reduced to 1 ton. It returns <code>false</code> when the selected commodity is unknown. If <code>count</code> is not specified, <code>1</code> will be assumed.

=== <code>setCargoType</code> ===
{{oolite-method-added|1.79}}
function '''setCargoType'''(commodityType : String) : Boolean
Attempts to set the ship's cargo hold to contain commodities of the specified type, discarding any cargo already present. This should generally only be used immediately after a ship is spawned. Valid commodity types are:
*<code>"SCARCE_GOODS"</code>: goods which are likely to be rare in the current system, usually legal
*<code>"PLENTIFUL_GOODS"</code>: goods which are likely to be plentiful in the current system, usually legal
*<code>"MEDICAL_GOODS"</code>: narcotics (used for the Moray Medical Boat)
*<code>"ILLEGAL_GOODS"</code>: various goods likely to be rare in the current system, with a strong bias towards contraband
*<code>"PIRATE_GOODS"</code>: similar to <code>"ILLEGAL_GOODS"</code> but the total amount carried will be lower
This will return <code>false</code> 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.

=== <code>setCrew</code> ===
{{oolite-method-added|1.79}}
function '''setCrew'''(Object) : Boolean
Sets the ship's crew to one represented by the given object (or sets the ship to uncrewed if <code>null</code> is given as a parameter). Returns <code>true</code> if this succeeds, <code>false</code> 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:
* origin system
* random seed
* role
* the rest
You can therefore set a random seed or role to get particular behaviour, and use the other keys to override it.

At the moment this method only sets the first crew member (the pilot of the ship) in [[Oolite JavaScript Reference: Ship#crew|crew]][0] .

=== <code>setEquipmentStatus</code> ===
function '''setEquipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]], statusKey : String)
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>.

'''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.

'''See also:''' <code>[[#equipmentStatus|equipmentStatus()]]</code>, <code>[[Oolite JavaScript Reference: EquipmentInfo#canBeDamaged|EquipmentInfo.canBeDamaged]]</code>for equipment that cannot be damaged

=== <code>setMaterials</code> ===
function '''setMaterials'''(materialDictionary : Object [, shaderDictionary : Object]) : Boolean
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.

'''Example:'''
this.ship.setMaterials({"my_ship_diffuse.png": { diffuse_map: "my_ship_damaged_diffuse.png" }});

'''See also:''' <code>[[#setShaders|setShaders()]]</code>, <code>[[#getMaterials|getMaterials()]]</code>

=== <code>setScript</code> ===
function '''setScript'''(scriptName : String)
Set, or completely replace, the javascript code associated to a ship entity.

=== <code>setShaders</code> ===
function '''setShaders'''(shaderDictionary : Object) : Boolean
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.

'''See also:''' <code>[[#setMaterials|setMaterials()]]</code>, <code>[[#getShaders|getShaders()]]</code>

=== <code>spawn</code> ===
function '''spawn'''(role : String [, count : Number]) : Array
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.

<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:
* The spawned ships inherit most of the temperature of the parent.
* 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.
* <code>spawn()</code> does not set up escorts for the new ships, or generate witchspace effects, or do any special AI handling.

=== <code>spawnOne</code> ===
function '''spawnOne'''(role : String) : Ship
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.

=== <code>switchAI</code> ===
function '''switchAI'''(AIName : String)
Set the current AI, exiting the old one. Equivalent to the <code>[[AI_methods|switchAITo]]:</code> AI method. May not be used on player.

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>

=== <code>threatAssessment</code> ===
{{oolite-method-added|1.79}}
function '''threatAssessment'''(full : Boolean) : Number
Returns a number indicating the relative strength of the ship. If the 'full' parameter is <code>true</code>, 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.

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.

=== <code>throwSpark</code> ===
{{oolite-method-added|1.79}}
function '''throwSpark'''()
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.

=== <code>updateEscortFormation</code> ===
function '''updateEscortFormation'''()
Request that the game updates the target positions for the ship’s escorts by calling the ship’s script’s <code>coordinatesForEscortPosition()</code> method.

== Static Methods ==
=== <code>keys</code> ===
{{Oolite-method-added|1.79}}
function '''keys'''() : Array
Returns all dataKeys of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.

'''Example:'''
var dataKeysArray = Ship.keys();

=== <code>keysForRole</code> ===
{{Oolite-method-added|1.79}}
function '''keysForRole'''(role : String) : Array
Returns all dataKeys of ships defined in all [[shipdata.plist]] which contains the given role.

'''Example:'''
var role = "trader";
var roleKeys = Ship.keysForRole( role );
log("keysForRole", role + ": " + roleKeys );

=== <code>roleIsInCategory</code> ===
{{Oolite-method-added|1.79}}
function '''roles'''(role : String, category : String) : Boolean
Returns whether the role given is in a particular category as defined in [[role-categories.plist]]

'''Example:'''
Ship.roleIsInCategory("trader","oolite-pirate-victims"); // true

=== <code>roles</code> ===
{{Oolite-method-added|1.79}}
function '''roles'''() : Array
Returns all roles of ships defined in all [[shipdata.plist]] including installed [[OXP]]s.

'''Example:'''
var roles = Ship.roles();
for( var i = 0; i < roles.length; i++ ) {
var roleKeys = Ship.keysForRole( roles[i] );
log("roles", i + ". "+roles[i] + ": " + roleKeys );
}

=== <code>shipDataForKey</code> ===
{{Oolite-method-added|1.79}}
function '''shipDataForKey'''(datakey : String) : Object
Returns an object containing a representation of the raw [[shipdata.plist]] entry for a given data key, or <code>null</code> 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.

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.

'''Example:'''
var shipdata = Ship.shipDataForKey("cobra3-trader");
log("test",shipdata["name"]); // "Cobra Mark III"
log("test",shipdata["ship_class_name"]); // undefined
log("test",shipdata["ship_unique_name"]); // undefined
log("test",shipdata["display_name"]); // undefined

===<code>setShipDataForKey</code>===
{{Oolite-method-added|1.91}}
function '''setShipDataForKey'''(datakey : String, newShipData : Object)
This method modifies or adds properties of a ship class specified by the datakey parameter. The newShipData parameter can be an existing property defined in shipdata.plist or a new one.

'''Example:'''
Ship.setShipDataForKey ("cobra3-trader", {name: "Cobra trader variant"})
var shipdata = Ship.shipDataForKey ("cobra3-trader")
log ("test", shipdata ["name"])

'''See also''': [http://www.aegidian.org/bb/viewtopic.php?p=274534#p274534 bulletin board post by Tsoj]

==See also==
*[[Shipdata.plist]]

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Vector3D

2022-10-28T19:49:27Z

Massively Locked: /* Methods */ replaced "function" (x2), added code tags

'''Prototype:''' <code>Object</code> 
'''Subtypes:''' none

The '''<code>Vector3D</code>''' class represents a [http://en.wikipedia.org/wiki/Vector_%28spatial%29 geometrical vector] in three-dimensional space, in cartesian representation. It is used to represent positions, headings and velocities. Explaining vector geometry is beyond the scope of this document, but there are numerous tutorials on the web.

=== Vector Expressions ===
All Oolite-provided functions which take a vector as an argument may instead be passed an array of three numbers, or an [[Oolite JavaScript Reference: Entity|Entity]] (in which case the entity’s <code>[[Oolite JavaScript Reference: Entity#position|position]]</code> is used). In specifications, this is represented by arguments typed <code>vectorExpression</code>. For example, if <code>a</code> and <code>b</code> are vectors whose values are (0, 1, 0) and (1, 0, 0) respectively, the following are equivalent:

var c = a.add(b);
var d = a.add(Vector3D(1, 0, 0));
var e = a.add([1, 0, 0]);
// c, d and e are now all (1, 1, 0).

== Properties ==
=== <code>x</code> ===
'''x''' : Number (read/write)
The ''x'' co-ordinate of the vector.

=== <code>y</code> ===
'''y''' : Number (read/write)
The ''y'' co-ordinate of the vector.

=== <code>z</code> ===
'''z''' : Number (read/write)
The ''z'' co-ordinate of the vector.

== Methods ==
=== Constructor ===
'''new Vector3D'''([value : [[#Vector Expressions|vectorExpression]]]) : Vector3D
Create a new vector with the specified value. If no value is provided, the vector is initialized to (0, 0, 0).

=== <code>add</code> ===
function '''add'''(v : [[#Vector Expressions|vectorExpression]]) : Vector3D
Returns the vector sum of the target and <code>v</code>.

'''See Also:''' <code>[[#subtract|subtract]]()</code>

=== <code>angleTo</code> ===
function '''angleTo'''(v : [[#Vector Expressions|vectorExpression]]) : Number
Returns the angle (in radians) between the target and <code>[[#Vector Expressions|vectorExpression]]</code>. This is always a positive value between 0 and π.

<code>v.angleTo(u)</code> is equivalent to <code>Math.[https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Math/acos acos](v.[[#direction|direction]]().[[#dot|dot]](u.[[#direction|direction]]()))</code>.

=== <code>cross</code> ===
function '''cross'''(v : [[#Vector Expressions|vectorExpression]]) : Vector3D
Returns the [http://en.wikipedia.org/wiki/Vector_%28spatial%29#Cross_product cross product] of the target and <code>[[#Vector Expressions|vectorExpression]]</code>.

'''See Also:''' <code>[[#dot|dot]]()</code>

=== <code>direction</code> ===
function '''direction'''() : Vector3D
Returns the [http://en.wikipedia.org/wiki/Unit_vector unit vector] with the same direction as the target.

<code>v.direction()</code> is equivalent to <code>v.[[#multiply|multiply]](1 / v.[[#magnitude|magnitude]]())</code>.

'''See Also:''' <code>[[#magnitude|magnitude]]()</code>

=== <code>distanceTo</code> ===
function '''distanceTo'''(v : [[#Vector Expressions|vectorExpression]]) : Number
Returns the distance between the source vector and <code>v</code>. If <code>v</code> is not a vector, then if it is an [[Oolite JavaScript Reference: Entity|Entity]] its position will be used; and if it is an array of three values (for example, <code>[x, y, z]</code> or <code>[1, 2, 3]</code>), it will be treated as a vector with those coordinates.

<code>u.distanceTo(v)</code> is equivalent to <code>u.[[#subtract|subtract]](v).[[#magnitude|magnitude]]()</code>.

'''CAUTION:''' If passed an invalid <code>v</code>, the method will return zero, not log an error. It is also incorrect to call <code>distanceTo</code> on something that is not a vector. For example: <code>this.ship.distanceTo(v)</code> is missing <code>position</code> and needs to be written as <code>this.ship.position.distanceTo(v)</code>.

'''See Also:''' <code>[[#squaredDistanceTo|squaredDistanceTo]]()</code>

=== <code>dot</code> ===
function '''dot'''(v : [[#Vector Expressions|vectorExpression]]) : Number
Returns the [http://en.wikipedia.org/wiki/Vector_%28spatial%29#Dot_product dot product] of the target and <code>v</code>.

The dot product of two vectors says something how well they are aligned to each other. The dot product of two identical vectors is 1 while two vectors pointing in opposite direction result in a -1 result. Also you can't reliably compare two vectors with each other to see if they are identical. To check if <code>vector1 == vector2</code> you need the dot product :
vector1.dot(vector2) > 0.999

'''See Also:''' <code>[[#cross|cross]]()</code>

=== <code>fromCoordinateSystem</code> ===
function '''fromCoordinateSystem'''(system : String) : Vector3D
Convert a vector from an [[Oolite coordinate systems|abstract coordinate system]] to absolute coordinates. <code>system</code> must be a three-letter string specifying an abstract coordinate system.

'''Important:'''
Vectors do not “know” which coordinate system they’re in. The script must keep track of that. If you add together vectors in different coordinate systems the result will be nonsense, just as if you added measurements in different units without appropriate conversions.

'''Example:'''
this.halfway = Vector3D(0, 0, 0.5).fromCoordinateSystem("wpu");
// Equivalent: Vector3D.interpolate([0, 0, 0], S.mainPlanet, 0.5)

'''See Also:''' <code>[[#toCoordinateSystem|toCoordinateSystem]]()</code>

=== <code>magnitude</code> ===
function '''magnitude'''() : Number
Returns the magnitude (or length) of the vector.

'''See Also:''' <code>[[#squaredMagnitude|squaredMagnitude]]()</code>, <code>[[#direction|direction]]()</code>

=== <code>multiply</code> ===
function '''multiply'''(f : Number) : Vector3D
Returns the product of the target and <code>f</code>. This has the effect of scaling the vector by the factor <code>f</code>.

=== <code>rotateBy</code> ===
function '''rotateBy'''(q : [[Oolite JavaScript Reference: Quaternion#Quaternion Expressions|quaternionExpression]]) : Vector3D
Apply the rotation specified by <code>q</code> to the target vector.

=== <code>rotationTo</code> ===
function '''rotationTo'''(v : [[#Vector Expressions|vectorExpression]] [, maxArc : Number]) : [[Oolite JavaScript Reference: Quaternion|Quaternion]]
Returns a [[Oolite JavaScript Reference: Quaternion|quaternion]] corresponding to a rotation from the target vector to <code>v</code>. The optional parameter <code>maxArc</code> specifies a maximum rotation angle; if the angle between the target and <code>v</code> is greater than <code>maxArc</code> radians, a rotation of <code>maxArc</code> radians towards <code>vectorExpression</code> is generated instead.

Both the target and <code>v</code> must be normalized. The vectors must not be antiparallel (180° apart), since the axis of rotation is undefined in this case.

'''Example:'''
var orientation = myVector.rotationTo([0, 0, 1])
This will generate a quaternion were the <code>forwardVector</code> is pointing in the same direction as <code>myVector</code>. (<code>[0, 0, 1]</code> is equal to the <code>forwardVector</code> of the identity quaternion.)

=== <code>squaredDistanceTo</code> ===
function '''squaredDistanceTo'''(v: [[#Vector Expressions|vectorExpression]]) : Number
Returns the square of the distance between the source vector and vector <code>v</code>. If <code>v</code> is not a vector, then if it is an [[Oolite JavaScript Reference: Entity|Entity]] its position will be used; and if it is an array of three values (for example, <code>[x, y, z]</code> or <code>[1, 2, 3]</code>), it will be treated as a vector with those coordinates.

<code>u.squaredDistanceTo(v)</code> is equivalent to <code>u.[[#distanceTo|distanceTo]](v) * u.[[#distanceTo|distanceTo]](v)</code>, or <code>u.[[#subtract|subtract]](v).[[#squaredMagnitude|squaredMagnitude]]()</code>.

'''CAUTION:''' If passed an invalid <code>v</code>, the method will return zero, not log an error. It is also incorrect to call <code>squaredDistanceTo</code> on something that is not a vector. For example: <code>this.ship.squaredDistanceTo(v)</code> is missing <code>position</code> and needs to be written as <code>this.ship.position.squaredDistanceTo(v)</code>.

'''See Also:''' <code>[[#distanceTo|distanceTo]]()</code>

=== <code>squaredMagnitude</code> ===
function '''squaredMagnitude'''() : Number
Returns the square of the magnitude of the vector.

<code>v.squaredMagnitude()</code> is equivalent to <code>v.[[#magnitude|magnitude]]() * v.[[#magnitude|magnitude]]()</code>.

=== <code>subtract</code> ===
function '''subtract'''(v : [[#Vector Expressions|vectorExpression]]) : Vector3D
Returns the vector difference between the target and <code>v</code>.

'''See Also:''' <code>[[#add|add]]()</code>

=== <code>toArray</code> ===
function '''toArray'''() : Array
Returns an array of the vector’s components, in the order <code>[x, y, z]</code>. <code>v.toArray()</code> is equivalent to <code>[v.x, v.y, v.z]</code>.

=== <code>toCoordinateSystem</code> ===
function '''toCoordinateSystem'''(system : String) : Vector3D
Convert a vector from absolute coordinates to an [[Oolite coordinate systems|abstract coordinate system]]. <code>system</code> must be a three-letter string specifying an abstract coordinate system. The target of the method must be a vector in absolute coordinates. (To convert a vector from one abstract coordinate system to another, you must first call code>[[#fromCoordinateSystem|fromCoordinateSystem]]()</code>, then <code>toCoordinateSystem()</code>.)

'''Important:'''
Vectors do not “know” which coordinate system they’re in. The script must keep track of that. If you add together vectors in different coordinate systems the result will be nonsense, just as if you added measurements in different units without appropriate conversions.

'''Example:'''
Vector3D(0, 0, 226380).toCoordinateSystem("wpu")
// In Lave system, this returns (0, 0, 0.5).

'''See Also:''' <code>[[#fromCoordinateSystem|fromCoordinateSystem]]()</code>

=== <code>tripleProduct</code> ===
function '''tripleProduct'''(v : [[#Vector Expressions|vectorExpression]], w : [[#Vector Expressions|vectorExpression]]) : Number
Returns the [http://en.wikipedia.org/wiki/Vector_%28spatial%29#Triple_product triple product] of the target, <code>v</code> and <code>w</code>.

<code>u.tripleProduct(v, w)</code> is equivalent to <code>u.[[#dot|dot]](v.[[#cross|cross]](w))</code>.

== Static methods ==

=== <code>interpolate</code> ===
function '''interpolate'''(u : [[#Vector Expressions|vectorExpression]], v : [[#Vector Expressions|vectorExpression]], where : Number) : Vector3D
Returns a point on the line between <code>u</code> and <code>v</code>. If <code>where</code> is 0, the result is <code>u</code>. If <code>where</code> is 1, the result is <code>v</code>. If <code>where</code> is 0.5, the result is half way between <code>u</code> and <code>v</code>. Values of <code>where</code> outside the range [0, 1] are valid; for instance, <code>Vector3D.interpolate(u, v, -1)</code> returns a point as far from <code>u</code> as <code>v</code> is, but in the opposite direction.

<code>Vector3D.interpolate(u, v, where)</code> is equivalent to <code>u.[[#add|add]](v.[[#subtract|subtract]](u).[[#multiply|multiply]](where))</code>, or <code>u.[[#multiply|multiply]](1 - where).[[#add|add]](v. [[#multiply|multiply]](where))</code>.

=== <code>random</code> ===
function '''random'''([maxLength : Number]) : Vector3D
Returns a vector of random length up to <code>maxLength</code>, in a random direction. If <code>maxLength</code> is not specified (or not a number), 1.0 is used. These vectors are uniformly distributed within the unit sphere, which has the effect that longer vectors are more common than shorter ones. Use <code>Vector3D.[[#randomDirectionAndLength|randomDirectionAndLength]]()</code> if an even length distribution is desired.

In the following image, the cloud on the left was made with the 2D equivalent of <code>random()</code>, and the image on the right was made with the 2D equivalent of <code>randomDirectionAndLength()</code>. [[Image:Randomvectordistribution.png]]

'''See Also:''' <code>[[#randomDirection|randomDirection]]()</code>, <code>[[#randomDirectionAndLength|randomDirectionAndLength]]()</code>

=== <code>randomDirection</code> ===
function '''randomDirection'''([scale : Number]) : Vector3D
Returns a vector of length <code>scale</code>, in a random direction. If <code>scale</code> is not specified (or not a number), 1.0 is used.

'''See Also:''' <code>[[#random|random]]()</code>, <code>[[#randomDirectionAndLength|randomDirectionAndLength]]()</code>

=== <code>randomDirectionAndLength</code> ===
function '''randomDirectionAndLength'''([maxLength : Number]) : Vector3D
Returns a vector of random length up to <code>maxLength</code>, in a random direction. If <code>maxLength</code> is not specified (or not a number), 1.0 is used. These vectors have a uniform distribution of magnitude (all lengths are equally likely), but cluster towards the origin. Use <code>Vector3D.[[#random|random]]()</code> if an even spacial distribution is desired.

'''See Also:''' <code>[[#random|random]]()</code>, <code>[[#randomDirection|randomDirection]]()</code>

[[Category:Oolite JavaScript Reference]]