Elite Wiki - User contributions [en]

Material Test Suite OXP

2014-01-04T23:06:14Z

Ahruman: Added link for test suite version 1.3.

The '''Material Test Suite''' is an expansion pack which tests Oolite’s [[Materials in Oolite|material model]] and built-in shaders. It was created during the testing phase before version 1.76 to test material functionality across different platforms and hardware. It may be useful in diagnosing some rendering problems.

To run the test suite:
* Download the test suite and install it. (Oolite test release 1.75 or later required. For information on installing expansion packs, see [[OXP#Installing an OXP"|the “OXP” article]].)
** For Oolite 1.75–1.77: [http://jens.ayton.se/oolite/files/material-test-suite-1.2.oxp.zip Material Test Suite 1.2]
** For Oolite test release 1.79 (January 2014) or later: [http://jens.ayton.se/oolite/files/material-test-suite-1.3.oxz Material Test Suite 1.3]
* Run Oolite, and decline when asked whether you want to load a game. (If you are using Strict Mode, disable it and restart Oolite.)
* You should now be presented with an information screen and the options “Run test suite” and “Cancel”. Select “Run test suite”.
* You will now be shown a series of spinning cubes. The precise number shown depends on your system’s capabilities. A successful test shows a grey box with a number on it (see [[#Sample Images|sample images]] below). A failed test will show something else, typically a solid black box.
* Please take a note of any failed tests, writing down the label shown on the left of the screen (such as “simple: 3”). If it is something other than a solid black or red box, please also take a screen shot (“'''*'''” key).
* While you’re at it, we’d appreciate if you tested dust rendering. When the test suite is complete, leave the station and fly away until you are no longer mass locked. Fly at normal speed and at hyperspeed (default: “'''J'''” key). Note whether you see dust particles flying past. Test this in every available shader mode (to change shader mode, pause, press “'''2'''” or “'''F2'''”, and select “Game Options…”).

If all the tests work and dust is nicely dusty, we’re done. You can throw out the Material Test Suite expansion pack and get back to playing the game. Otherwise, please report the problem:
* Quit Oolite and open the log file. (To locate the log file, see [[Oolite FAQ#Diagnosing Problems|the FAQ entry on diagnosing problems]].)
* Copy the lines between “<code>========== [Marker 1] ==========</code>” and “<code>========== [Marker 2] ==========</code>”. Paste them into an e-mail to [mailto:bugs@oolite.org bugs@oolite.org] or [http://www.aegidian.org/bb/viewtopic.php?t=8038 this forum thread] (or send the whole log as an attachment). Don’t forget to specify which tests failed!

If your tests passed, feel free to report anyway. Confirmation that we’re doing something right is good for our egos. But if they failed, we really need to know. We can’t fix problems we don’t know about.

== Sample Images ==
Click the images for a bigger view. Note that tests 8–16 will not be shown on systems without GLSL shader support.

[[File:Oolite Material Test Suite 1.png|160px|left|thumb]] Test 1: <code>diffuse_map</code> only. 

[[File:Oolite Material Test Suite 2.png|160px|left|thumb]] Test 2: <code>diffuse_map</code> and <code>emission_map</code>.

Note that the number '''2''' glows green in the dark. 

[[File:Oolite Material Test Suite 3.png|160px|left|thumb]] Test 3: <code>emission_map</code> only.

Note that the number '''3''' and the ring both glow green in the dark. 

[[File:Oolite Material Test Suite 4.png|160px|left|thumb]] Test 4: <code>diffuse_map</code> and <code>illumination_map</code>.

Note that number '''4''' is illuminated as though by a spotlight (with a slightly blue tint). 

[[File:Oolite Material Test Suite 5.png|160px|left|thumb]] Test 5: <code>illumination_map</code> only.

Note that the number '''5''' and the ring both glow with a dull blue tint. 

[[File:Oolite Material Test Suite 6.png|160px|left|thumb]] Test 6: <code>diffuse_map</code>, <code>emission_map</code> and <code>illumination_map</code>.

Note that the number '''6''' is illuminated as in test 4, and the ring glows with a slight green tint. 

[[File:Oolite Material Test Suite 7.png|160px|left|thumb]] Test 7: <code>diffuse_map</code> and <code>emission_and_illumination_map</code>.

When rendered correctly, the effects should be the same as in test 6. 

[[File:Oolite Material Test Suite 8.png|160px|left|thumb]] Test 8: <code>diffuse_map</code> and <code>normal_map</code>.

Note the shadows and highlights around the inside of the ring, which conform to the main light source, producing the effect of an indentation containing the number '''8'''. 

[[File:Oolite Material Test Suite 9.png|160px|left|thumb]] Test 9: <code>diffuse_map</code> and <code>normal_and_parallax_map</code>.

This should look similar to test 8, but with slightly better perspective. If you noticed a “creeping” effect in test 8, it should be alleviated in test 9. This is more noticeable if you look at the tests again. 

[[File:Oolite Material Test Suite 10.png|160px|left|thumb]] Test 10: <code>emission_map</code> and <code>normal_and_parallax_map</code>.

The number '''10''' and the ring glow as in test 3, and the interior of the ring is indented as in test 9. 

[[File:Oolite Material Test Suite 11.png|160px|left|thumb]] Test 11: <code>diffuse_map</code>, <code>emission_map</code> and <code>normal_and_parallax_map</code>.

The ring is white and the number '''11''' glows green, as in test 2, and the interior of the ring is indented. 

[[File:Oolite Material Test Suite 12.png|160px|left|thumb]] Test 12: <code>diffuse_map</code>, <code>emission_map</code>, <code>illumination_map</code> and <code>normal_and_parallax_map</code>.

The ring glows and the indented area around the number is illuminated as though by a spotlight, as in tests 6 and 7. 

[[File:Oolite Material Test Suite 13.png|160px|left|thumb]] Test 13: <code>diffuse_map</code> and <code>specular_map</code>.

Note that the number '''13''' is only visible as a variation in the glossiness of the surface, and completely invisible in shadow. 

[[File:Oolite Material Test Suite 14.png|160px|left|thumb]] Test 14: <code>specular_map</code> only.

Note that the number '''14''' and the ring are only visible as a variation in the glossiness of the surface, and the cube is uniformly grey in shadow. 

[[File:Oolite Material Test Suite 15.png|160px|left|thumb]] Test 15: <code>diffuse_map</code>, <code>emission_map</code> and <code>specular_map</code>.

A shiny surface as in tests 13 and 14, but width a glowing number '''15'''. 

[[File:Oolite Material Test Suite 16.png|160px|left|thumb]] Test 16: <code>diffuse_map</code>, <code>emission_map</code>, <code>illumination_map</code>, <code>normal_and_parallax_map</code> and <code>specular_map</code>.

Everything all at once: like test 12, but with the varying shininess from tests 13–15.

'''Bug:''' For unknown reasons, the shininess of test 16 does not match that of tests 13–15. 

[[Category:Oolite expansion packs]]

File:Oolite-oxp-icon.png

2013-11-02T13:53:25Z

Ahruman: uploaded a new version of "File:Oolite-oxp-icon.png": Updated to “new” icon from early 2011.

illustration for OXP_howto

Debug OXP

2013-10-01T07:35:47Z

Ahruman: Update for 1.77.1

'''Debug.oxp''' is a special OXP that enables JavaScript console support in Oolite (1.70 and later). It also adds a menu with various debug facilities under Mac OS X.

=== Downloads ===
[http://oolite.org/releases/debug-oxp-1.77.1.zip Debug OXP for Oolite 1.77.1]

== External JavaScript console support ==
On all platforms, installing Debug.oxp enables support for external console applications using the [[Oolite debug console TCP protocol]]. By default, it will attempt to connect to a console running on the same computer, but this can be changed by specifying a different <code>console-host</code> (and, optionally, <code>console-port</code>) in ''debugConfig.plist''. For external console support on the same computer under Mac OS X, <code>console-host</code> must be explicitly set to “127.0.0.1”; if this is not done, the [[#Integrated JavaScript console|integrated JavaScript console]] will be used instead. For information on using a console (integrated or external), see [[#Using the JavaScript console|Using the JavaScript console]] below.

'''Note:''' A cross-platform, python based, external console application is available in the [http://developer.berlios.de/project/showfiles.php?group_id=3577 Berlios Oolite files] area.

It contains a precompiled console for windows based computers, and the original python based console for Linux and Posix compliant computers.

On Debian or Ubuntu Linux you will need python 2.6.x installed and (at least) the packages <code>blt python-tk tk8.5</code> (or the equivalents in other distros.)

== Mac OS X-specific features ==
Under Mac OS X, the Debug OXP provides a menu with various debugging options and an integrated JavaScript console, as well as enabling external console support as on all platforms.

=== Debug menu (Mac OS X only) ===
[[Image:Oolite-debug-menu.png|494px]]

The Debug menu provides options to
* Show the Oolite run log in the standard Console application.
* Enable or disable various classes of log message at runtime (like editing ''logcontrol.plist'', without the need to restart Oolite).
* Enable various testing features, such as drawing of bounding boxes.
* Show the JavaScript console, and specify when it should be shown automatically. (This may not have any effect with external consoles, depending on the external console implementation.)
* Create a ship of any role near the main station (equivalent to the <code>:spawn</code> [[#Macros|macro]]).
Note: some of these features are implemented by sending JavaScript messages to the [[#The console script|console script]]. If the script has been modified, some features may not work properly.

The Log Message Classes submenu can be modified by editing ''debugLogMessageClassesMenu.plist'', found inside the OXP. This is merged from Config directories in the usual fashion.

=== Integrated JavaScript console (Mac OS X only) ===
[[Image:Oolite debug protocol example 1.png|594px]]

The integrated JavaScript console provides a window within Oolite which acts as a [[#Using the JavaScript console|JavaScript console]]. It can be shown using the Show JavaScript Console command in the Debug menu, unless external console mode has been enabled by setting <code>console-host</code> in ''debugConfig.plist''.

The integrated console has a 100-line memory. To see previous commands, press ⇞ (Page Up) or ⌥↑ (Option-Up Arrow). You can go the other way in the obvious manner.

== Using the JavaScript console ==
The JavaScript console, whether integrated or external, provides a powerful mechanism for interactively manipulating the game world. It can be used to issue simple commands, like <code>player.ship.awardEquipment("EQ_FUEL_INJECTION")</code>. It can be used to inspect properties of entities in the game world. And it can be used to develop scripts, by rewriting and testing methods of live ship scripts and world scripts.

=== Macros ===
Macros are a special type of command prefixed with a colon. Instead of being interpreted as a JavaScript command, a macro is looked up in a dictionary, and the result is used as the “real” command. For instance, if you enter the command <code>:listM</code> (short for “list macros”), the macro dictionary is queried for the string “listM”, and (by default) the code <code>for (let prop in macros) { ConsoleMessage('macro-list', ':' + prop) }</code> is found and executed. This code is called the ''expansion'' of the macro. The result is a list of macros being printed:
:clr
:clear
:spawn
:bgColor
:showM
:rmFgColor
::
:d
:ds
:listM
:setM
:delM
:fgColor
:rmBgColor
:resetM

As you can see in the example, To see the expansion of a macro without executing it, use <code>:showM</code>:
> :showM :delM
:delM = deleteMacro(PARAM)

When a macro with the word <code>PARAM</code> is executed, <code>PARAM</code> is replaced with any text following the macro name, surrounded in quotation marks. This is how <code>:showM</code> functions, for example; the string “:showM :delM” is expanded to “showMacro(":delM")”, causing the JavaScript function <code>showMacro()</code>, which is part of the [[#The console script|console script]], to be called. You can see the implementation of <code>showMacro()</code> by entering <code>showMacro</code> – without any parentheses – into the console.

An initial set of macros is loaded from ''debugConfig.plist''. If you edit any macros, using <code>:setM</code> or <code>:delM</code>, all macros are saved in Oolite’s preferences from that point forwards. This means that you don’t have to re-enter any macros you write with <code>:setM</code> after restarting Oolite.

The following example creates a simple :msg macro:
> :setM msg ConsoleMessage(' ',PARAM)
If you then type:
> :msg Hello World
The macro will be expanded, and you'll see “Hello World” on the console. However, macros are not functions, so you cannot use macros in the middle of javascript, or as part of another macro.

=== Console Properties ===

The console has several properties. They are accessible with "console.Foo":
debugFlags (r/w)
shaderMode (r/w)
maximumShaderMode (read only)
reducedDetailMode (r/w)
displayFPS (r/w)
platformDescription (read only)
pedanticMode (r/w)
ignoreDroppedPackets (r/w)

With <code>debugFlags</code> you can selective set/disable debugging options. Every debugging option is activated by setting a corresponding bit in the <code>debugFlags</code>:
Linked Lists = 0x00000001
Collisions = 0x00000004
Docking = 0x00000008
Octrees - Verbose Logging = 0x00000010
Bounding Boxes = 0x00000040
Octrees - Draw = 0x00000080
Normals = 0x00000100
Hide Dust = 0x00000200
disable Shader Fallback = 0x00000400
Extra Shader Validation = 0x00000800
Miscellaneous = 0x10000000

=== The console script ===
While an external or integrated console is required to provide a means of user interaction, most of the actual behaviour of the console is implemented in JavaScript, in a script called ''oolite-debug-console.js''. Input typed into the console is passed to the console script, which then generates output. The console script is also informed of log messages and JavaScript errors, and provides a global function, <code>ConsoleMessage(colorCode: String, message: String)</code>, to write messages to the console using its background colour support. Lastly, the console script implements the entire macro system.

This means that the console’s behaviour can be extensively customized, for instance, by replacing the macro system with something more powerful. There are two basic approaches to doing this:
* Creating a custom script (or a copy) with the same name, in an OXP which loads later than Debug.oxp (e.g., one which has a name which comes later in alphabetical order).
* Using a normal world script, and changing the console script object at startup.
The latter approach has the advantage that it can continue to work with future versions of the console script, and multiple patches can coexist. For example, a modification to supplement the macro system with a better one might look as follows:
this.name = "my-super-console-macros"

this.startUp = function()
{
// Ensure debug console is installed
if (!debugConsole) return

// Save original implementation of consolePerformJSCommand
// Note the prefix, used to ensure uniqueness. If several scripts patch
// the same method, it's important that they use different names.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand = debugConsole.consolePerformJSCommand

// Replace debugConsole.consolePerformJSCommand with custom function
debugConsole.consolePerformJSCommand = function(command)
{
// Note that in this function "this" will refer to debugconsole, not
// my-super-console-macros, since the function will be called as a
// method of debugConsole.

// Strip leading spaces, same code as original function.
while (command.charAt(0) == " ")
{
command = command.substring(1)
}

if (command.charAt(0) == "!")
{
// Super macro call detected.
// Insert super macro system here.
}
else
{
// Otherwise, call through to original method.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand(command)
}
}
}
This same patching technique, incidentally, can be used to modify scripts at runtime, either from the console or from other scripts.

{{misc-OXP}}
[[Category:Oolite utilities]]
[[Category:Oolite scripting]]

Oolite FAQ

2013-05-12T22:02:48Z

Ahruman: /* Diagnosing Problems */ Updated log-finding info for Mac OS X.

== Getting Started ==

{{FAQ|question=Where do I get the program? And what about the different versions that exist?|answer= The latest recommended release is 1.77-test, and the latest 'official' stable release is version 1.76.1, both available on the [http://oolite.org/download.shtml oolite.org download page] for OS X, Windows, and Linux(x86). The last stable release made by the original programmer, Giles Williams (a.k.a. Aegidian) was 1.65 and is best available from his website [http://oolite.aegidian.org/ oolite.aegidian.org]. The latest test releases/development versions can be [http://developer.berlios.de/project/showfiles.php?group_id=3577 downloaded from BerliOS] with installers also available for OS X, Windows and Linux. More detailed information can be found on the [http://aegidian.org/bb/index.php Oolite Bulletin Board], in the respective sections for [http://aegidian.org/bb/viewforum.php?f=10 Oolite-Mac], [http://aegidian.org/bb/viewforum.php?f=9 Oolite-Linux] and [http://aegidian.org/bb/viewforum.php?f=8 Oolite-PC].}}

{{FAQ|question=What's the point of the game?|answer=To fly from planet to planet, buying and selling goods, shooting pirates or committing acts of piracy. There's no goal other than perhaps to achieve the rank of ELITE.}}

{{FAQ|question=I'm still confused, how do I play?|answer=It's a good idea to start with the [http://svn.berlios.de/svnroot/repos/oolite-linux/tags/1.77/Doc/OoliteReadMe.pdf Oolite ReadMe] file for some basic information. For further information you may wish to consult the [http://wiki.alioth.net/index.php/Oolite_Instruction_Manual Oolite Instruction Manual] here on the wiki. A load of helpful information can be obtained from [http://wiki.alioth.net/index.php/Mr_Gimlet Mr Gimlet], the quite talkative dockmaster on Lave Station. If you're a fresh graduate from the Flight Academy on the way to your first ship, you should see him. It's also a good idea to have a look at Ian Bell's [http://www.iancgbell.clara.net/elite/manual.htm Flight Training Manual] for the original BBC Elite, although some of Oolite's control keys are different from the original, so be careful.}}

{{FAQ|question=How do I configure my joystick or gamepad for Oolite in Linux?|answer=See [[Linux Joysticks and Gamepads]].}}

== Gameplay ==

{{FAQ|question=What do the various colors represent on the radar?|answer=White - unpowered items that can't mass-lock the in-system drive (jumpdrive). Green/Yellow - navigation buoys. Yellow - powered craft. Red - powered craft identified as hostile. Green - space stations. Green/Red - thargoids. Purple - police. Blue/Red - police on intercept. Red/Yellow - active mine (about to detonate). Blue/Cyan - witchspace wormhole.}}

{{FAQ|question=I keep crashing when trying to dock. How do I dock manually?|answer=Many young Jamesons have met a sticky end and had to be scraped from the docking port of Lave Station whilst attempting docking. It's fairly easy once you get the hang of it. Check the [[How_to_Dock|How to Dock]] guide from the Galactic Navy Flight Manual. Or you can get the [[Traffic_Control_OXP|Traffic Control OXP]] for friendly instructions given by the station crew as you try to dock.}}

{{FAQ|question=How do I make decent profits?|answer=Trade between a Poor or Average Agricultural and a Rich or Average Industrial planet. Write down the prices for everything on both planets and find out where you make the most profit per ton. You can also download the [http://svn.berlios.de/svnroot/repos/oolite-linux/tags/1.77/Doc/OoliteRS.pdf Oolite Reference Sheet], which features a table with the average prices. From there you can figure out whether you're on a buyers' or a sellers' market. The [http://wiki.alioth.net/images/9/9e/OoliteTradingChart2.zip Trading Chart] allows you to create your own statistics along your way. [http://www.box.net/shared/bchkkloi32 This spreadsheet] highlights Poor Agricultural and Rich Industrial planets on a star chart (the spreadsheet is in .xls format and needs the Analysis Toolpak installed). You can also earn credits by taking cargo contracts - courier goods of varied type and volume between planets near and far. The spreadsheet helps assess whether you will be be able to complete the contract on time, and so build your reputation as an outstanding courier. Another option is to fit one or more [http://wiki.alioth.net/index.php/Passenger_Berth Passenger Berths] in your ship and earn credits by transporting individuals who, for one reason or another, prefer not to use the commercial Passenger Liners to reach their destination. As with cargo contracts, you can build your reputation up, which will result in your being offered more lucrative fares.}}

{{FAQ|question=It takes so long to get to the station after each jump. Can I do anything to speed the trip up?|answer=Well, space is huge. It is vast. I mean, have you ever imagined a football-field with an orange in one of the goals and a walnut in the other goal? If you haven't, then don't. It takes you nowhere. As will your ship's engine at normal speed. But then that's what your jumpdrive is for. Hit '''J''', and your journey speeds up. Unfortunately your jumpdrive doesn't work when other masses, like ships or planets, are nearby. They will 'lock' it. And in the 'corridor' between the witchpoint and the planet you are very likely to meet other ships. On the other hand there is no rule that you have to stick to the corridor. Just leave it sideways in any direction with your jumpdrive engaged for about 10-15 seconds, and head for the planet then. Makes your voyage much smoother. If you're a bounty-hunter and eager to meet lots of pirates, however, this is not your method of choice.}}

{{FAQ|question=I have already made my first intergalactic jump to Galaxy 2, but now I remember that I forgot my Zero-G cricket set/food blender/deadly lobstoid/edible arts graduate on Lave/Tionisla/Xeesle/Reesdice! Or I just found out that there are some more missions I'd like to do in the first galaxy. So how can I jump back to Galaxy 1?|answer=You can't. Unfortunately due to their very physical nature intergalactic wormholes allow for one-way travel only. Fortunately, though, the intergalactic wormhole in Galaxy 8 connects back to Galaxy 1. So you can go full circle. And you have to, if you want to return to the first galaxy. Of course that will cost you another 5000 credits for each galactic hyperjump. So the complete 8-Galaxies-Sightseeing-Tour has a pricetag of a total 40000 credits.}}

{{FAQ|question=I've got a trumble! First it was cute and fluffy. But then it started to multiply. Even worse, they started to eat everything on board and they are confusing my sights. I don't want them any more! How can I get rid of them? Help!|answer=First of all, don't feel embarrassed. It happens to all commanders sooner or later. I mean, they're really cute and fluffy, aren't they? But seriously, there are several things you could try. E.g. sell them to other unsuspecting noobs. If you don't find enough willing buyers, you could use your escape capsule and abandon your infested ship, hoping that they haven't yet made it into the escape pod, of course. I mean, you can always hope, can't you? If that all doesn't work for you, just remember the old Klingon saying: 'Revenge is a dish that is best served cold.' Now consider that for trumbles it's just the opposite. Want some BBQ-sauce?}}

{{FAQ|question=My keyboard doesn't have a particular key used by Oolite, or I even want to change the keyboard layout completely to my liking. What can I do to change the keys?|answer=Oolite reads a key configuration file called keyconfig.plist that you can find at /AddOns/Config/keyconfig.plist; that is the Config-folder that you find inside your AddOns-folder; which is where you put your OXPs. (PC-users have to create the folder /AddOns/Config/ first and then drop a copy of the keyconfig.plist found in /Oolite.app/Contents/Resources/Config/ to this folder.) You can open this file in any text editor and change the ASCII values of the keys used to suit your own preferences. Information on the default keys is also found in the [http://wiki.alioth.net/index.php/Oolite_Keyboard_Controls Oolite Keybord Controls-documentation] here on the wiki.}}

{{FAQ|question=I've completed a number of native and OXP missions and my [[Cobra_Mk.3_%28Oolite%29|Cobra Mk. III]] has a number of new and funky pieces of equipment. However, I'm planning a change of ship, what pieces of equipment will I lose as a result?|answer=Many missions award equipment as a result of either accepting or completing them. For the majority of ship equipment, trading ships will result in the equipment being sold as well, with a few exceptions. The '''Cloaking Device''' and the '''Mark Transponder Scanner''', available from the (native) Cloaking Device and (OXP) Assassins missions respectively are transferred to your new ship. The '''Naval Energy Unit''', although awarded with the completion of the (native) Thargoid Plans mission, will be sold when you trade ships. However, completing the mission allows you to buy these units from high TL systems.}}

{{FAQ|question=I’m using ECM-hardened missiles, but enemies are still able to destroy them! I never seem to be able to destroy enemy hardheads, though. What gives?|answer=ECM-hardened missiles are not ECM-proof. The probability of a hardened missile being destroyed by ECM is 10%–34% depending on range, and if it is destroyed, there’s a 50% chance that it will detonate. This applies equally to hardened missiles fired by computer-controlled ships and those fired by the player. The most effective use of hardened missiles is to use them against relatively slow targets at moderate range, and only use them on nimble ships if you desperately need to force them to break off an attack. Also, don’t use your ECM until a missile is close to blast range (250 metres).

Specifically, the ECM sends out four pulses with different ranges, at half-second intervals. Each pulse has a 10% chance of destroying each hardhead it encounters. For a missile fired at close range, that’s 1 - 0.94 = 34.39% chance of being destroyed within two seconds.}}

{{FAQ|question=If I believe that sizes and distances in Oolite are given in meters, it is so ''unrealistic''. The planets have a diameter of only 30–50 kilometers, and the suns are only 1000 kilometers away. Can't we get a little more realism in space, please?|answer=First of all, remember that Oolite is a ''game'', not a ''space simulation''. This is because it ''wants to'' be a game, not a sim. So yes, sizes and distances are all messed up. Ships and stations are too big, planets and suns are too small, and too close to each other. But this is ''deliberately'' so, and we are not going to change it.

The reason is simple: Realistic sizes and distances don't make a good game. In reality space is so huge that you never would meet anybody else on your journey. Imagine the dozen or so ships you meet in the 500 or so kilometers between witchpoint and planet spread over the realistic 150 '''million''' kilometers between Sun and Earth. Even if your direction is only one degree off the perfect line, you would miss them all. And how interesting would that be for the gameplay? And finally, if you had a realistically sized station in front of a realistically sized planet, how would you ever even notice it? A grain of sand in front of a, well, '''planet'''. The result would be players in complete loneliness and virtually no interaction with NPCs. An utterly, utterly boring game. Therefore it was the right decision to screw realism in the layout of the planetary systems in Elite and Oolite.}}

== Expanding the Game ==

{{FAQ|question=Speaking of OXPs, I've heard a lot about them. What are they? And where do I find them?|answer=OXP stands for 'Oolite eXpansion Pack'. As the name suggests, an OXP is an expansion to the game. It can contain virtually everything: new graphics for your ship, new ships for the player and/or the NPCs, new stations, new missions, new fun. To install an OXP you simply have to drag it into your AddOns-folder (only the OXP itself, not the folder it probably comes in). And as for finding them, you're already at the right place. All OXPs are now (or will become) accessible through the [[OXP|OXP-page of the wiki]]. Just follow the link. And if you fancy trying to create an OXP, the modifying Oolite FAQ can be found [[Modifying Oolite Informal FAQ|here]].}}

{{FAQ|question=Are there any OXPs that are highly recommended? Or can I get a list of 'must-have' OXPs?|answer=This is a difficult one to answer, because it depends so much on personal taste. There is no list of 'must-have' or necessary OXPs that could be agreed upon by all—or even most—players or contributers. But if you have a look at the [http://aegidian.org/bb/index.php Oolite Bulletin Board], especially the [http://aegidian.org/bb/viewforum.php?f=2 Discussion]- and the [http://aegidian.org/bb/viewforum.php?f=4 Expansion Pack]-forums, you will surely find some topics about this question, and the personal answers of a couple of board members.}}

== Why does this and that not exist? ==

{{FAQ|question=Will there ever be an Oolite Massive Multi-player Online Role-Play Game (MMORPG)?|answer=At present Ahruman and Co. (the developers) have no plans to develop either Oolite or a separate branch to accommodate either an MMORPG or an MOG (Multi-player Online Game). This, however, doesn't mean one of you clever bods out there can't try ;-) We suggest you read [http://aegidian.org/bb/viewtopic.php?t=6173 this Bulletin Board thread] before you commence though, it may save you a lot of hair-tearing!}}

{{FAQ|question=Can the range of hyperspace jumps/my fuel capacity be increased?|answer=No. Jump range in Oolite is hard-coded for a reason. The game would become less challenging and thus less fun. (Although I can imagine hacks that give unlimited fuel.) And don't forget that there are already various ways of refuelling while you are in flight.}}

{{FAQ|question=I want Laser Cooling Boosters!|answer=There are none at the moment and the reason is simple. It would unbalance the game too much. If they were available for the player only, things would get too easy. And if the NPCs could get them, too, things would get too hard. It's all about maintaining a reasonable balance. So the ultimate advice on this is: aim carefully; don't waste your laser fire; prevent overheating.}}

{{FAQ|question=The other day I got killed when I launched from a Rock Hermit/Behemoth/whatever, and all the profits/kills that I made before were gone. Why couldn't I save there? Why only on main stations?|answer=First of all, congratulations to you for having internalized the ''Golden Rule'': save early, save often! Unfortunately in Oolite you can save and load a commander only on main stations. That's because they are the only 'fixed' objects in space. The rest of the system is populated anew each time you load a game and is not saved in your savefile. So chances are that the Rock Hermit or Behemoth you docked with when saving simply wouldn't exist when you load again, and you would find yourself in nirvana instead of in a safe haven. To prevent odd behavior like this saving and loading is prohibited anywhere other than in a main station. Alternatively you could install [http://wiki.alioth.net/index.php/Save_Anywhere Save Anywhere.oxp], which does exactly what it says on the tin. Note, however, that it is still in beta state so read the documentation first.}}

{{FAQ|question=I would like to switch between different ships of mine, e.g. have a nice racer for the weekends, meanwhile leave my freighter docked somewhere and take it back on Monday. Why can't I do this?|answer=It is possible for OXPs to provide this facility in 1.77 or later versions. Check the [[OXP_List|OXP List]] or ask on the forum to find one that suits you.}}

== Known Issues / Bugs ==

{{FAQ|question=I am running Oolite on Windows Vista/7 and have installed the game in C:\Program Files\Oolite. I cannot find my saved games, log files, game preferences .GNUstepDefaults file and/or any saved screenshots, although I can see the saved games in the game and use them normally. Where are my files?|answer=You are experiencing file virtualization under Windows. Any application installed in %programfiles%, %systemroot%, %systemdrive% or %programdata that writes files under its folder structure is subject to this. As per Microsoft Support's article KB927387, the resolution for finding your files again is using one of the following methods:
•Click the Compatibility Files button that appears on the Explorer bar to view virtualized files in the folder. The Compatibility Files button appears only if there are virtualized files in the folder.

•Look in the C:\Users\User_name\AppData\Local\VirtualStore folder to locate files and folders.

•Save your application's data in a folder under your user profile.}}

== System Requirements ==

{{FAQ|question=Does it work on Mac OS X 10.2 (Jaguar) & 10.3 (Panther)?|answer=Sadly, no. The minimum OS requirement for Oolite on the Mac is now Mac OS X 10.4. The previous stable version (1.65) is however compatible with Mac OS X 10.3.9}}

{{FAQ|question=Does it work on both Intel and PPC Macs?|answer=Yes, since 1.65 Oolite has been Universal Binary. It was PPC only in previous versions.}}

{{FAQ|question=What's the latest version?|answer=The last stable release is 1.76.1, and the latest test release (recommended) is 1.77. The last stable and latest test versions can be downloaded from [http://oolite.org/download.shtml Oolite's homepage]. More information can be found through the [http://aegidian.org/bb/viewforum.php?f=10 Oolite forums].}}

{{FAQ|question=Is there a port for the PC or Linux?|answer=Yes. Both ports are stable and are at the same level of development as Oolite for the Mac. You can download Oolite for Windows and for Linux PCs from [http://oolite.org/download.shtml Oolite's homepage] (click on "show all platforms" if you can't see the version you're looking for). Information on test releases can be found through the Oolite forums, for the [http://aegidian.org/bb/viewforum.php?f=9 Linux version], and for the [http://aegidian.org/bb/viewforum.php?f=8 Windows version].}}

== Writing OXPs ==

{{FAQ|question=I would like to contribute to Oolite and write my own OXP, but unfortunately my knowledge in scripting/programming is limited. How can I get started?|answer=First of all the Oolite community welcomes all efforts to enhance and enrich their favorite game, so be our guest! Many of us have started with very little knowledge, but over time were able to write and release astonishing OXPs, so why shouldn't you? Anyway, scripting can be learned. Currently there are two scripting languages in use for Oolite, plist-scripting (sometimes referred to as legacy-scripting) and JavaScript. For any serious OXP-plans you will have to learn them. A general starting point is the [http://wiki.alioth.net/index.php/OXP_howto OXP howto]-page, which will link you to further documentation. For plist-scripting you should read the [http://wiki.alioth.net/index.php/OXP_howto_plist OXP howto plist]-page, and also the [http://wiki.alioth.net/index.php/Property_list Property list]-intro. Information on the ongoing implementation of scripting with JavaScript can be found in the [http://wiki.alioth.net/index.php/Category:Oolite_scripting Category page for scripting] (work in progress). If you want to design a new ship, you should have a look at the [http://wiki.alioth.net/index.php/OXP_howto_model OXP howto model]-page and the [http://wiki.alioth.net/index.php/OXP_howto_texture OXP howto texture]-page. And if you want to give it a behavior of its own, you should consult the [http://wiki.alioth.net/index.php/OXP_howto_AI OXP howto AI]-page. I suggest you try to read and understand these first. If you still have questions afterwards, there is always the [http://aegidian.org/bb/index.php Oolite Bulletin Board], where lots of friendly people usually are very willing to lend a helping hand and to answer lots of questions.}}

{{FAQ|question=I want to write an OXP or add content to the Wiki, but some (or all) of the content was written by another author. What copyright issues do I face?|answer=Anything submitted to the Wiki is on the basis that anyone else may edit or fiddle with it. OXPs are submitted under the creative commons licence. The author (strictly speaking) owns the copyright, but licenses users to use or distribute the OXP as long as they don't sell or charge for it. In practice virtually all OXP authors don't assert copyright and are pleased and flattered that somebody thinks their stuff is worth writing about or pinching to use in another OXP (it is good manners to credit the original author in the readme though). I expect the author will be pleased if you want to add some background, but if you are in doubt, send him or her a PM asking him for permission. At the end of the day, Oolite is a fun project and everybody is doing stuff for it on that basis. (nicked wholesale from [http://aegidian.org/bb/viewtopic.php?p=44813#44813 Little_Bear's] post on the [http://aegidian.org/bb/index.php Oolite Bulletin Board])}}

== Diagnosing Problems ==

{{FAQ|question=Someone asked me for my log file. What is that, and where is it?|answer=While Oolite runs, various diagnostic information is written to a file called Latest.log. Where it is depends on your operating system:
* '''Mac OS X''': Restart Oolite, and select “Show Previous Log” from the “'''Oolite'''” menu in the menu bar. Alternatively, in the Finder, select “Go to Folder…” from the Go menu, and enter “~/Library/Logs/Oolite/”, and find Latest.log.
* '''Windows''': in Oolite’s folder (typically in C:\''Oolite''), there is a folder called ''oolite.app'', which contains a folder called ''Logs''. A shortcut to this folder is created at Oolite's Start Menu entries during installation. If you have installed the game in a folder subject to file virtualization like C:\Program Files\Oolite and encounter difficulty in locating the log files, then please refer to the Known Issues section of this FAQ for information on how to access them.
* '''Linux and other Unix-like systems''': ~/.Oolite/Logs (that is, in the hidden folder ''.Oolite'' in your home folder). If you’re using Nautilus or Konqueror—if you’ve never heard of them, you probably are—select Show Hidden Files from the View menu.}}

{{FAQ|question=Why do none of the OXPs I have installed appear to work in the game?|answer=Check you do not have Oolite in 'Strict Play' mode. When docked or paused press F2 and if it says 'Reset to Unrestricted Play' then OXPs will not work. It needs to say 'Reset to Strict Play'. Alternately perhaps you downloaded and extracted an OXP straight to the "add ons" file. Without then checking that the file ending ".oxp" is moved up from any subdirectory folders to the "add ons" folder itself, as Oolite simply ignores folders etc not ending in .OXP in "add ons"}}

== Other Questions ==

{{FAQ|question=I have a question not answered here, where can I get help?|answer=Post your queries onto [http://aegidian.org/bb/index.php the friendliest board this side of Riedquat™]. Satisfaction is not guaranteed, but then what is, in this mixed-up universe? Help keep the board friendly by making sure your question isn't already answered here!

If you want to report a bug, please read [http://aegidian.org/bb/viewtopic.php?t=3778 this]. Yes, all that work is a drag, but if nobody reports the bug it probably won’t get fixed.

Or join us in #oolite, or #oolite-dev if you're working on Oolite or OXPs, on irc.oftc.net or ipv6.oftc.net.}}

[[Category:Oolite]]

Debug OXP

2013-05-12T12:33:49Z

Ahruman: Undo revision 36794 by Ahruman (talk)

'''Debug.oxp''' is a special OXP that enables JavaScript console support in Oolite (1.70 and later). It also adds a menu with various debug facilities under Mac OS X.

=== Downloads ===
[http://jens.ayton.se/oolite/files/debug-oxp-1.76.zip Debug OXP for Oolite 1.76]

== External JavaScript console support ==
On all platforms, installing Debug.oxp enables support for external console applications using the [[Oolite debug console TCP protocol]]. By default, it will attempt to connect to a console running on the same computer, but this can be changed by specifying a different <code>console-host</code> (and, optionally, <code>console-port</code>) in ''debugConfig.plist''. For external console support on the same computer under Mac OS X, <code>console-host</code> must be explicitly set to “127.0.0.1”; if this is not done, the [[#Integrated JavaScript console|integrated JavaScript console]] will be used instead. For information on using a console (integrated or external), see [[#Using the JavaScript console|Using the JavaScript console]] below.

'''Note:''' A cross-platform, python based, external console application is available in the [http://developer.berlios.de/project/showfiles.php?group_id=3577 Berlios Oolite files] area.

It contains a precompiled console for windows based computers, and the original python based console for Linux and Posix compliant computers.

On Debian or Ubuntu Linux you will need python 2.6.x installed and (at least) the packages <code>blt python-tk tk8.5</code> (or the equivalents in other distros.)

== Mac OS X-specific features ==
Under Mac OS X, the Debug OXP provides a menu with various debugging options and an integrated JavaScript console, as well as enabling external console support as on all platforms.

=== Debug menu (Mac OS X only) ===
[[Image:Oolite-debug-menu.png|494px]]

The Debug menu provides options to
* Show the Oolite run log in the standard Console application.
* Enable or disable various classes of log message at runtime (like editing ''logcontrol.plist'', without the need to restart Oolite).
* Enable various testing features, such as drawing of bounding boxes.
* Show the JavaScript console, and specify when it should be shown automatically. (This may not have any effect with external consoles, depending on the external console implementation.)
* Create a ship of any role near the main station (equivalent to the <code>:spawn</code> [[#Macros|macro]]).
Note: some of these features are implemented by sending JavaScript messages to the [[#The console script|console script]]. If the script has been modified, some features may not work properly.

The Log Message Classes submenu can be modified by editing ''debugLogMessageClassesMenu.plist'', found inside the OXP. This is merged from Config directories in the usual fashion.

=== Integrated JavaScript console (Mac OS X only) ===
[[Image:Oolite debug protocol example 1.png|594px]]

The integrated JavaScript console provides a window within Oolite which acts as a [[#Using the JavaScript console|JavaScript console]]. It can be shown using the Show JavaScript Console command in the Debug menu, unless external console mode has been enabled by setting <code>console-host</code> in ''debugConfig.plist''.

The integrated console has a 100-line memory. To see previous commands, press ⇞ (Page Up) or ⌥↑ (Option-Up Arrow). You can go the other way in the obvious manner.

== Using the JavaScript console ==
The JavaScript console, whether integrated or external, provides a powerful mechanism for interactively manipulating the game world. It can be used to issue simple commands, like <code>player.ship.awardEquipment("EQ_FUEL_INJECTION")</code>. It can be used to inspect properties of entities in the game world. And it can be used to develop scripts, by rewriting and testing methods of live ship scripts and world scripts.

=== Macros ===
Macros are a special type of command prefixed with a colon. Instead of being interpreted as a JavaScript command, a macro is looked up in a dictionary, and the result is used as the “real” command. For instance, if you enter the command <code>:listM</code> (short for “list macros”), the macro dictionary is queried for the string “listM”, and (by default) the code <code>for (let prop in macros) { ConsoleMessage('macro-list', ':' + prop) }</code> is found and executed. This code is called the ''expansion'' of the macro. The result is a list of macros being printed:
:clr
:clear
:spawn
:bgColor
:showM
:rmFgColor
::
:d
:ds
:listM
:setM
:delM
:fgColor
:rmBgColor
:resetM

As you can see in the example, To see the expansion of a macro without executing it, use <code>:showM</code>:
> :showM :delM
:delM = deleteMacro(PARAM)

When a macro with the word <code>PARAM</code> is executed, <code>PARAM</code> is replaced with any text following the macro name, surrounded in quotation marks. This is how <code>:showM</code> functions, for example; the string “:showM :delM” is expanded to “showMacro(":delM")”, causing the JavaScript function <code>showMacro()</code>, which is part of the [[#The console script|console script]], to be called. You can see the implementation of <code>showMacro()</code> by entering <code>showMacro</code> – without any parentheses – into the console.

An initial set of macros is loaded from ''debugConfig.plist''. If you edit any macros, using <code>:setM</code> or <code>:delM</code>, all macros are saved in Oolite’s preferences from that point forwards. This means that you don’t have to re-enter any macros you write with <code>:setM</code> after restarting Oolite.

The following example creates a simple :msg macro:
> :setM msg ConsoleMessage(' ',PARAM)
If you then type:
> :msg Hello World
The macro will be expanded, and you'll see “Hello World” on the console. However, macros are not functions, so you cannot use macros in the middle of javascript, or as part of another macro.

=== Console Properties ===

The console has several properties. They are accessible with "console.Foo":
debugFlags (r/w)
shaderMode (r/w)
maximumShaderMode (read only)
reducedDetailMode (r/w)
displayFPS (r/w)
platformDescription (read only)
pedanticMode (r/w)
ignoreDroppedPackets (r/w)

With <code>debugFlags</code> you can selective set/disable debugging options. Every debugging option is activated by setting a corresponding bit in the <code>debugFlags</code>:
Linked Lists = 0x00000001
Collisions = 0x00000004
Docking = 0x00000008
Octrees - Verbose Logging = 0x00000010
Bounding Boxes = 0x00000040
Octrees - Draw = 0x00000080
Normals = 0x00000100
Hide Dust = 0x00000200
disable Shader Fallback = 0x00000400
Extra Shader Validation = 0x00000800
Miscellaneous = 0x10000000

=== The console script ===
While an external or integrated console is required to provide a means of user interaction, most of the actual behaviour of the console is implemented in JavaScript, in a script called ''oolite-debug-console.js''. Input typed into the console is passed to the console script, which then generates output. The console script is also informed of log messages and JavaScript errors, and provides a global function, <code>ConsoleMessage(colorCode: String, message: String)</code>, to write messages to the console using its background colour support. Lastly, the console script implements the entire macro system.

This means that the console’s behaviour can be extensively customized, for instance, by replacing the macro system with something more powerful. There are two basic approaches to doing this:
* Creating a custom script (or a copy) with the same name, in an OXP which loads later than Debug.oxp (e.g., one which has a name which comes later in alphabetical order).
* Using a normal world script, and changing the console script object at startup.
The latter approach has the advantage that it can continue to work with future versions of the console script, and multiple patches can coexist. For example, a modification to supplement the macro system with a better one might look as follows:
this.name = "my-super-console-macros"

this.startUp = function()
{
// Ensure debug console is installed
if (!debugConsole) return

// Save original implementation of consolePerformJSCommand
// Note the prefix, used to ensure uniqueness. If several scripts patch
// the same method, it's important that they use different names.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand = debugConsole.consolePerformJSCommand

// Replace debugConsole.consolePerformJSCommand with custom function
debugConsole.consolePerformJSCommand = function(command)
{
// Note that in this function "this" will refer to debugconsole, not
// my-super-console-macros, since the function will be called as a
// method of debugConsole.

// Strip leading spaces, same code as original function.
while (command.charAt(0) == " ")
{
command = command.substring(1)
}

if (command.charAt(0) == "!")
{
// Super macro call detected.
// Insert super macro system here.
}
else
{
// Otherwise, call through to original method.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand(command)
}
}
}
This same patching technique, incidentally, can be used to modify scripts at runtime, either from the console or from other scripts.

{{misc-OXP}}
[[Category:Oolite utilities]]
[[Category:Oolite scripting]]

Debug OXP

2013-05-12T12:33:21Z

Ahruman: /* External JavaScript console support */

'''Debug.oxp''' is a special OXP that enables JavaScript console support in Oolite (1.70 and later). It also adds a menu with various debug facilities under Mac OS X.

=== Downloads ===
[http://jens.ayton.se/oolite/files/debug-oxp-1.76.zip Debug OXP for Oolite 1.76]

== External JavaScript console support ==
On all platforms, installing Debug.oxp enables support for external console applications using the [[Oolite debug console TCP protocol]]. By default, it will attempt to connect to a console running on the same computer, but this can be changed by specifying a different <code>console-host</code> (and, optionally, <code>console-port</code>) in ''debugConfig.plist''. For external console support on the same computer under Mac OS X, <code>console-host</code> must be explicitly set to “127.0.0.1”; if this is not done, the [[#Integrated JavaScript console|integrated JavaScript console]] will be used instead. For information on using a console (integrated or external), see [[#Using the JavaScript console|Using the JavaScript console]] below.

'''Note:''' A cross-platform, python based, external console application is available from [https://github.com/OoliteProject/oolite-debug-console the Oolite project on GitHub] (click the ZIP button to download the latest version).

It contains a precompiled console for windows based computers, and the original python based console for Linux and Posix compliant computers.

On Debian or Ubuntu Linux you will need python 2.6.x installed and (at least) the packages <code>blt python-tk tk8.5</code> (or the equivalents in other distros.)

== Mac OS X-specific features ==
Under Mac OS X, the Debug OXP provides a menu with various debugging options and an integrated JavaScript console, as well as enabling external console support as on all platforms.

=== Debug menu (Mac OS X only) ===
[[Image:Oolite-debug-menu.png|494px]]

The Debug menu provides options to
* Show the Oolite run log in the standard Console application.
* Enable or disable various classes of log message at runtime (like editing ''logcontrol.plist'', without the need to restart Oolite).
* Enable various testing features, such as drawing of bounding boxes.
* Show the JavaScript console, and specify when it should be shown automatically. (This may not have any effect with external consoles, depending on the external console implementation.)
* Create a ship of any role near the main station (equivalent to the <code>:spawn</code> [[#Macros|macro]]).
Note: some of these features are implemented by sending JavaScript messages to the [[#The console script|console script]]. If the script has been modified, some features may not work properly.

The Log Message Classes submenu can be modified by editing ''debugLogMessageClassesMenu.plist'', found inside the OXP. This is merged from Config directories in the usual fashion.

=== Integrated JavaScript console (Mac OS X only) ===
[[Image:Oolite debug protocol example 1.png|594px]]

The integrated JavaScript console provides a window within Oolite which acts as a [[#Using the JavaScript console|JavaScript console]]. It can be shown using the Show JavaScript Console command in the Debug menu, unless external console mode has been enabled by setting <code>console-host</code> in ''debugConfig.plist''.

The integrated console has a 100-line memory. To see previous commands, press ⇞ (Page Up) or ⌥↑ (Option-Up Arrow). You can go the other way in the obvious manner.

== Using the JavaScript console ==
The JavaScript console, whether integrated or external, provides a powerful mechanism for interactively manipulating the game world. It can be used to issue simple commands, like <code>player.ship.awardEquipment("EQ_FUEL_INJECTION")</code>. It can be used to inspect properties of entities in the game world. And it can be used to develop scripts, by rewriting and testing methods of live ship scripts and world scripts.

=== Macros ===
Macros are a special type of command prefixed with a colon. Instead of being interpreted as a JavaScript command, a macro is looked up in a dictionary, and the result is used as the “real” command. For instance, if you enter the command <code>:listM</code> (short for “list macros”), the macro dictionary is queried for the string “listM”, and (by default) the code <code>for (let prop in macros) { ConsoleMessage('macro-list', ':' + prop) }</code> is found and executed. This code is called the ''expansion'' of the macro. The result is a list of macros being printed:
:clr
:clear
:spawn
:bgColor
:showM
:rmFgColor
::
:d
:ds
:listM
:setM
:delM
:fgColor
:rmBgColor
:resetM

As you can see in the example, To see the expansion of a macro without executing it, use <code>:showM</code>:
> :showM :delM
:delM = deleteMacro(PARAM)

When a macro with the word <code>PARAM</code> is executed, <code>PARAM</code> is replaced with any text following the macro name, surrounded in quotation marks. This is how <code>:showM</code> functions, for example; the string “:showM :delM” is expanded to “showMacro(":delM")”, causing the JavaScript function <code>showMacro()</code>, which is part of the [[#The console script|console script]], to be called. You can see the implementation of <code>showMacro()</code> by entering <code>showMacro</code> – without any parentheses – into the console.

An initial set of macros is loaded from ''debugConfig.plist''. If you edit any macros, using <code>:setM</code> or <code>:delM</code>, all macros are saved in Oolite’s preferences from that point forwards. This means that you don’t have to re-enter any macros you write with <code>:setM</code> after restarting Oolite.

The following example creates a simple :msg macro:
> :setM msg ConsoleMessage(' ',PARAM)
If you then type:
> :msg Hello World
The macro will be expanded, and you'll see “Hello World” on the console. However, macros are not functions, so you cannot use macros in the middle of javascript, or as part of another macro.

=== Console Properties ===

The console has several properties. They are accessible with "console.Foo":
debugFlags (r/w)
shaderMode (r/w)
maximumShaderMode (read only)
reducedDetailMode (r/w)
displayFPS (r/w)
platformDescription (read only)
pedanticMode (r/w)
ignoreDroppedPackets (r/w)

With <code>debugFlags</code> you can selective set/disable debugging options. Every debugging option is activated by setting a corresponding bit in the <code>debugFlags</code>:
Linked Lists = 0x00000001
Collisions = 0x00000004
Docking = 0x00000008
Octrees - Verbose Logging = 0x00000010
Bounding Boxes = 0x00000040
Octrees - Draw = 0x00000080
Normals = 0x00000100
Hide Dust = 0x00000200
disable Shader Fallback = 0x00000400
Extra Shader Validation = 0x00000800
Miscellaneous = 0x10000000

=== The console script ===
While an external or integrated console is required to provide a means of user interaction, most of the actual behaviour of the console is implemented in JavaScript, in a script called ''oolite-debug-console.js''. Input typed into the console is passed to the console script, which then generates output. The console script is also informed of log messages and JavaScript errors, and provides a global function, <code>ConsoleMessage(colorCode: String, message: String)</code>, to write messages to the console using its background colour support. Lastly, the console script implements the entire macro system.

This means that the console’s behaviour can be extensively customized, for instance, by replacing the macro system with something more powerful. There are two basic approaches to doing this:
* Creating a custom script (or a copy) with the same name, in an OXP which loads later than Debug.oxp (e.g., one which has a name which comes later in alphabetical order).
* Using a normal world script, and changing the console script object at startup.
The latter approach has the advantage that it can continue to work with future versions of the console script, and multiple patches can coexist. For example, a modification to supplement the macro system with a better one might look as follows:
this.name = "my-super-console-macros"

this.startUp = function()
{
// Ensure debug console is installed
if (!debugConsole) return

// Save original implementation of consolePerformJSCommand
// Note the prefix, used to ensure uniqueness. If several scripts patch
// the same method, it's important that they use different names.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand = debugConsole.consolePerformJSCommand

// Replace debugConsole.consolePerformJSCommand with custom function
debugConsole.consolePerformJSCommand = function(command)
{
// Note that in this function "this" will refer to debugconsole, not
// my-super-console-macros, since the function will be called as a
// method of debugConsole.

// Strip leading spaces, same code as original function.
while (command.charAt(0) == " ")
{
command = command.substring(1)
}

if (command.charAt(0) == "!")
{
// Super macro call detected.
// Insert super macro system here.
}
else
{
// Otherwise, call through to original method.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand(command)
}
}
}
This same patching technique, incidentally, can be used to modify scripts at runtime, either from the console or from other scripts.

{{misc-OXP}}
[[Category:Oolite utilities]]
[[Category:Oolite scripting]]

Oolite FAQ

2013-05-04T20:24:12Z

Ahruman: /* Diagnosing Problems */ Log files aren’t just in test releases any more.

== Getting Started ==

{{FAQ|question=Where do I get the program? And what about the different versions that exist?|answer= The latest recommended release is 1.77-test, and the latest 'official' stable release is version 1.76.1, both available on the [http://oolite.org/download.shtml oolite.org download page] for OS X, Windows, and Linux(x86). The last stable release made by the original programmer, Giles Williams (a.k.a. Aegidian) was 1.65 and is best available from his website [http://oolite.aegidian.org/ oolite.aegidian.org]. The latest test releases/development versions can be [http://developer.berlios.de/project/showfiles.php?group_id=3577 downloaded from BerliOS] with installers also available for OS X, Windows and Linux. More detailed information can be found on the [http://aegidian.org/bb/index.php Oolite Bulletin Board], in the respective sections for [http://aegidian.org/bb/viewforum.php?f=10 Oolite-Mac], [http://aegidian.org/bb/viewforum.php?f=9 Oolite-Linux] and [http://aegidian.org/bb/viewforum.php?f=8 Oolite-PC].}}

{{FAQ|question=What's the point of the game?|answer=To fly from planet to planet, buying and selling goods, shooting pirates or committing acts of piracy. There's no goal other than perhaps to achieve the rank of ELITE.}}

{{FAQ|question=I'm still confused, how do I play?|answer=It's a good idea to start with the [http://svn.berlios.de/svnroot/repos/oolite-linux/tags/1.77/Doc/OoliteReadMe.pdf Oolite ReadMe] file for some basic information. For further information you may wish to consult the [http://wiki.alioth.net/index.php/Oolite_Instruction_Manual Oolite Instruction Manual] here on the wiki. A load of helpful information can be obtained from [http://wiki.alioth.net/index.php/Mr_Gimlet Mr Gimlet], the quite talkative dockmaster on Lave Station. If you're a fresh graduate from the Flight Academy on the way to your first ship, you should see him. It's also a good idea to have a look at Ian Bell's [http://www.iancgbell.clara.net/elite/manual.htm Flight Training Manual] for the original BBC Elite, although some of Oolite's control keys are different from the original, so be careful.}}

{{FAQ|question=How do I configure my joystick or gamepad for Oolite in Linux?|answer=See [[Linux Joysticks and Gamepads]].}}

== Gameplay ==

{{FAQ|question=What do the various colors represent on the radar?|answer=White - unpowered items that can't mass-lock the in-system drive (jumpdrive). Green/Yellow - navigation buoys. Yellow - powered craft. Red - powered craft identified as hostile. Green - space stations. Green/Red - thargoids. Purple - police. Blue/Red - police on intercept. Red/Yellow - active mine (about to detonate). Blue/Cyan - witchspace wormhole.}}

{{FAQ|question=I keep crashing when trying to dock. How do I dock manually?|answer=Many young Jamesons have met a sticky end and had to be scraped from the docking port of Lave Station whilst attempting docking. It's fairly easy once you get the hang of it. Check the [[How_to_Dock|How to Dock]] guide from the Galactic Navy Flight Manual. Or you can get the [[Traffic_Control_OXP|Traffic Control OXP]] for friendly instructions given by the station crew as you try to dock.}}

{{FAQ|question=How do I make decent profits?|answer=Trade between a Poor or Average Agricultural and a Rich or Average Industrial planet. Write down the prices for everything on both planets and find out where you make the most profit per ton. You can also download the [http://svn.berlios.de/svnroot/repos/oolite-linux/tags/1.77/Doc/OoliteRS.pdf Oolite Reference Sheet], which features a table with the average prices. From there you can figure out whether you're on a buyers' or a sellers' market. The [http://wiki.alioth.net/images/9/9e/OoliteTradingChart2.zip Trading Chart] allows you to create your own statistics along your way. [http://www.box.net/shared/bchkkloi32 This spreadsheet] highlights Poor Agricultural and Rich Industrial planets on a star chart (the spreadsheet is in .xls format and needs the Analysis Toolpak installed). You can also earn credits by taking cargo contracts - courier goods of varied type and volume between planets near and far. The spreadsheet helps assess whether you will be be able to complete the contract on time, and so build your reputation as an outstanding courier. Another option is to fit one or more [http://wiki.alioth.net/index.php/Passenger_Berth Passenger Berths] in your ship and earn credits by transporting individuals who, for one reason or another, prefer not to use the commercial Passenger Liners to reach their destination. As with cargo contracts, you can build your reputation up, which will result in your being offered more lucrative fares.}}

{{FAQ|question=It takes so long to get to the station after each jump. Can I do anything to speed the trip up?|answer=Well, space is huge. It is vast. I mean, have you ever imagined a football-field with an orange in one of the goals and a walnut in the other goal? If you haven't, then don't. It takes you nowhere. As will your ship's engine at normal speed. But then that's what your jumpdrive is for. Hit '''J''', and your journey speeds up. Unfortunately your jumpdrive doesn't work when other masses, like ships or planets, are nearby. They will 'lock' it. And in the 'corridor' between the witchpoint and the planet you are very likely to meet other ships. On the other hand there is no rule that you have to stick to the corridor. Just leave it sideways in any direction with your jumpdrive engaged for about 10-15 seconds, and head for the planet then. Makes your voyage much smoother. If you're a bounty-hunter and eager to meet lots of pirates, however, this is not your method of choice.}}

{{FAQ|question=I have already made my first intergalactic jump to Galaxy 2, but now I remember that I forgot my Zero-G cricket set/food blender/deadly lobstoid/edible arts graduate on Lave/Tionisla/Xeesle/Reesdice! Or I just found out that there are some more missions I'd like to do in the first galaxy. So how can I jump back to Galaxy 1?|answer=You can't. Unfortunately due to their very physical nature intergalactic wormholes allow for one-way travel only. Fortunately, though, the intergalactic wormhole in Galaxy 8 connects back to Galaxy 1. So you can go full circle. And you have to, if you want to return to the first galaxy. Of course that will cost you another 5000 credits for each galactic hyperjump. So the complete 8-Galaxies-Sightseeing-Tour has a pricetag of a total 40000 credits.}}

{{FAQ|question=I've got a trumble! First it was cute and fluffy. But then it started to multiply. Even worse, they started to eat everything on board and they are confusing my sights. I don't want them any more! How can I get rid of them? Help!|answer=First of all, don't feel embarrassed. It happens to all commanders sooner or later. I mean, they're really cute and fluffy, aren't they? But seriously, there are several things you could try. E.g. sell them to other unsuspecting noobs. If you don't find enough willing buyers, you could use your escape capsule and abandon your infested ship, hoping that they haven't yet made it into the escape pod, of course. I mean, you can always hope, can't you? If that all doesn't work for you, just remember the old Klingon saying: 'Revenge is a dish that is best served cold.' Now consider that for trumbles it's just the opposite. Want some BBQ-sauce?}}

{{FAQ|question=My keyboard doesn't have a particular key used by Oolite, or I even want to change the keyboard layout completely to my liking. What can I do to change the keys?|answer=Oolite reads a key configuration file called keyconfig.plist that you can find at /AddOns/Config/keyconfig.plist; that is the Config-folder that you find inside your AddOns-folder; which is where you put your OXPs. (PC-users have to create the folder /AddOns/Config/ first and then drop a copy of the keyconfig.plist found in /Oolite.app/Contents/Resources/Config/ to this folder.) You can open this file in any text editor and change the ASCII values of the keys used to suit your own preferences. Information on the default keys is also found in the [http://wiki.alioth.net/index.php/Oolite_Keyboard_Controls Oolite Keybord Controls-documentation] here on the wiki.}}

{{FAQ|question=I've completed a number of native and OXP missions and my [[Cobra_Mk.3_%28Oolite%29|Cobra Mk. III]] has a number of new and funky pieces of equipment. However, I'm planning a change of ship, what pieces of equipment will I lose as a result?|answer=Many missions award equipment as a result of either accepting or completing them. For the majority of ship equipment, trading ships will result in the equipment being sold as well, with a few exceptions. The '''Cloaking Device''' and the '''Mark Transponder Scanner''', available from the (native) Cloaking Device and (OXP) Assassins missions respectively are transferred to your new ship. The '''Naval Energy Unit''', although awarded with the completion of the (native) Thargoid Plans mission, will be sold when you trade ships. However, completing the mission allows you to buy these units from high TL systems.}}

{{FAQ|question=I’m using ECM-hardened missiles, but enemies are still able to destroy them! I never seem to be able to destroy enemy hardheads, though. What gives?|answer=ECM-hardened missiles are not ECM-proof. The probability of a hardened missile being destroyed by ECM is 10%–34% depending on range, and if it is destroyed, there’s a 50% chance that it will detonate. This applies equally to hardened missiles fired by computer-controlled ships and those fired by the player. The most effective use of hardened missiles is to use them against relatively slow targets at moderate range, and only use them on nimble ships if you desperately need to force them to break off an attack. Also, don’t use your ECM until a missile is close to blast range (250 metres).

Specifically, the ECM sends out four pulses with different ranges, at half-second intervals. Each pulse has a 10% chance of destroying each hardhead it encounters. For a missile fired at close range, that’s 1 - 0.94 = 34.39% chance of being destroyed within two seconds.}}

{{FAQ|question=If I believe that sizes and distances in Oolite are given in meters, it is so ''unrealistic''. The planets have a diameter of only 30–50 kilometers, and the suns are only 1000 kilometers away. Can't we get a little more realism in space, please?|answer=First of all, remember that Oolite is a ''game'', not a ''space simulation''. This is because it ''wants to'' be a game, not a sim. So yes, sizes and distances are all messed up. Ships and stations are too big, planets and suns are too small, and too close to each other. But this is ''deliberately'' so, and we are not going to change it.

The reason is simple: Realistic sizes and distances don't make a good game. In reality space is so huge that you never would meet anybody else on your journey. Imagine the dozen or so ships you meet in the 500 or so kilometers between witchpoint and planet spread over the realistic 150 '''million''' kilometers between Sun and Earth. Even if your direction is only one degree off the perfect line, you would miss them all. And how interesting would that be for the gameplay? And finally, if you had a realistically sized station in front of a realistically sized planet, how would you ever even notice it? A grain of sand in front of a, well, '''planet'''. The result would be players in complete loneliness and virtually no interaction with NPCs. An utterly, utterly boring game. Therefore it was the right decision to screw realism in the layout of the planetary systems in Elite and Oolite.}}

== Expanding the Game ==

{{FAQ|question=Speaking of OXPs, I've heard a lot about them. What are they? And where do I find them?|answer=OXP stands for 'Oolite eXpansion Pack'. As the name suggests, an OXP is an expansion to the game. It can contain virtually everything: new graphics for your ship, new ships for the player and/or the NPCs, new stations, new missions, new fun. To install an OXP you simply have to drag it into your AddOns-folder (only the OXP itself, not the folder it probably comes in). And as for finding them, you're already at the right place. All OXPs are now (or will become) accessible through the [[OXP|OXP-page of the wiki]]. Just follow the link. And if you fancy trying to create an OXP, the modifying Oolite FAQ can be found [[Modifying Oolite Informal FAQ|here]].}}

{{FAQ|question=Are there any OXPs that are highly recommended? Or can I get a list of 'must-have' OXPs?|answer=This is a difficult one to answer, because it depends so much on personal taste. There is no list of 'must-have' or necessary OXPs that could be agreed upon by all—or even most—players or contributers. But if you have a look at the [http://aegidian.org/bb/index.php Oolite Bulletin Board], especially the [http://aegidian.org/bb/viewforum.php?f=2 Discussion]- and the [http://aegidian.org/bb/viewforum.php?f=4 Expansion Pack]-forums, you will surely find some topics about this question, and the personal answers of a couple of board members.}}

== Why does this and that not exist? ==

{{FAQ|question=Will there ever be an Oolite Massive Multi-player Online Role-Play Game (MMORPG)?|answer=At present Ahruman and Co. (the developers) have no plans to develop either Oolite or a separate branch to accommodate either an MMORPG or an MOG (Multi-player Online Game). This, however, doesn't mean one of you clever bods out there can't try ;-) We suggest you read [http://aegidian.org/bb/viewtopic.php?t=6173 this Bulletin Board thread] before you commence though, it may save you a lot of hair-tearing!}}

{{FAQ|question=Can the range of hyperspace jumps/my fuel capacity be increased?|answer=No. Jump range in Oolite is hard-coded for a reason. The game would become less challenging and thus less fun. (Although I can imagine hacks that give unlimited fuel.) And don't forget that there are already various ways of refuelling while you are in flight.}}

{{FAQ|question=I want Laser Cooling Boosters!|answer=There are none at the moment and the reason is simple. It would unbalance the game too much. If they were available for the player only, things would get too easy. And if the NPCs could get them, too, things would get too hard. It's all about maintaining a reasonable balance. So the ultimate advice on this is: aim carefully; don't waste your laser fire; prevent overheating.}}

{{FAQ|question=The other day I got killed when I launched from a Rock Hermit/Behemoth/whatever, and all the profits/kills that I made before were gone. Why couldn't I save there? Why only on main stations?|answer=First of all, congratulations to you for having internalized the ''Golden Rule'': save early, save often! Unfortunately in Oolite you can save and load a commander only on main stations. That's because they are the only 'fixed' objects in space. The rest of the system is populated anew each time you load a game and is not saved in your savefile. So chances are that the Rock Hermit or Behemoth you docked with when saving simply wouldn't exist when you load again, and you would find yourself in nirvana instead of in a safe haven. To prevent odd behavior like this saving and loading is prohibited anywhere other than in a main station. Alternatively you could install [http://wiki.alioth.net/index.php/Save_Anywhere Save Anywhere.oxp], which does exactly what it says on the tin. Note, however, that it is still in beta state so read the documentation first.}}

{{FAQ|question=I would like to switch between different ships of mine, e.g. have a nice racer for the weekends, meanwhile leave my freighter docked somewhere and take it back on Monday. Why can't I do this?|answer=It is possible for OXPs to provide this facility in 1.77 or later versions. Check the [[OXP_List|OXP List]] or ask on the forum to find one that suits you.}}

== Known Issues / Bugs ==

{{FAQ|question=I am running Oolite on Windows Vista/7 and have installed the game in C:\Program Files\Oolite. I cannot find my saved games, log files, game preferences .GNUstepDefaults file and/or any saved screenshots, although I can see the saved games in the game and use them normally. Where are my files?|answer=You are experiencing file virtualization under Windows. Any application installed in %programfiles%, %systemroot%, %systemdrive% or %programdata that writes files under its folder structure is subject to this. As per Microsoft Support's article KB927387, the resolution for finding your files again is using one of the following methods:
•Click the Compatibility Files button that appears on the Explorer bar to view virtualized files in the folder. The Compatibility Files button appears only if there are virtualized files in the folder.

•Look in the C:\Users\User_name\AppData\Local\VirtualStore folder to locate files and folders.

•Save your application's data in a folder under your user profile.}}

== System Requirements ==

{{FAQ|question=Does it work on Mac OS X 10.2 (Jaguar) & 10.3 (Panther)?|answer=Sadly, no. The minimum OS requirement for Oolite on the Mac is now Mac OS X 10.4. The previous stable version (1.65) is however compatible with Mac OS X 10.3.9}}

{{FAQ|question=Does it work on both Intel and PPC Macs?|answer=Yes, since 1.65 Oolite has been Universal Binary. It was PPC only in previous versions.}}

{{FAQ|question=What's the latest version?|answer=The last stable release is 1.76.1, and the latest test release (recommended) is 1.77. The last stable and latest test versions can be downloaded from [http://oolite.org/download.shtml Oolite's homepage]. More information can be found through the [http://aegidian.org/bb/viewforum.php?f=10 Oolite forums].}}

{{FAQ|question=Is there a port for the PC or Linux?|answer=Yes. Both ports are stable and are at the same level of development as Oolite for the Mac. You can download Oolite for Windows and for Linux PCs from [http://oolite.org/download.shtml Oolite's homepage] (click on "show all platforms" if you can't see the version you're looking for). Information on test releases can be found through the Oolite forums, for the [http://aegidian.org/bb/viewforum.php?f=9 Linux version], and for the [http://aegidian.org/bb/viewforum.php?f=8 Windows version].}}

== Writing OXPs ==

{{FAQ|question=I would like to contribute to Oolite and write my own OXP, but unfortunately my knowledge in scripting/programming is limited. How can I get started?|answer=First of all the Oolite community welcomes all efforts to enhance and enrich their favorite game, so be our guest! Many of us have started with very little knowledge, but over time were able to write and release astonishing OXPs, so why shouldn't you? Anyway, scripting can be learned. Currently there are two scripting languages in use for Oolite, plist-scripting (sometimes referred to as legacy-scripting) and JavaScript. For any serious OXP-plans you will have to learn them. A general starting point is the [http://wiki.alioth.net/index.php/OXP_howto OXP howto]-page, which will link you to further documentation. For plist-scripting you should read the [http://wiki.alioth.net/index.php/OXP_howto_plist OXP howto plist]-page, and also the [http://wiki.alioth.net/index.php/Property_list Property list]-intro. Information on the ongoing implementation of scripting with JavaScript can be found in the [http://wiki.alioth.net/index.php/Category:Oolite_scripting Category page for scripting] (work in progress). If you want to design a new ship, you should have a look at the [http://wiki.alioth.net/index.php/OXP_howto_model OXP howto model]-page and the [http://wiki.alioth.net/index.php/OXP_howto_texture OXP howto texture]-page. And if you want to give it a behavior of its own, you should consult the [http://wiki.alioth.net/index.php/OXP_howto_AI OXP howto AI]-page. I suggest you try to read and understand these first. If you still have questions afterwards, there is always the [http://aegidian.org/bb/index.php Oolite Bulletin Board], where lots of friendly people usually are very willing to lend a helping hand and to answer lots of questions.}}

{{FAQ|question=I want to write an OXP or add content to the Wiki, but some (or all) of the content was written by another author. What copyright issues do I face?|answer=Anything submitted to the Wiki is on the basis that anyone else may edit or fiddle with it. OXPs are submitted under the creative commons licence. The author (strictly speaking) owns the copyright, but licenses users to use or distribute the OXP as long as they don't sell or charge for it. In practice virtually all OXP authors don't assert copyright and are pleased and flattered that somebody thinks their stuff is worth writing about or pinching to use in another OXP (it is good manners to credit the original author in the readme though). I expect the author will be pleased if you want to add some background, but if you are in doubt, send him or her a PM asking him for permission. At the end of the day, Oolite is a fun project and everybody is doing stuff for it on that basis. (nicked wholesale from [http://aegidian.org/bb/viewtopic.php?p=44813#44813 Little_Bear's] post on the [http://aegidian.org/bb/index.php Oolite Bulletin Board])}}

== Diagnosing Problems ==

{{FAQ|question=Someone asked me for my log file. What is that, and where is it?|answer=While Oolite runs, various diagnostic information is written to a file called Latest.log. Where it is depends on your operating system:
* '''Mac OS X''': ~/Library/Logs/Oolite/Latest.log (that is, in your home folder, open the folder named ''Library'', then ''Logs'', then ''Oolite''). Alternatively, select “Show Previous Log” from the “'''Oolite'''” menu in the menu bar when running Oolite.
* '''Windows''': in Oolite’s folder (typically in C:\''Oolite''), there is a folder called ''oolite.app'', which contains a folder called ''Logs''. A shortcut to this folder is created at Oolite's Start Menu entries during installation. If you have installed the game in a folder subject to file virtualization like C:\Program Files\Oolite and encounter difficulty in locating the log files, then please refer to the Known Issues section of this FAQ for information on how to access them.
* '''Linux and other Unix-like systems''': ~/.Oolite/Logs (that is, in the hidden folder ''.Oolite'' in your home folder). If you’re using Nautilus or Konqueror—if you’ve never heard of them, you probably are—select Show Hidden Files from the View menu.}}

{{FAQ|question=Why do none of the OXPs I have installed appear to work in the game?|answer=Check you do not have Oolite in 'Strict Play' mode. When docked or paused press F2 and if it says 'Reset to Unrestricted Play' then OXPs will not work. It needs to say 'Reset to Strict Play'. Alternately perhaps you downloaded and extracted an OXP straight to the "add ons" file. Without then checking that the file ending ".oxp" is moved up from any subdirectory folders to the "add ons" folder itself, as Oolite simply ignores folders etc not ending in .OXP in "add ons"}}

== Other Questions ==

{{FAQ|question=I have a question not answered here, where can I get help?|answer=Post your queries onto [http://aegidian.org/bb/index.php the friendliest board this side of Riedquat™]. Satisfaction is not guaranteed, but then what is, in this mixed-up universe? Help keep the board friendly by making sure your question isn't already answered here!

If you want to report a bug, please read [http://aegidian.org/bb/viewtopic.php?t=3778 this]. Yes, all that work is a drag, but if nobody reports the bug it probably won’t get fixed.

Or join us in #oolite, or #oolite-dev if you're working on Oolite or OXPs, on irc.oftc.net or ipv6.oftc.net.}}

[[Category:Oolite]]

Materials in Oolite

2013-05-04T18:55:17Z

Ahruman:

Traditionally, the surface appearance of ships in Oolite has been defined entirely by textures specified in the ship’s model file and the ''[[#smooth|smooth]]'' attribute. Test release 1.67 added support for [[Shaders in Oolite|shaders]], and test release 1.69 expanded this to a more flexible '''material model'''. Under the new model, the texture file names in model files have been repurposed as '''material keys'''. A material key specifies an entry in the ship’s '''material dictionary''', specified in the ship’s ''[[shipdata.plist]]'' entry. For backwards compatibility, if no material of a given name is found, a material is generated using the material key as a diffuse texture name – providing the same functionality as previous versions of Oolite.

This page documents the material model as of Oolite test release 1.74, and applies to stable release 1.76 and later.

== Important concepts ==
The following concepts are important in understanding how materials work and how they interact with lights.
* '''Colour''': Oolite uses a basic low dynamic range lighting model. Colours are considered to be lists of three values, representing red, green and blue colours, each ranging from 0 to 1. These are often encoded as integers ranging from 0 to 255 for technical reasons, but 0 to 1 is the true range of values. There may also be an associated ''alpha channel'', which is traditionally used for blending effects. In shaders, any colour channel can be used for any purpose, and textures often encode values that are not treated as colours.
* '''Fragment''': roughty speaking, an on-screen pixel. When objects are rendered, their geometry is used to generate a fragments, which are then coloured based on lighting and materials.
* '''Modulation''': multiplying two colours together, by channel. For instance, if the calculated light colour for a given fragment is pale yellow – [1, 1, 0.8] – and the corresponding part of the diffuse map is turquoise – [0.2, 0.8, 0.8] – the ''diffuse contribution'' is [0.2, 0.8, 0.64] (a greenish tint). In graphics programs, this blending mode is usually called ''Multiply''.
* '''Additive blending''': adding two colours together, by channel. In Oolite’s low dynamic range lighting model, the result is always clipped to the range 0..1. In graphics programs, this blending mode is usually called ''Lighten''.
* '''Normals''': All lighting calculations require a concept of the orientation of a surface relative to a light and, for reflections, relative to the camera. A surface oriented towards the light will be lighter than a surface oriented away from it. The ''normal'' for any given point on a surface is a vector pointing straight out, which for our purposes ''defines'' the concept of “straight out”. By default, Oolite models have constant normals across each face. By setting the <code>smooth</code> attribute in [[shipdata.plist]], normals are instead interpolated across each face, with each vertex having a normal that is a weighted average of surounding faces’ normals, and each point on a surface getting a weighted average of the normals at the corners of the face. Using ''smooth groups'', a model can be divided into regions which are smoothed but have sharp boundaries between them. As of Oolite 1.74, models can also include explicit per-vertex normals instead of having Oolite calculate them – most 3D modellers export this information. When using smoothing, it is important to understand that Oolite does not add any geometry,and will result in each vertex being lit as if it is locally flat. This is generally inappropriate for any sharp corner. If you set <code>smooth</code> on a basic cube, the result will be badly lit.
* '''Diffuse reflection''': light that is reflected evenly in all directions. A “dull” surface primarily reflects diffusely. Because the light is reflected evenly in all directions, the diffuse term is independent of the camera position; it is a function of the light and the surface normal. The standard diffuse reflection term is the cosine of the angle between the direction to the light and the normal, or zero if this is negative – this is known as the [http://en.wikipedia.org/wiki/Lambertian_reflectance Lambertian reflectance model]. This value is then modulated with the material’s diffuse colour and diffuse map.
* '''Specular reflection''': light that is reflected in a particular direction, producing a shiny effect. In real life, this is simply a mirror reflection which is generally darkened and blurred, leaving an enlarged, blurry reflection of bright light sources, with other objects being washed out so they aren’t noticeable. In Oolite, a simpler mathematical model called the [http://en.wikipedia.org/wiki/Blinn–Phong_shading_model Blinn-Phong shading model] is used. [http://www.youtube.com/watch?v=76jvMmV1ih0 This video] demonstrates the effects of specular lighting and specular mapping on the built-in scarred alloy model.

== The material dictionary ==
The '''material dictionary''' is actually specified as two separate dictionaries in the ''shipdata.plist'' entry. The first is called ''materials'', the second ''shaders''. If [[Shaders in Oolite|shader support]] is available and enabled, the entries in ''shaders'' are used in preference to those in ''materials''. Otherwise, ''shaders'' is ignored. The entries in the two dictionaries take exactly the same form, however; it is possible to specify a shader in the ''materials'' dictionary, and it will simply be ignored if shader support is not available. The ''materials'' and ''shaders'' dictionaries, merged together, are known as a ''material dictionary''.

=== Material specifiers ===
The material dictionary is a [[property list]] dictionary whose keys are ''material keys'' as defined below, and whose values are '''material specifiers''', which are either dictionaries or strings. When a string is used as a material specifier, it is equivalent to a dictionary with that string as the value for '''diffuse_map''', and no other properties. Currently-supported material specifier keys are listed here; “texture specifier” and similar are defined below.

Most of these keys have no effect when a custom shader is in effect.

When shaders are disabled or not available, emission and illumination maps are supported only if reduced detail is disabled and the graphics hardware supports multi-texturing. If '''emission_modulate_color''', '''illumination_map''', or '''emission_and_illumination_map''' are used, Oolite must combine them into a single emission map. It is generally preferable to do this in advance (by modulating the illumination map with the diffuse map and blending it additively with the emission map, after applying any colouring). This is more efficient when using shaders, too.

{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ General material attribues
! Name !! Type !! Description
|-
| '''ambient_color''' || [[#Colour specifiers|colour specifier]] || The ambient colour of the entity, that is, the colour reflected evenly in all directions by starlight. If there is a '''diffuse_map''', the '''ambient_color''' is modulated by the '''diffuse_map'''. Default: white (1.0, 1.0, 1.0, 1.0).
|-
| '''diffuse_color''' || [[#Colour specifiers|colour specifier]] || Overall diffuse colour of the entity; that is, the colour reflected in a “non-shiny” way on the sunlit side of the entity. If there is a '''diffuse_map''', the '''diffuse_color''' is modulated by the '''diffuse_map'''. Default: white (1.0, 1.0, 1.0, 1.0).
|-
| '''diffuse_map''' || [[#Texture specifiers|texture specifier]] || A texture specifying the basic colour of the material. This is a “normal” texture, the same as you get without a material dictionary. If not specified, the material key will be used. To specify no texture, use an empty string for '''diffuse_map'''. Ignored when using shaders.
|-
| '''emission_color''' || [[#Colour specifiers|colour specifier]] || The emitted (glow) colour of the material. This is ignored when '''emission_map''' is in use (but see also: '''emission_modulate_color'''). Default: black (0.0, 0.0, 0.0, 1.0).
|-
| '''emission_map''' || [[#Texture specifiers|texture specifier]] || A texture specifying emission (glow) colours. This is blended additively with all other colour terms. If '''emission_modulate_color''' is specified, the emission map is modulated by the modulate colour. Emission maps are used when shaders are active, and without shaders on supported hardware.
|-
| '''emission_modulate_color''' || [[#Colour specifiers|colour specifier]] || A colour with which to modulate the '''emission_map'''. If the emission map is in full colour, it is best to apply the colouring in advance using a graphics program. However, if the emission map is a single colour, using a greyscale emission map and a modulate colour will reduce memory usage by a factor of four when shaders are in use. Default: white (1.0, 1.0, 1.0, 1.0).
|-
| '''emission_and_illumination_map''' || [[#Texture specifiers|texture specifier]] || A texture whose RGB channels act like '''emission_map''', and whose alpha channel acts like '''illumination_map''' (and can be coloured with '''illumination_modulate_color'''). This uses less memory (on systems with shaders) than using separate shaders, although blending the emission and illumination maps into a single emission map, as described above, is still preferable.
|-
| '''illumination_map''' || [[#Texture specifiers|texture specifier]] || A texture specifying local illumination colour, which is added to incoming light. It differs from an emission map in that it is modulated with the diffuse colour before being added to the final colour. See example below.
|-
| '''illumination_modulate_color''' || [[#Colour specifiers|colour specifier]] || A colour with which to modulate the '''illumination_map'''. Default: white (1.0, 1.0, 1.0, 1.0).
|-
| '''normal_map''' || [[#Texture specifiers|texture specifier]] || A texture modifying [[#Important concepts|normals]]. The red, green and blue channels are the x, y and z coordinates of normals relative to the underlying normal (“[http://en.wikipedia.org/wiki/Normal_mapping tangent-space normal mapping]”), and the alpha channel is ingored. This is only used when shaders are active and no custom shader is used.
|-
| '''normal_and_parallax_map''' || [[#Texture specifiers|texture specifier]] || Like '''normal_map''', except that the alpha channel is includes a depth value used to add [http://en.wikipedia.org/wiki/Parallax_mapping simulated perspective]. If specified, '''normal_map''' is ignored.
|-
| '''parallax_bias''' || number || A value added to the parallax component of '''normal_and_parallax_map''', after multiplying by '''parallax_scale''' (default: 0).
|-
| '''parallax_scale''' || number || A scale factor for the parallax component of '''normal_and_parallax_map''' (default: 0.01). This value is the depth of the parallax map relative to the size of the texture. For instance, a value of 0.01 on a texture 100 metres wide will produce a maximum indentation of 1 metre. High parallax_scale values tend to lead to unacceptable texture distortion and “creeping” artefacts.
|-
| '''specular_color''' || [[#Colour specifiers|colour specifier]] || The colour to use for specular reflection over the entire model when '''specular_map''' is not used. The specular term is added to the diffuse term; for less intense specular highlights, use a darker colour. Default: black (0.0, 0.0, 0.0, 1.0) if '''shininess''' is zero, (0.2, 0.2, 0.2, 1.0) otherwise.
|-
| '''specular_map''' || [[#Texture specifiers|texture specifier]] || A texture specifying the specular highlight colour in its red, green and blue channels, and '''shininess''' in its alpha channel. 1 (fully opaque) means the value of '''shininess''' is used. 0 means a very low shininess is used. This is only used when shaders are active and no custom shader is used.
|-
| '''specular_modulate_color''' || [[#Colour specifiers|colour specifier]] || A colour with which to modulate the '''specular_map'''. Default: white (1.0, 1.0, 1.0, 1.0).
|-
| '''shininess''' || integer || The “tightness” of specular reflection, ranging from 0 to 128. 0 means no specular highlight. 128 is maximally shiny. Default: 128 if '''specular_map''' is used, 10 otherwise. '''Limitation:''' to use different shininess values with '''specular_map''' or '''specular_color''', you must either use the default or use different “shaders” and “materials” dictionaries. This should be fixed for 1.75.
|-
| '''vertex_shader''' || file name || name of GLSL vertex program to use.
|-
| '''fragment_shader''' || file name || name of GLSL fragment program to use.
|-
| '''textures''' || array of [[#Texture specifiers|texture specifier]]s || Textures to use in shader program.
|-
| '''uniforms''' || dictionary of uniform variable specifiers || uniform variables to use in shader program.
|-
|}

==== Illumination mapping vs. emission mapping ====
This image demonstrates the distinction between illumination mapping (top row) and emission mapping (bottom row).

[[Image:Emission-vs-illumination.png]]

=== Colour specifiers ===
'''Colour specifiers''' are used to declare colours in material attribute dictionaries, and in other contexts such as lasers in ''[[shipdata.plist]]''. Colour specifiers take any of several forms:

==== Named colours ====
The simplest form of colour specifier is a string containing a colour name. The following names are supported:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Colour names
! Name !! RGBA value
|-
| blackColor || 0, 0, 0, 1
|-
| darkGrayColor || 1/3, 1/3, 1/3, 1
|-
| lightGrayColor || 2/3, 2/3, 2/3, 1
|-
| whiteColor || 1, 1, 1, 1
|-
| grayColor || 1/2, 1/2, 1/2, 1
|-
| redColor || 1, 0, 0, 1
|-
| greenColor || 0, 1, 0, 1
|-
| blueColor || 0, 0, 1, 1
|-
| cyanColor || 0, 1, 1, 1
|-
| yellowColor || 1, 1, 0, 1
|-
| magentaColor || 1, 0, 1, 1
|-
| orangeColor || 1, 1/2, 0, 1
|-
| purpleColor || 1/2, 0, 1/2, 1
|-
| brownColor || 0.6, 0.4, 0.2, 1
|-
| clearColor || 0, 0, 0, 0
|-
|}

==== RGBA tuples ====
Colours may also be specified in RGB or RGBA (red, green, blue, alpha [transparency]). RGB or RGBA tuples may be specified as arrays or as strings separated by spaces. The values may range from 0 to 1 or 0 to 255. (If no value is greater than 1, 0–1 is assumed, otherwise 0–255.) Examples:
* <code>"1 1 0"</code> — yellow
* <code>"0 128 0 128"</code> — medium green at 50% opacity
* <code>(1, 0, 0)</code> – red

==== RGBA dictionaries ====
Just in case you’re unsure of the order the RGB[A] components come in, you can use a dictionary:
{
blue = 0.8;
green = 0.8;
}
Accepted keys are '''red''', '''green''', '''blue''' and '''alpha''' (or '''opacity'''), all optional (default: 0.0 for red, green and blue, 1.0 for alpha).

==== HSBA dictionaries ====
But wait, there’s more! Colours may also be specified as dictionaries in the [http://en.wikipedia.org/wiki/HSB_colour_space HSB colour space]. Accepted keys are '''hue''' (hue angle in degrees, required), '''saturation''', '''brightness''' (or '''value''') and '''alpha''' (or '''opacity'''). The default for the optional keys is 1.0.
{
// Pale magenta
hue = 300;
saturation = 0.3;
}

=== Texture specifiers ===
'''Texture specifiers''' are used to, er, specify textures. The simplest form of texture specifier is a string: <code>"ahruman-example-texture.png"</code>. The very simplest texture specifier is the empty string, <code>""</code>, meaning no texture. More complex texture specifiers are dictionaries, which can be used to specify a number of texture options.
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Texture specifier attributes
! Name !! Type !! Description
|-
| '''anisotropy''' || real || The degree of [http://en.wikipedia.org/wiki/Anisotropic_filtering anisotropic filtering] to use. Anisotropic filtering is used to reduce blurriness of MIP mapped textures shown at an angle (and thus only applies to textures whose '''min_filter''' is '''mipmap''' or '''default'''). The '''anisotropy''' setting is multiplied by the maximum anisotropy level specified by the system, and anisotropic filtering is used only if the result is greater than 1. (For example, on a GeForce FX 5200 card, the maximum level is 8, so an anisotropy value of 0.5 means an effective anisotropic filtering strength of 4. The precise meaning of this number is hardware-dependant. Fun, eh?) Anisotropic filtering is disabled in Reduced Detail mode and is not available on all hardware. Default: 0.5.
|-
| '''cube_map''' || boolean || If this is true, and the texture file is six times as high as it is wide, the texture will be treated as a cube map. If cube maps are not supported, it will be converted to a latitude/longitude map; if used as a diffuse map or emission/illumination map, you must ensure the model has appropriate texture coordinates. Note that cube maps are always available if shaders are supported, so custom shaders do not need to worry about this.

'''cube_map''' is always true for planet textures. To convert textures to and from cube maps, see [[planettool]].
|-
| '''extract_channel''' || string || Indicates that one of the channels of the texture should be extracted into a new greyscale texture. Allowed values: '''r''', '''g''', '''b''' and '''a'''.

This obviously involves extra work for Oolite, which is always a bad thing, but it makes it possible to combine multiple effect maps in a single texture for shaders and then extract channels for use as emission or illumination maps without shipping a redundant texture. If this means nothing to you, you probably don’t want to use '''extract_channel'''.
|-
| '''mag_filter''' || string || Specifies how to scale up the texture when it is near the camera. Either of:
* '''nearest''' (use nearest-neighbour sampling, which produces a pixellated effect)
* '''linear''' (use linear interpolation, which produces a blurry effect).
Default: '''linear'''.
|-
| '''min_filter''' || string || Specifies how to scale down the texture when it is far from the camera. One of:
* '''nearest''': nearest-neighbour sampling; generally very ugly, but sometimes useful for shaders using textures for special purposes.
* '''linear''': efficient, but rather ugly for textures with significant contrast or details.
* '''mipmap''': use trilinear MIP map filtering to improve scaling quality; generally also fast and least ugly, but uses 1/3 more memory, potentially slowing down systems with limited RAM or video memory.
* '''default''': '''linear''' in reduced detail mode, otherwise '''mipmap'''.
Default: '''default'''.
|-
| '''name''' || string || The file name of the texture to use. Must be a PNG image, in the Textures folder of Oolite or an OXP. In the specific case of '''diffuse_map''' textures, '''name''' is implicitly the same as the material key; to use no texture, you must specify <code>diffuse_map = ""</code>.
|-
| '''no_shrink''' || boolean || Indicates that Oolite should not scale the texture down, except to meet hardware requirements. Default: false.
|-
| '''repeat_s''' || boolean || Whether Oolite should repeat the texture in the ''s'' (or ''u'') co-ordinate, rather than clamping it. Default: false.
|-
| '''repeat_t''' || boolean || Whether Oolite should repeat the texture in the ''t'' (or ''v'') co-ordinate, rather than clamping it. Default: false.
|-
| '''texture_LOD_bias''' || real || tweak factor for MIP mapping (which does not apply to other '''min_filter''' modes). MIP mapping involves a trade-off between scaling artefacts and blurriness; the LOD (level of detail) bias affects this. Positive values mean more blur, negative ones mean more artefacts. The default value is −0.25 (mostly so people won’t say “hey, why is everything blurrier in the new Oolite?”). Texture LOD bias is not available on all hardware.
|-
|}

=== Uniform specifiers ===
:''Main article: [[Shaders in Oolite: uniforms]]''
A ''uniform specifier'' is used to specify game information to pass to a [[Shaders in Oolite|shader program]]. As with [[#Texture specifiers|texture specifiers]], the simple case is a string, which is treated as <code>{ binding = "the string" }</code>. For instance, uHullHeatLevel = hullHeatLevel</code> will bind a shader’s <code>uHullHeatLevel</code> uniform to a ship’s <code>hullHeatLevel</code> property. Additional properties can be specified in a dictionary.
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Texture specifier attributes
! Name !! Type !! Description
|-
| '''asMatrix''' || boolean || For a '''binding''' uniform whose bound property is of type ''quaternion'', setting '''asMatrix''' to true causes the value to be converted to a rotation matrix. If '''asMatrix''' is false, the quaternion will be converted to a vector, whose w, x, y and z values match those of the quaternion. For any other type of uniform, '''asMatrix''' is ignored. Default: true.
|-
| '''binding''' || string || The entity property to bind to, for a '''binding''' uniform. Ignored for other types of uniform.
|-
| '''clamped''' || boolean || For a '''binding''' uniform whose bound property is of type ''float'', setting '''clamped''' to true causes the value to be restricted to the range 0 to 1, inclusive. For a binding of type ''int'', causes the value to be set to either 0 or 1; 1 indicates that the underlying property has any value other than 0. For any other type of uniform, '''clamped''' is ignored. Default: false.
|-
| '''normalized''' || boolean || For a '''binding''' uniform whose bound property is of type ''vector'', setting '''normalized''' to true causes the value to be normalized, that is, scaled to a length of 1. For any other type of uniform, '''normalized''' is ignored. The spelling '''normalised''' is also accepted. Default: false.
|-
| '''type''' || string || One of:
* '''binding''': indicates that the '''binding''' property specifies an entity property to be set dynamically each time the shader is used.
* '''float''' or '''real''': indicates that the '''value''' property is an floating-point number.
* '''int''' or '''integer''': indicates that the '''value''' property is an integer, or whole number.
* '''texture''': indicates that the '''value''' property is an integer specifying a texture unit, that is, an index in the '''textures''' array.
Default: '''float'''.
|-
| '''value''' || number || The value to use for a '''float''', '''int''' or '''texture''' uniform. Ignored for '''binding''' uniforms.
|-
|}

=== Material dictionary example ===
Here is an example from the [[Material Test Suite OXP]]:
materials =
{
"cube-face" =
{
diffuse_map = "oolite_shader_test_suite_7_diffuse.png";
emission_and_illumination_map = "oolite_shader_test_suite_emission_and_illumination.png";
emission_modulate_color = (160, 255, 160);
illumination_modulate_color = (180, 180, 200);
};
};
Here, the “cube-face” material is assigned the diffuse texture “oolite_shader_test_suite_7_diffuse.png” and a combined emission and illumination map (which is a greyscale+alpha texture). The emission and illumination components are then given coloured tints (slightly green and slightly blue, respectively), producing this:

[[File:Oolite Material Test Suite 7.png|320px]]

== See also ==
* [[Material Test Suite OXP]] — demonstrates most material properties.

[[Category: Oolite]] [[Category:Oolite_scripting]]

Oolite JavaScript Reference: EquipmentInfo

2013-03-30T21:13:59Z

Ahruman: There's no such word as “its'”.

'''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>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 Ship Outfitting screen.

=== <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|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|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 "EQ_MISSILE".

=== <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 ship info 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 "Missile".

=== <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>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 equipment screen. Starting with Oolite 1.77, this key will actually make 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)
True 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)
True 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: Quaternion

2012-12-26T22:00:46Z

Ahruman: /* Quaternion Expressions */ Removed obsolete musings.

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

The '''<code>Quaternion</code>''' class represents a [[quaternion]], a four-dimensional number, which is used to express rotations. Explaining quaternion mathematics is ''way'' beyond the scope of this document, but a quick overview is provided below.

=== Quaternions for Rotations ===
This is a very quick, pragmatic discussion of quaternions as they apply to rotating things in Oolite. If you’re interested in the theory, see:
* Wikipedia: [http://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation Quaternions and spatial rotation]
* Wikipedia: [http://en.wikipedia.org/wiki/Quaternion Quaternion]
* MathWorld: [http://mathworld.wolfram.com/Quaternion.html Quaternion]

Consider a ship at point ''h'' oriented to face a station at point ''t''. This can be expressed as the vector from the ship to the station, ''v'' = ''t'' − ''h''. However, if the ship rolls, it is still heading along the same vector ''v'', so additional information is required: a twist angle, ''α''. A rotation quaternion is a tuple ''Q'' = (''w'', ''x'', ''y'', ''z''), such that
:''Qw'' = cos ''α''/2
:''Qx'' = ''vx'' sin ''α''/2
:''Qy'' = ''vy'' sin ''α''/2
:''Qz'' = ''vz'' sin ''α''/2
Additionally, a rotation quaternion must be normalized; that is, it must fulfill the '''normal invariant''' ''Qw''² + ''Qx''² + ''Qy''² + ''Qz''² = 1. Unlike with [[property list]] scripting and specifications, quaternions will not be automatically normalized for you except where specified, but a <code>[[#normalize|normalize]]()</code> method is provided.

An '''identity rotation''' – that is, one which, when applied, has no effect – is represented by the '''identity quaternion''' (1, 0, 0, 0).

The <code>Quaternion</code> class provides several methods to make construction of rotations easier: <code>[[#rotate|rotate]]()</code>, <code>[[#rotateX|rotateX]]()</code>, <code>[[#rotateY|rotateY]]()</code>, <code>[[#rotateZ|rotateZ]]()</code>.

Rotations can be combined by quaternion multiplication (see the <code>[[#multiply|multiply]]()</code> method). Note that quaternion multiplication is not commutative; that is, ''PQ'' is not the same as ''QP''. If this seems strange, take a box or book and assign it ''x'', ''y'' and ''z'' axes. Rotate it about the ''x'' axis and then the ''y'' axis. Then, rotate it about the ''y'' axis followed by the ''x'' axis. If the results of the two rotations are the same, you’re doing it wrong.

=== Quaternion Expressions ===
All Oolite-provided functions which take a quaternion as an argument may instead be passed an array of four numbers, or an [[Oolite JavaScript Reference: Entity|Entity]] (in which case the entity’s <code>[[Oolite JavaScript Reference: Entity#orientation|orientation]]</code> is used). In specifications, this is represented by arguments typed <code>quaternionExpression</code>.

== Properties ==
=== <code>w</code> ===
'''w''' : Number (read/write)

The ''w'' component of the quaternion.

=== <code>x</code> ===
'''x''' : Number (read/write)
The ''x'' component of the quaternion.

=== <code>y</code> ===
'''y''' : Number (read/write)
The ''y'' component of the quaternion.

=== <code>z</code> ===
'''z''' : Number (read/write)
The ''z'' component of the quaternion.

== Methods ==
=== Constructor ===
'''new Quaternion'''([value : [[#Quaternion Expressions|quaternionExpression]]])
Create a new quaternion with the specified value. If no value is provided, the vector is initialized to the identity quaternion (1, 0, 0, 0).

=== <code>conjugate</code> ===
{{oolite-method-added|1.77}}
function '''conjugate'''() : Quaternion
Return the conjugate of the quaternion (i.e. the quaternion which when multiplied by the original quaternion returns the identity quaternion). The input quaternion must be normalized.

=== <code>dot</code> ===
function '''dot'''(q : [[#Quaternion Expressions|quaternionExpression]]) : Number
Returns the quaternion dot product (inner product) of the target and <code>q</code>. (For two normalized quaternions, this will be 1 if they’re equal, -1 if they’re opposite and 0 if they’re perpendicular.)

=== <code>multiply</code> ===
function '''multiply'''(q : [[#Quaternion Expressions|quaternionExpression]]) : Quaternion
Returns the standard quaternion product (Grassmann product) of the target and <code>q</code>. This is used to concatenate rotations together.

=== <code>normalize</code> ===
function '''normalize'''() : Quaternion
Returns the quaternion adjusted to fulfill the [[#Quaternions for Rotations|normal invariant]]. Specifically, this divides each component by the square root of (''w''² + ''x''² + ''y''² + ''z''²).

=== <code>rotate</code> ===
function '''rotate'''(a : [[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]], angle : Number) : Quaternion
Returns a quaternion rotated <code>angle</code> radians about the axis of <code>a</code>. The vector <code>a</code> must be a normalized vector. (FIXME: clockwise or anticlockwise?)

=== <code>rotateX</code> ===
function '''rotateX'''(angle : Number) : Quaternion
Returns a quaternion rotated <code>angle</code> radians about the ''x'' axis. (FIXME: clockwise or anticlockwise?)

<code>q.rotateX(angle)</code> is equivalent to <code>q.[[#rotate|rotate]]([1, 0, 0], angle)</code>.

=== <code>rotateY</code> ===
function '''rotateY'''(angle : Number) : Quaternion
Returns a quaternion rotated <code>angle</code> radians about the ''y'' axis. (FIXME: clockwise or anticlockwise?)

<code>q.rotateY(angle)</code> is equivalent to <code>q.[[#rotate|rotate]]([0, 1, 0], angle)</code>.

=== <code>rotateZ</code> ===
function '''rotateZ'''(angle : Number) : Quaternion
Returns a quaternion rotated <code>angle</code> radians about the ''z'' axis. (FIXME: clockwise or anticlockwise?)

<code>q.rotateZ(angle)</code> is equivalent to <code>q.[[#rotate|rotate]]([0, 0, 1], angle)</code>.

=== <code>toArray</code> ===
function '''toArray'''() : Array
Returns an array of the quaternion’s components, in the order <code>[w, x, y, z]</code>. <code>q.toArray()</code> is equivalent to <code>[q.w, q.x, q.y, q.z]</code>.

=== <code>vectorForward</code> ===
function '''vectorForward'''() : [[Oolite JavaScript Reference: Vector|Vector]]
Returns the forward vector from the quaternion.

To understand this, consider an entity which is aligned with the world co-ordinate system – that is, its <code>[[Oolite JavaScript Reference: Entity#orientation|orientation]]</code> is the identity quaternion (1, 0, 0, 0), and thus its ''x'' axis is aligned with the world ''x'' axis, its ''y'' axis is aligned with the world ''y'' axis and its ''z'' axis is aligned with the world ''z'' axis. If it is rotated by a quaternion ''Q'', <code>Q.vectorForward()</code> is the forward (''z'') axis after rotation. Similarly, <code>Q.[[#vectorUp|vectorUp]]()</code> is the up (''y'') axis after rotation, and <code>Q.[[#vectorRight|vectorRight]]()</code> is the right (''x'') axis after rotation.

=== <code>vectorRight</code> ===
function '''vectorRight'''() : [[Oolite JavaScript Reference: Vector|Vector]]
Returns the right vector from the quaternion. See <code>[[#vectorForward|vectorForward]]()</code> for a definition.

=== <code>vectorUp</code> ===
function '''vectorUp'''() : [[Oolite JavaScript Reference: Vector|Vector]]
Returns the up vector from the quaternion. See <code>[[#vectorForward|vectorForward]]()</code> for a definition.

== Static Methods ==

=== <code>random</code> ===
function '''random'''() : Quaternion
Returns a random normalized quaternion.

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Quaternion

2012-12-24T10:51:53Z

Ahruman: /* conjugate */ Incorrect synopsis.

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

The '''<code>Quaternion</code>''' class represents a [[quaternion]], a four-dimensional number, which is used to express rotations. Explaining quaternion mathematics is ''way'' beyond the scope of this document, but a quick overview is provided below.

=== Quaternions for Rotations ===
This is a very quick, pragmatic discussion of quaternions as they apply to rotating things in Oolite. If you’re interested in the theory, see:
* Wikipedia: [http://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation Quaternions and spatial rotation]
* Wikipedia: [http://en.wikipedia.org/wiki/Quaternion Quaternion]
* MathWorld: [http://mathworld.wolfram.com/Quaternion.html Quaternion]

Consider a ship at point ''h'' oriented to face a station at point ''t''. This can be expressed as the vector from the ship to the station, ''v'' = ''t'' − ''h''. However, if the ship rolls, it is still heading along the same vector ''v'', so additional information is required: a twist angle, ''α''. A rotation quaternion is a tuple ''Q'' = (''w'', ''x'', ''y'', ''z''), such that
:''Qw'' = cos ''α''/2
:''Qx'' = ''vx'' sin ''α''/2
:''Qy'' = ''vy'' sin ''α''/2
:''Qz'' = ''vz'' sin ''α''/2
Additionally, a rotation quaternion must be normalized; that is, it must fulfill the '''normal invariant''' ''Qw''² + ''Qx''² + ''Qy''² + ''Qz''² = 1. Unlike with [[property list]] scripting and specifications, quaternions will not be automatically normalized for you except where specified, but a <code>[[#normalize|normalize]]()</code> method is provided.

An '''identity rotation''' – that is, one which, when applied, has no effect – is represented by the '''identity quaternion''' (1, 0, 0, 0).

The <code>Quaternion</code> class provides several methods to make construction of rotations easier: <code>[[#rotate|rotate]]()</code>, <code>[[#rotateX|rotateX]]()</code>, <code>[[#rotateY|rotateY]]()</code>, <code>[[#rotateZ|rotateZ]]()</code>.

Rotations can be combined by quaternion multiplication (see the <code>[[#multiply|multiply]]()</code> method). Note that quaternion multiplication is not commutative; that is, ''PQ'' is not the same as ''QP''. If this seems strange, take a box or book and assign it ''x'', ''y'' and ''z'' axes. Rotate it about the ''x'' axis and then the ''y'' axis. Then, rotate it about the ''y'' axis followed by the ''x'' axis. If the results of the two rotations are the same, you’re doing it wrong.

=== Quaternion Expressions ===
All Oolite-provided functions which take a quaternion as an argument may instead be passed an [[Oolite JavaScript Reference: Entity|Entity]] instead, in which case the entity’s <code>[[Oolite JavaScript Reference: Entity#orientation|orientation]]</code> is used. In specifications, this is represented by arguments named <code>quaternionOrEntity</code>. (Is this actually useful? It seems less compellingly so than the [[Oolite JavaScript Reference: Vector#Vector Expressions|vector equivalent]]. -- [[User:Ahruman]])

Additionally, most <code>Quaternion</code> methods may be passed four numbers, or an array of four numbers, instead of a quaternion. In specifications, this is represented by arguments named <code>quaternionExpression</code>.

== Properties ==
=== <code>w</code> ===
'''w''' : Number (read/write)

The ''w'' component of the quaternion.

=== <code>x</code> ===
'''x''' : Number (read/write)
The ''x'' component of the quaternion.

=== <code>y</code> ===
'''y''' : Number (read/write)
The ''y'' component of the quaternion.

=== <code>z</code> ===
'''z''' : Number (read/write)
The ''z'' component of the quaternion.

== Methods ==
=== Constructor ===
'''new Quaternion'''([value : [[#Quaternion Expressions|quaternionExpression]]])
Create a new quaternion with the specified value. If no value is provided, the vector is initialized to the identity quaternion (1, 0, 0, 0).

=== <code>conjugate</code> ===
{{oolite-method-added|1.77}}
function '''conjugate'''() : Quaternion
Return the conjugate of the quaternion (i.e. the quaternion which when multiplied by the original quaternion returns the identity quaternion). The input quaternion must be normalized.

=== <code>dot</code> ===
function '''dot'''(q : [[#Quaternion Expressions|quaternionExpression]]) : Number
Returns the quaternion dot product (inner product) of the target and <code>q</code>. (For two normalized quaternions, this will be 1 if they’re equal, -1 if they’re opposite and 0 if they’re perpendicular.)

=== <code>multiply</code> ===
function '''multiply'''(q : [[#Quaternion Expressions|quaternionExpression]]) : Quaternion
Returns the standard quaternion product (Grassmann product) of the target and <code>q</code>. This is used to concatenate rotations together.

=== <code>normalize</code> ===
function '''normalize'''() : Quaternion
Returns the quaternion adjusted to fulfill the [[#Quaternions for Rotations|normal invariant]]. Specifically, this divides each component by the square root of (''w''² + ''x''² + ''y''² + ''z''²).

=== <code>rotate</code> ===
function '''rotate'''(a : [[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]], angle : Number) : Quaternion
Returns a quaternion rotated <code>angle</code> radians about the axis of <code>a</code>. The vector <code>a</code> must be a normalized vector. (FIXME: clockwise or anticlockwise?)

=== <code>rotateX</code> ===
function '''rotateX'''(angle : Number) : Quaternion
Returns a quaternion rotated <code>angle</code> radians about the ''x'' axis. (FIXME: clockwise or anticlockwise?)

<code>q.rotateX(angle)</code> is equivalent to <code>q.[[#rotate|rotate]]([1, 0, 0], angle)</code>.

=== <code>rotateY</code> ===
function '''rotateY'''(angle : Number) : Quaternion
Returns a quaternion rotated <code>angle</code> radians about the ''y'' axis. (FIXME: clockwise or anticlockwise?)

<code>q.rotateY(angle)</code> is equivalent to <code>q.[[#rotate|rotate]]([0, 1, 0], angle)</code>.

=== <code>rotateZ</code> ===
function '''rotateZ'''(angle : Number) : Quaternion
Returns a quaternion rotated <code>angle</code> radians about the ''z'' axis. (FIXME: clockwise or anticlockwise?)

<code>q.rotateZ(angle)</code> is equivalent to <code>q.[[#rotate|rotate]]([0, 0, 1], angle)</code>.

=== <code>toArray</code> ===
function '''toArray'''() : Array
Returns an array of the quaternion’s components, in the order <code>[w, x, y, z]</code>. <code>q.toArray()</code> is equivalent to <code>[q.w, q.x, q.y, q.z]</code>.

=== <code>vectorForward</code> ===
function '''vectorForward'''() : [[Oolite JavaScript Reference: Vector|Vector]]
Returns the forward vector from the quaternion.

To understand this, consider an entity which is aligned with the world co-ordinate system – that is, its <code>[[Oolite JavaScript Reference: Entity#orientation|orientation]]</code> is the identity quaternion (1, 0, 0, 0), and thus its ''x'' axis is aligned with the world ''x'' axis, its ''y'' axis is aligned with the world ''y'' axis and its ''z'' axis is aligned with the world ''z'' axis. If it is rotated by a quaternion ''Q'', <code>Q.vectorForward()</code> is the forward (''z'') axis after rotation. Similarly, <code>Q.[[#vectorUp|vectorUp]]()</code> is the up (''y'') axis after rotation, and <code>Q.[[#vectorRight|vectorRight]]()</code> is the right (''x'') axis after rotation.

=== <code>vectorRight</code> ===
function '''vectorRight'''() : [[Oolite JavaScript Reference: Vector|Vector]]
Returns the right vector from the quaternion. See <code>[[#vectorForward|vectorForward]]()</code> for a definition.

=== <code>vectorUp</code> ===
function '''vectorUp'''() : [[Oolite JavaScript Reference: Vector|Vector]]
Returns the up vector from the quaternion. See <code>[[#vectorForward|vectorForward]]()</code> for a definition.

== Static Methods ==

=== <code>random</code> ===
function '''random'''() : Quaternion
Returns a random normalized quaternion.

[[Category:Oolite JavaScript Reference]]

User:Ahruman

2012-11-03T20:42:37Z

Ahruman:

Jens Ayton is the current project lead for [[Oolite]], although he has officially retired from “feature development”.

He also has a [http://jens.ayton.se/blag/ programming blog thing] which updates some years.

Oolite JavaScript Reference: System

2012-10-08T17:41:44Z

Ahruman: /* legacy_addShips etc. */ Derp.

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

The '''<code>System</code>''' class represents the current 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>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, “Mostly Industrial”. 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, “Democracy”. 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 “Slimy Blue Frogs”.

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

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

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

== 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 function [[Oolite_JavaScript_Reference:_Vector3D#fromCoordinateSystem|fromCoordinateSystem]] to convert legacy type coordinates to absolute coordinates.

'''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 functions 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>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.

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

=== <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>[[#shipsWithRole|shipsWithRole]]()</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 "This is a dull planet."

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 "This is a dull planet." if called from galaxy 0, and throw an exception if called from the other galaxies.

=== <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 “Inzaan”. <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

2012-10-08T17:41:23Z

Ahruman: /* legacy_addShips etc. */ Formatting error.

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

The '''<code>System</code>''' class represents the current 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>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, “Mostly Industrial”. 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, “Democracy”. 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 “Slimy Blue Frogs”.

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

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

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

== 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 function [[Oolite_JavaScript_Reference:_Vector3D#fromCoordinateSystem|fromCoordinateSystem]] to convert legacy type coordinates to absolute coordinates.

'''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 functions 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>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.

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

=== <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>[[#shipsWithRole|shipsWithRole]]()</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 "This is a dull planet."

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 "This is a dull planet." if called from galaxy 0, and throw an exception if called from the other galaxies.

=== <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 “Inzaan”. <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: World script event handlers

2012-10-08T16:50:22Z

Ahruman: /* Defunct */ Removed reference to reset() (which disappeared in test release 1.74) and marked tickle() as removed.

This page provides an exhaustive list of event handlers which can be implemented inside world scripts [[Scripting Oolite with JavaScript|JavaScript scripts for Oolite]].

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.

=== Game State ===

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

The <code>startUp</code> handler is called after all OXPs have been loaded. It can be used to do one-off initialisation such as registering to listen for certain keystrokes etc. note that keystroke listening is not implemented. (world script only)

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

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

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

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

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

=== Docking ===

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

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

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

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

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

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

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

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

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

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

The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect.

this.shipLaunchedFromStation = function(station)
{
// Your code here
}
At this moment "ship.dockedStation == null", "ship.docked == false", "ship.status == STATUS_IN_FLIGHT".

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

The <code>playerStartedAutoPilot</code> handler is called when the player starts autopilot docking. It is not called for the instantaneous dock command.

this.playerStartedAutoPilot = function()
{
// 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>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".

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Enter/Exit Aegis ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Combat ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== <code>shipKilledOther</code> ====

The <code>shipKilledOther</code> handler is called when a ship kills an other ship. <code>whom</code> the identity of the ship that was killed. <code>damageType</code> is the type of damage. (Handler added in test version 1.75)

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

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

The <code>shipTargetDestroyed</code> handler is called when the target gets destroyed. <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
}

=== Equipment and Cargo ===

==== <code>equipmentDestroyed</code> ====

The <code>equipmentDestroyed</code> handler is called when equipment gets destroyed completely beyond repair. (in strict mode) (world script only)

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

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

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

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

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

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

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

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

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

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

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

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

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

==== <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)
{
// Your code here
}

==== <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
}

=== Other ===

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

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

COMPASS_MODE_BASIC
COMPASS_MODE_PLANET
COMPASS_MODE_STATION
COMPASS_MODE_SUN
COMPASS_MODE_TARGET
COMPASS_MODE_BEACONS

script example

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

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

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

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

==== <code>guiScreenChanged</code> ====

The <code>guiScreenChanged</code> handler is called when the guiScreen changes. "from" is the screen it is changing from and "to" is the screen were it initially switched to. Note that the screen can have changed again in the meantime by the action of other oxps. Therefor, it will generally better to test for the global <code>guiScreen</code> to see which page is really on display instead of using the "to" parameter. (world script only) 
This handler will not fire for every screen the player can switch to, but only when switching to any of the following screens: <code>GUI_SCREEN_MAIN, GUI_SCREEN_STATUS, GUI_SCREEN_MANIFEST, GUI_SCREEN_SYSTEM_DATA, GUI_SCREEN_OPTIONS, GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_SHIPYARD, GUI_SCREEN_SHORT_RANGE_CHART, GUI_SCREEN_LONG_RANGE_CHART, GUI_SCREEN_MARKET, GUI_SCREEN_CONTRACTS, GUI_SCREEN_REPORT</code>

this.guiScreenChanged = function(to, from)
{
// Your code here
}

==== <code>guiScreenWillChange</code> ====

The <code>guiScreenWillChange</code> handler is called when the guiScreen is about to change. It only fires for the screens: <code>GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_MANIFEST, GUI_SCREEN_MARKET, GUI_SCREEN_SHIPYARD</code> and <code>GUI_SCREEN_SYSTEM_DATA</code>. On these screens a script could change the content of the page to be displayed. (world script only)

this.guiScreenWillChange = function(to, from)
{
// Your code here
}

==== <code>missionChoiceWasReset</code> ====

The <code>missionChoiceWasReset</code> handler is called when the mission choice is set to null via script (either using the legacy script method resetMissionChice, or using mission.choice = null; in javascript)

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

==== <code>missionScreenEnded</code> ====

The <code>missionScreenEnded</code> handler is called when the missionscreen ends. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

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

==== <code>missionScreenOpportunity</code> ====

The <code>missionScreenOpportunity</code> handler is called if there are no mission / report screens active, and the player is docked to a station. It gets fired at game startup, upon docking, and after a docking report or previous mission screen has ended. (world script only)

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

This handler works a bit different as other handlers. It fires for every installed oxp, until an oxp creates a mission screen during this handler. Than it stops. When the mission screen ends and there is no callback function that created a new mission screen, than the missionScreenOpportunity is send again to all installed oxps, starting with the oxp that used the mission screen as last one. All this means that when this handler fires, it is safe to show a mission screen and no further test are needed.

==== <code>reportScreenEnded</code> ====

The <code>reportScreenEnded</code> handler is called when the last arrival-report screen ends. This is a screen that should not be written by a missionscreen. The code should wait until this eventhandler fires. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

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

==== <code>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 woldScript is new since Oolite 1.74. After the event is sent to the shipScript, it is now also send to the worldScript with the added entity as argument.

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 a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds.

this.shipLaunchedEscapePod = function(escapepod)
{
// 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
}
}

=== Defunct ===

==== <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]]

Scripting Oolite with JavaScript

2012-10-08T16:48:36Z

Ahruman: /* Using JavaScript */ Removed reference to tickle().

[[Oolite]] 1.68 and later supports scripts written in [http://en.wikipedia.org/wiki/ECMAScript ECMAScript] (more commonly known as [http://en.wikipedia.org/wiki/JavaScript JavaScript]) in addition to its traditional model based on [[property lists]]. This page provides an overview of how JavaScript is used in Oolite. The page [[Oolite JavaScript Reference: object model]] provides reference for Oolite-specific objects and methods. The page [[Oolite JavaScript Reference: world script event handlers]] provides reference for the event handlers Oolite supports. The language standards and some tutorials can be found through the Wiki links provided above.

== Using JavaScript ==

Currently, JavaScript is supported for “worldScripts”, that is, as a replacement for scripts in ''script.plist'' and shipScripts, that acts as expansion for the ships AI. While a ''script.plist'' file may contain any number of separate scripts, a single JavaScript file may contain only one script.

If your OXP only uses one script, place a JavaScript file named ''script.js'' (or ''script.es'') in the OXP’s ''Config'' directory. If you wish to use multiple scripts, you may instead create file named ''world-scripts.plist'' in the ''Config'' directory. This [[property list]] file should consist of an array of worldScript names; the named scripts should exist in a directory named ''Scripts'' inside your OXP. As with most “atomic” files (files which cannot be merged), such script files must have a unique name to avoid conflicts with other OXPs. Using the ''world-scripts.plist'' method, you can combine JavaScript, plist and OOS scripts however you wish.

Whereas plist scripts are based on polling – all scripts are run at semi-regular intervals, whether they need to be or not – scripts written in JavaScript are “event driven” – different functions, or ''event handlers'', in the script are called in response to state changes in the game, or when other events of interest happen. For instance, <code>willExitWitchSpace</code> is called just before player exits witchspace, and <code>alertConditionChanged</code> is called whenever the alert condition changes. See the [[Oolite JavaScript event handler reference|event handler reference]] for a full list of handlers and when Oolite will call them.

=== script.js File Template ===

Copy and paste this template into a file called script.js in the OXP Config directory. Ensure you change at least the Name value. '''Every script must have a unique name.''' If multiple scripts with the same name are encountered, Oolite will arbitrarily select one and discard the others.

<pre>this.name = "My OXP Script"
this.author = "Your Name Here"
this.copyright = "(C) 2009 Me."
this.licence = "CC-NC-by-SA 2.0"
this.description = "This OXP doesn't do very much yet.";
this.version = "1.0 alpha 1"

"use strict";

/* You can copy and paste this function and just change the "startUp"
to another event name to handle other OXP events (eg "STATUS_DOCKED",
"alertConditionChanged", etc).
*/
this.startUp = function()
{
Log("Initialising OXP " + name)
}
</pre>

== See Also ==
* [https://developer.mozilla.org/en/JavaScript/Reference Mozilla JavaScript reference pages]
* [[Oolite JavaScript event handler reference]]
* [[Oolite JavaScript object model]]

* [[Variables in Oolite JavaScripts]]
* [[Javascript Operators]]
* [[Handling OXP Dependencies with JavaScript]]

[[Category:Oolite scripting]]

Running Oolite-Mac

2012-09-19T22:18:52Z

Ahruman: /* Building Oolite from source */

==Overview==
Oolite was originally developed for OS X, and as such, OS X is Oolite's home operating system. The OS X version can be considered the reference version for all other ports. It has some specific Mac OS X only support such as speech synthesis, iTunes integration and Growl integration. Joysticks are not directly supported - however, there are programs that convert joystick inputs into mouse and keyboard inputs, and these programs are reported to work well with Oolite.

==Getting and installing the game==
You can get the most recent release of the game from [http://developer.berlios.de/project/showfiles.php?group_id=3577 BerliOS].

Installation is the standard method of dragging the Oolite folder to your Applications or Games folder.

===Installing [[OXP]]s (add ons)===
In the Oolite folder that you dragged from the disk image, you will find an Oolite application and an AddOns folder. Place OXPs in the AddOns folder, and they will be loaded the next time you start the game.

==Building Oolite from source==

=== Development Environment (Xcode) ===
The supported development environment for Oolite trunk is Xcode 4.5 or later under Mac OS X 10.7.4 or 10.8. At the time of writing, Xcode 4.2–4.4 are likely to work, while earlier versions such as 3.2.6 running under Mac OS X 10.6 or later will only work after some additional changes, and are no longer supported. Xcode 4 is available for free from the [http://itunes.apple.com/us/app/xcode/id497799835?mt=12 Mac App Store].

Earlier versions of Oolite, including the 1.76-maintenace branch, require Xcode 3.2.6, even under Mac OS X 10.7 or 10.8. For more information, see [http://wiki.alioth.net/index.php?title=Running_Oolite-Mac&oldid=28534#Building_Oolite_from_source this earlier version of this page].

You will also require the Subversion version control tool; an up-to-date binary is available [http://downloads.open.collab.net/binaries.html here], or in the optional Xcode command line tools package. To download the command line tools package, select Open Developer Tool→More Developer Tools… from the '''Xcode''' menu within Xcode.

=== Getting the source ===

The source code and data files are available from [http://developer.berlios.de/projects/oolite-linux/ the oolite-linux BerliOS project]. Don't be confused by the name 'oolite-linux'; at one point there were three separate repositories for Oolite, but the Linux one was where they ended up being merged together. The SVN url for the current development line is:

svn://svn.berlios.de/oolite-linux/trunk

Version 1.76 is:

svn://svn.berlios.de/oolite-linux/tags/1.76

The 1.76.x maintenance branch is:

svn://svn.berlios.de/oolite-linux/branches/1.76-maintenance

Note that the 1.76 versions require Xcode 3.2.6 as mentioned above.

To download the source with Subversion, the quickest way to do it is to open a Terminal window, and run the following command:

svn checkout svn://svn.berlios.de/oolite-linux/trunk

If you have a BerliOS account and are a project member, you can get it with:

svn checkout svn+ssh://''accountname''@svn.berlios.de/svnroot/repos/oolite-linux/trunk

Developers should also checkout the relevant maintenance branch:

svn checkout svn+ssh://''accountname''@svn.berlios.de/svnroot/repos/oolite-linux/branches/1.76-maintenance/

=== Building Oolite ===
For a trunk build, open Oolite.xcodeproj, select the ''Oolite – Debug'' or ''Oolite – Test Release'' scheme from the Scheme pop-up menu, and hit Build. Dependencies will be downloaded automatically (in the deps folder inside the Oolite repository).

When you open the project for the first time, Xcode will generate build schemes for all the subprojects used to build Oolite. It is unlikely that you will ever need this, so it’s a good idea to hide them. Select Manage Schemes from the Product menu and uncheck the checkboxes in the Show column, except for the schemes marked Shared.

==== Building earlier versions ====
For instructions on building earlier versions of Oolite, see [http://wiki.alioth.net/index.php?title=Running_Oolite-Mac&oldid=28534#Building_Oolite_from_source this earlier version of this page].

==== Build products ====
Building any of the shared build schemes in trunk will result in the following being created in the build results folder: ''AddOns'', ''Debug.oxp'', ''include'' (with subfolders ''js'', ''ogg'', ''png'' and ''vorbis''), ''jskwgen'', ''jsoplengen'', ''libjs_for_oolite.a'', ''libnspr4_for_oolite.a'', ''libogg_for_oolite.a'', ''libpng_for_oolite.a'', ''libvorbis_for_oolite.a'', ''Oolite.app'', ''Oolite.docktileplugin'' and ''Oolite.mdimporter''. ''AddOns'' contains a copy of ''Debug.oxp''. Oolite.app contains a copy of ''Oolite.mdimporter'' and ''Oolite.docktileplugin'', and static libraries (.a files) are linked into the Oolite executable. Everything except ''Oolite.app'' and ''AddOns'' can be considered side effects of the build process.

[[Category:Oolite]] [[Category:Factual]]

Oolite JavaScript Reference: World script event handlers

2012-07-13T16:10:51Z

Ahruman: /* tickle */ Deprecated, timers now exist.

This page provides an exhaustive list of event handlers which can be implemented inside world scripts [[Scripting Oolite with JavaScript|JavaScript scripts for Oolite]].

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.

=== Game State ===

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

The <code>startUp</code> handler is called after all OXPs have been loaded. It can be used to do one-off initialisation such as registering to listen for certain keystrokes etc. note that keystroke listening is not implemented. (world script only)

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

==== <code>reset (removed in 1.74)</code> ====

The <code>reset</code> handler is called whenever the player is respawned, such as after dying or when loading a saved game. It should be used to reset any local state in the script. (world script only)

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

in 1.74 the startUp event is called in its place, eliminating the need for two separate events.

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

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

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

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

=== Docking ===

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

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

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

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

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

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

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

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

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

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

The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect.

this.shipLaunchedFromStation = function(station)
{
// Your code here
}
At this moment "ship.dockedStation == null", "ship.docked == false", "ship.status == STATUS_IN_FLIGHT".

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

The <code>playerStartedAutoPilot</code> handler is called when the player starts autopilot docking. It is not called for the instantaneous dock command.

this.playerStartedAutoPilot = function()
{
// 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>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".

=== 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; currently, the possible values are “blocked”, “too far” and “insufficient fuel”. Other values may be added in future.

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.

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

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

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

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

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

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

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

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

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

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

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

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

=== Enter/Exit Aegis ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Combat ===

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

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

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

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

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

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

==== <code>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> ====

The <code>shipKilledOther</code> handler is called when a ship kills an other ship. <code>whom</code> the identity of the ship that was killed. <code>damageType</code> is the type of damage. (Handler added in test version 1.75)

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

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

The <code>shipTargetDestroyed</code> handler is called when the target gets destroyed. <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
}

=== Equipment and Cargo ===

==== <code>equipmentDestroyed</code> ====

The <code>equipmentDestroyed</code> handler is called when equipment gets destroyed completely beyond repair. (in strict mode) (world script only)

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

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

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

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

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

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

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

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

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

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

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

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

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

==== <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)
{
// Your code here
}

==== <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
}

=== Other ===

==== <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>guiScreenChanged</code> ====

The <code>guiScreenChanged</code> handler is called when the guiScreen changes. "from" is the screen it is changing from and "to" is the screen were it initially switched to. Note that the screen can have changed again in the meantime by the action of other oxps. Therefor, it will generally better to test for the global <code>guiScreen</code> to see which page is really on display instead of using the "to" parameter. (world script only) 
This handler will not fire for every screen the player can switch to, but only when switching to any of the following screens: <code>GUI_SCREEN_MAIN, GUI_SCREEN_STATUS, GUI_SCREEN_MANIFEST, GUI_SCREEN_SYSTEM_DATA, GUI_SCREEN_OPTIONS, GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_SHIPYARD, GUI_SCREEN_SHORT_RANGE_CHART, GUI_SCREEN_LONG_RANGE_CHART, GUI_SCREEN_MARKET, GUI_SCREEN_CONTRACTS, GUI_SCREEN_REPORT</code>

this.guiScreenChanged = function(to, from)
{
// Your code here
}

==== <code>guiScreenWillChange</code> ====

The <code>guiScreenWillChange</code> handler is called when the guiScreen is about to change. It only fires for the screens: <code>GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_MANIFEST, GUI_SCREEN_MARKET</code> and<code> GUI_SCREEN_SHIPYARD</code>. On these screens a script could change the content of the page to be displayed. In Oolite 1.75 will <code>GUI_SCREEN_SYSTEM_DATA</code> be added to this list. (world script only)

this.guiScreenWillChange = function(to, from)
{
// Your code here
}

==== <code>missionChoiceWasReset</code> ====

The <code>missionChoiceWasReset</code> handler is called when the mission choice is set to null via script (either using the legacy script method resetMissionChice, or using mission.choice = null; in javascript)

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

==== <code>missionScreenEnded</code> ====

The <code>missionScreenEnded</code> handler is called when the missionscreen ends. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

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

==== <code>missionScreenOpportunity</code> ====

The <code>missionScreenOpportunity</code> handler is called if there are no mission / report screens active, and the player is docked to a station. It gets fired at game startup, upon docking, and after a docking report or previous mission screen has ended. (world script only)

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

This handler works a bit different as other handlers. It fires for every installed oxp, until an oxp creates a mission screen during this handler. Than it stops. When the mission screen ends and there is no callback function that created a new mission screen, than the missionScreenOpportunity is send again to all installed oxps, starting with the oxp that used the mission screen as last one. All this means that when this handler fires, it is safe to show a mission screen and no further test are needed.

==== <code>reportScreenEnded</code> ====

The <code>reportScreenEnded</code> handler is called when the last arrival-report screen ends. This is a screen that should not be written by a missionscreen. The code should wait until this eventhandler fires. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

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

==== <code>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 woldScript is new since Oolite 1.74. After the event is sent to the shipScript, it is now also send to the worldScript with the added entity as argument.

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 a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds.

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

==== <code>tickle</code> ====

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.

==== <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
}
}

=== 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: Global

2012-06-10T20:05:24Z

Ahruman: Documented worldScriptNames

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>. Currently, the other possible values are <code>"GUI_SCREEN_INTRO1"</code>, <code>"GUI_SCREEN_INTRO2"</code>, <code>"GUI_SCREEN_STATUS"</code>, <code>"GUI_SCREEN_MANIFEST"</code>, <code>"GUI_SCREEN_EQUIP_SHIP"</code>, <code>"GUI_SCREEN_SHIPYARD"</code>, <code>"GUI_SCREEN_LONG_RANGE_CHART"</code>, <code>"GUI_SCREEN_SHORT_RANGE_CHART"</code>, <code>"GUI_SCREEN_SYSTEM_DATA"</code>, <code>"GUI_SCREEN_MARKET"</code>, <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>. This list may change in future.

=== <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

Mission variables can also be used in legacy scripts and in [[Misc_plists|descriptions.plist]] string expansions, by prefixing the name with “mission_”. 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, will 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. 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>

=== <code>displayNameForCommodity</code> ===
function '''displayNameForCommodity'''(commodityName : 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 [[Methods#Communications|Communications]].
When local key/value pairs are provided, they take precedence over any other values.

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

'''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>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 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 true, the messages will be written to the logfile. 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 temporary enable/disable logging above message by typing in the console:
console.setDisplayMessagesInClass("myOXP.init", true/false)

=== <code>randomInhabitantsDescription</code> ===
function '''randomInhabitantsDescription'''([plural : boolean, default true])
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(true) +".");

=== <code>randomName</code> ===
function '''randomName'''()
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>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: 512 });

=== <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]) : Bool
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]]

Material Test Suite OXP

2012-01-29T20:37:18Z

Ahruman:

The '''Material Test Suite''' is an expansion pack which tests Oolite’s [[Materials in Oolite|material model]] and built-in shaders. It was created during the testing phase before version 1.76 to test material functionality across different platforms and hardware. It may be useful in diagnosing some rendering problems.

To run the test suite:
* [http://jens.ayton.se/oolite/files/material-test-suite-1.2.oxp.zip Download the test suite] and install it. (Oolite test release 1.75 or later required. For information on installing expansion packs, see [[OXP#Installing an OXP"|the “OXP” article]].)
* Run Oolite, and decline when asked whether you want to load a game. (If you are using Strict Mode, disable it and restart Oolite.)
* You should now be presented with an information screen and the options “Run test suite” and “Cancel”. Select “Run test suite”.
* You will now be shown a series of spinning cubes. The precise number shown depends on your system’s capabilities. A successful test shows a grey box with a number on it (see [[#Sample Images|sample images]] below). A failed test will show something else, typically a solid black box.
* Please take a note of any failed tests, writing down the label shown on the left of the screen (such as “simple: 3”). If it is something other than a sold black or red box, please also take a screen shot (“'''*'''” key).
* While you’re at it, we’d appreciate if you tested dust rendering. When the test suite is complete, leave the station and fly away until you are no longer mass locked. Fly at normal speed and at hyperspeed (default: “'''J'''” key). Note whether you see dust particles flying past. Test this in every available shader mode (to change shader mode, pause, press “'''2'''” or “'''F2'''”, and select “Game Options…”).

If all the tests work and dust is nicely dusty, we’re done. You can throw out the Material Test Suite expansion pack and get back to playing the game. Otherwise, please report the problem:
* Quit Oolite and open the log file. (To locate the log file, see [[Oolite FAQ#Diagnosing Problems|the FAQ entry on diagnosing problems]].)
* Copy the lines between “<code>========== [Marker 1] ==========</code>” and “<code>========== [Marker 2] ==========</code>”. Paste them into an e-mail to [mailto:bugs@oolite.org bugs@oolite.org] or [http://www.aegidian.org/bb/viewtopic.php?t=8038 this forum thread] (or send the whole log as an attachment). Don’t forget to specify which tests failed!

If your tests passed, feel free to report anyway. Confirmation that we’re doing something right is good for our egos. But if they failed, we really need to know. We can’t fix problems we don’t know about.

== Sample Images ==
Click the images for a bigger view. Note that tests 8–16 will not be shown on systems without GLSL shader support.

[[File:Oolite Material Test Suite 1.png|160px|left|thumb]] Test 1: <code>diffuse_map</code> only. 

[[File:Oolite Material Test Suite 2.png|160px|left|thumb]] Test 2: <code>diffuse_map</code> and <code>emission_map</code>.

Note that the number '''2''' glows green in the dark. 

[[File:Oolite Material Test Suite 3.png|160px|left|thumb]] Test 3: <code>emission_map</code> only.

Note that the number '''3''' and the ring both glow green in the dark. 

[[File:Oolite Material Test Suite 4.png|160px|left|thumb]] Test 4: <code>diffuse_map</code> and <code>illumination_map</code>.

Note that number '''4''' is illuminated as though by a spotlight (with a slightly blue tint). 

[[File:Oolite Material Test Suite 5.png|160px|left|thumb]] Test 5: <code>illumination_map</code> only.

Note that the number '''5''' and the ring both glow with a dull blue tint. 

[[File:Oolite Material Test Suite 6.png|160px|left|thumb]] Test 6: <code>diffuse_map</code>, <code>emission_map</code> and <code>illumination_map</code>.

Note that the number '''6''' is illuminated as in test 4, and the ring glows with a slight green tint. 

[[File:Oolite Material Test Suite 7.png|160px|left|thumb]] Test 7: <code>diffuse_map</code> and <code>emission_and_illumination_map</code>.

When rendered correctly, the effects should be the same as in test 6. 

[[File:Oolite Material Test Suite 8.png|160px|left|thumb]] Test 8: <code>diffuse_map</code> and <code>normal_map</code>.

Note the shadows and highlights around the inside of the ring, which conform to the main light source, producing the effect of an indentation containing the number '''8'''. 

[[File:Oolite Material Test Suite 9.png|160px|left|thumb]] Test 9: <code>diffuse_map</code> and <code>normal_and_parallax_map</code>.

This should look similar to test 8, but with slightly better perspective. If you noticed a “creeping” effect in test 8, it should be alleviated in test 9. This is more noticeable if you look at the tests again. 

[[File:Oolite Material Test Suite 10.png|160px|left|thumb]] Test 10: <code>emission_map</code> and <code>normal_and_parallax_map</code>.

The number '''10''' and the ring glow as in test 3, and the interior of the ring is indented as in test 9. 

[[File:Oolite Material Test Suite 11.png|160px|left|thumb]] Test 11: <code>diffuse_map</code>, <code>emission_map</code> and <code>normal_and_parallax_map</code>.

The ring is white and the number '''11''' glows green, as in test 2, and the interior of the ring is indented. 

[[File:Oolite Material Test Suite 12.png|160px|left|thumb]] Test 12: <code>diffuse_map</code>, <code>emission_map</code>, <code>illumination_map</code> and <code>normal_and_parallax_map</code>.

The ring glows and the indented area around the number is illuminated as though by a spotlight, as in tests 6 and 7. 

[[File:Oolite Material Test Suite 13.png|160px|left|thumb]] Test 13: <code>diffuse_map</code> and <code>specular_map</code>.

Note that the number '''13''' is only visible as a variation in the glossiness of the surface, and completely invisible in shadow. 

[[File:Oolite Material Test Suite 14.png|160px|left|thumb]] Test 14: <code>specular_map</code> only.

Note that the number '''14''' and the ring are only visible as a variation in the glossiness of the surface, and the cube is uniformly grey in shadow. 

[[File:Oolite Material Test Suite 15.png|160px|left|thumb]] Test 15: <code>diffuse_map</code>, <code>emission_map</code> and <code>specular_map</code>.

A shiny surface as in tests 13 and 14, but width a glowing number '''15'''. 

[[File:Oolite Material Test Suite 16.png|160px|left|thumb]] Test 16: <code>diffuse_map</code>, <code>emission_map</code>, <code>illumination_map</code>, <code>normal_and_parallax_map</code> and <code>specular_map</code>.

Everything all at once: like test 12, but with the varying shininess from tests 13–15.

'''Bug:''' For unknown reasons, the shininess of test 16 does not match that of tests 13–15. 

[[Category:Oolite expansion packs]]

Material Test Suite OXP

2012-01-24T13:15:22Z

Ahruman: No longer soliciting test results.

The '''Material Test Suite''' is an expansion pack which tests Oolite’s [[Materials in Oolite|material model]] and built-in shaders. It was created during the testing phase before version 1.76 to test material functionality across different platforms and hardware. It may be useful in diagnosing some rendering problems.

To run the test suite:
* [http://jens.ayton.se/oolite/files/material-test-suite-1.2.oxp.zip Download the test suite] and install it. (Oolite test release 1.75 or later required. For information on installing expansion packs, see [[OXP#Installing an OXP"|the “OXP” article]].)
* Run Oolite, and decline when asked whether you want to start a new game. (If you are using Strict Mode, disable it and restart Oolite.)
* You should now be presented with an information screen and the options “Run test suite” and “Cancel”. Select “Run test suite”.
* You will now be shown a series of spinning cubes. The precise number shown depends on your system’s capabilities. A successful test shows a grey box with a number on it (see [[#Sample Images|sample images]] below). A failed test will show something else, typically a solid black box.
* Please take a note of any failed tests, writing down the label shown on the left of the screen (such as “simple: 3”). If it is something other than a sold black or red box, please also take a screen shot (“'''*'''” key).
* While you’re at it, we’d appreciate if you tested dust rendering. When the test suite is complete, leave the station and fly away until you are no longer mass locked. Fly at normal speed and at hyperspeed (default: “'''J'''” key). Note whether you see dust particles flying past. Test this in every available shader mode (to change shader mode, pause, press “'''2'''” or “'''F2'''”, and select “Game Options…”).

If all the tests work and dust is nicely dusty, we’re done. You can throw out the Material Test Suite expansion pack and get back to playing the game. Otherwise, please report the problem:
* Quit Oolite and open the log file. (To locate the log file, see [[Oolite FAQ#Diagnosing Problems|the FAQ entry on diagnosing problems]].)
* Copy the lines between “<code>========== [Marker 1] ==========</code>” and “<code>========== [Marker 2] ==========</code>”. Paste them into an e-mail to [mailto:bugs@oolite.org bugs@oolite.org] or [http://www.aegidian.org/bb/viewtopic.php?t=8038 this forum thread] (or send the whole log as an attachment). Don’t forget to specify which tests failed!

If your tests passed, feel free to report anyway. Confirmation that we’re doing something right is good for our egos. But if they failed, we really need to know. We can’t fix problems we don’t know about.

== Sample Images ==
Click the images for a bigger view. Note that tests 8–16 will not be shown on systems without GLSL shader support.

[[File:Oolite Material Test Suite 1.png|160px|left|thumb]] Test 1: <code>diffuse_map</code> only. 

[[File:Oolite Material Test Suite 2.png|160px|left|thumb]] Test 2: <code>diffuse_map</code> and <code>emission_map</code>.

Note that the number '''2''' glows green in the dark. 

[[File:Oolite Material Test Suite 3.png|160px|left|thumb]] Test 3: <code>emission_map</code> only.

Note that the number '''3''' and the ring both glow green in the dark. 

[[File:Oolite Material Test Suite 4.png|160px|left|thumb]] Test 4: <code>diffuse_map</code> and <code>illumination_map</code>.

Note that number '''4''' is illuminated as though by a spotlight (with a slightly blue tint). 

[[File:Oolite Material Test Suite 5.png|160px|left|thumb]] Test 5: <code>illumination_map</code> only.

Note that the number '''5''' and the ring both glow with a dull blue tint. 

[[File:Oolite Material Test Suite 6.png|160px|left|thumb]] Test 6: <code>diffuse_map</code>, <code>emission_map</code> and <code>illumination_map</code>.

Note that the number '''6''' is illuminated as in test 4, and the ring glows with a slight green tint. 

[[File:Oolite Material Test Suite 7.png|160px|left|thumb]] Test 7: <code>diffuse_map</code> and <code>emission_and_illumination_map</code>.

When rendered correctly, the effects should be the same as in test 6. 

[[File:Oolite Material Test Suite 8.png|160px|left|thumb]] Test 8: <code>diffuse_map</code> and <code>normal_map</code>.

Note the shadows and highlights around the inside of the ring, which conform to the main light source, producing the effect of an indentation containing the number '''8'''. 

[[File:Oolite Material Test Suite 9.png|160px|left|thumb]] Test 9: <code>diffuse_map</code> and <code>normal_and_parallax_map</code>.

This should look similar to test 8, but with slightly better perspective. If you noticed a “creeping” effect in test 8, it should be alleviated in test 9. This is more noticeable if you look at the tests again. 

[[File:Oolite Material Test Suite 10.png|160px|left|thumb]] Test 10: <code>emission_map</code> and <code>normal_and_parallax_map</code>.

The number '''10''' and the ring glow as in test 3, and the interior of the ring is indented as in test 9. 

[[File:Oolite Material Test Suite 11.png|160px|left|thumb]] Test 11: <code>diffuse_map</code>, <code>emission_map</code> and <code>normal_and_parallax_map</code>.

The ring is white and the number '''11''' glows green, as in test 2, and the interior of the ring is indented. 

[[File:Oolite Material Test Suite 12.png|160px|left|thumb]] Test 12: <code>diffuse_map</code>, <code>emission_map</code>, <code>illumination_map</code> and <code>normal_and_parallax_map</code>.

The ring glows and the indented area around the number is illuminated as though by a spotlight, as in tests 6 and 7. 

[[File:Oolite Material Test Suite 13.png|160px|left|thumb]] Test 13: <code>diffuse_map</code> and <code>specular_map</code>.

Note that the number '''13''' is only visible as a variation in the glossiness of the surface, and completely invisible in shadow. 

[[File:Oolite Material Test Suite 14.png|160px|left|thumb]] Test 14: <code>specular_map</code> only.

Note that the number '''14''' and the ring are only visible as a variation in the glossiness of the surface, and the cube is uniformly grey in shadow. 

[[File:Oolite Material Test Suite 15.png|160px|left|thumb]] Test 15: <code>diffuse_map</code>, <code>emission_map</code> and <code>specular_map</code>.

A shiny surface as in tests 13 and 14, but width a glowing number '''15'''. 

[[File:Oolite Material Test Suite 16.png|160px|left|thumb]] Test 16: <code>diffuse_map</code>, <code>emission_map</code>, <code>illumination_map</code>, <code>normal_and_parallax_map</code> and <code>specular_map</code>.

Everything all at once: like test 12, but with the varying shininess from tests 13–15.

'''Bug:''' For unknown reasons, the shininess of test 16 does not match that of tests 13–15. 

[[Category:Oolite expansion packs]]

Oolite JavaScript Reference: SystemInfo

2012-01-20T11:54:58Z

Ahruman: Removed outdated beta stuff.

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

'''<code>SystemInfo</code>''' objects provide information about a specific system. <code>SystemInfo</code>s can be retrieved for any system in the current galaxy, but not systems in other galaxies. If you keep a reference to a <code>SystemInfo</code> object after the player goes to a different galaxy, attempts to read properties of the stored <code>SystemInfo</code> will cause an exception.

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)

=== <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);

'''See also:''' <code>SystemInfo.[[#systemsInRange_2|systemsInRange()]]</code> (which always provides results relative to the current system).

== 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);
});
}

[[Category:Oolite JavaScript Reference]]

Shaders in Oolite: uniforms

2012-01-19T17:29:18Z

Ahruman: /* Conversions */ Spelling

:The information presented on this page applies to Oolite test release 1.69 and later.

A '''uniform''' in a [[Shaders in Oolite|shader]] is a variable whose value is specified by the host application – in this case, [[Oolite]]. Oolite allows arbitrary uniforms to be specified for shaders applied to ships, and these may either take constant values specified in ''shipdata.plist'', or be “bound” to an attribute of the ship. This allows shader authors to access numerous properties of a game entity without having to ask for them and wait for an updated version of Oolite. ('''Note:''' in the case of subentities, bound properties are fetched from the parent ship.)

=== Basic syntax ===
Uniforms are specified in the ''materials'' or ''shaders'' dictionary of a ship’s ''shipdata.plist'' entry:
"ahruman_shady_cobra_example" =
{
 like_ship = "cobra3-player";
 shaders =
 {
 "cobra3_redux.png" =
 {
 textures = ( "cobra3_redux.png" );
 fragment_shader = "ahruman_shady_cobra_example.fragment";
uniforms =
{
shininess =
{
type = float;
value = 42.0;
};
withinAegis = "withinStationAegis";
compassMode = "compassMode";
}
 }
 }
}
This contrived example declares three uniforms, ''shininess'', ''withinAegis'' and ''compassMode''. ''shininess'' is a constant <code>float</code>; it is always 42. ''withinAegis'' is bound to the ship’s ''withinStationAegis'' property. (See below for information on available properties.) This is a boolean, that is, a number whose value is either 0 (meaning no) or 1 (meaning yes). ''compassMode'' is a binding to the ''compassMode'' property. To use the uniforms within a shader (either a vertex shader or a fragment shader), they are declared as follows:
uniform float shininess;
uniform int withinAegis;
uniform int compassMode;
...
void main(void)
{
if (withinAegis)
{
// Do aegis-specific effect here
}
...
}

=== Uniform property types ===
Every bindable property has a '''type'''. The simplest types, ''int'' and ''float'', correspond directly to the same types in GLSL. Both represent numbers, with the difference that a ''float'' can represent fractional values and very large values, but always has the same level of precision (about six digits), while ''int''s can represent any integer (non-fractional value) in a limited range. A ''bool'' is an integer whose value can be only 0 (meaning no or false) or 1 (meaning yes or true). ('''Note:''' the GLSL specification is deliberately vague on the ranges of the number types. It also points out that most hardware will actually use floating-point calculations for ''int'' variables, which implies that integer calculations will incur rounding overhead.)

The ''vector'' type is translated to a GLSL ''vec4'', whose ''x'', ''y'' and ''z'' components correspond to those of the Oolite vector, and whose ''w'' component is always 1.0.

The ''quaternion'' type can be translated to a ''mat4x4'' representing a rotation matrix, or to a ''vec4'' whose ''x'', ''y'', ''z'' and ''w'' components correspond to those of the Oolite quaternion.

The ''matrix'' type is translated into a GLSL ''mat4x4''.

The ''colour'' type is translated into a GLSL ''vec4'' type, whose ''r'', ''g'', ''b'' and ''a'' components correspond to those of the Oolite colour object.

==== Conversions ====
Several types of binding can be modified by conversion options, specified in the '''uniforms''' dictionary, for example:
haveFuel =
{
binding = "fuel";
clamped = true;
};
The '''clamped''' conversion option, when applied to a property of type ''float'', causes the value to be clamped to the range [0, 1]. When applied to an ''int'' property, any value other than 0 (including negative values) is converted to 1. The default value is ''false''.

The '''normalized''' option causes vector properties to be normalized, that is, scaled so they have the same direction but length 1. The default value is ''false''.

The '''asMatrix''' option causes quaternion properties to be converted to rotation matrix, rather than having their components packed into a ''vec4''. The default value is ''true''.

=== Bindable property reference ===
The following sections list entity properties which can be used in a uniform binding, regardless of apparent usefullness. Note, however, that '''some of these names may change before the next stable release'''.

==== Entity ====
The following properties are available for all entities:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Bindable entity properties
! Name !! Type !! Description
|-
| ''position'' || vector || The location of the entity in system co-ordinates.
|-
| ''orientation'' || quaternion || The orientation of the entity.
|-
| ''relativePosition'' || vector || The location of the entity, relative to the player.
|-
| ''viewpointOffset'' || vector || The location of the current camera, in entity co-ordinates. Although this is defined for all entities, it is only meaningful for the player ship.
|-
| ''collisionRadius'' || float || Together with the ''position'', specifies a sphere completely containing the collidable volume of the entity.
|-
| ''mass'' || float || The mass of the entity.
|-
| ''energy'' || float || The current energy level of the entity.
|-
| ''maxEnergy'' || float || The current maximum energy level of the entity.
|-
| ''universalTime'' || float || The [[Time scales in Oolite#game real time|game real time]] clock. The value is the same for all entities and updates once per frame.
|-
| ''spawnTime'' || float || The [[Time scales in Oolite#game real time|game real time]] at which the entity came into existance.
|-
| ''timeElapsedSinceSpawn'' || float || The number of seconds (in the [[Time scales in Oolite#game real time|game real time]] scale) since the entity came into existance – the difference between ''universalTime'' and ''spawnTime''.
|-
| ''throwingSparks'' || bool || Whether the entity is generating sparks (for instance, a ship about to explode).
|-
|}

==== Ship ====
Ships (i.e., anything set up in ''shipdata.plist'', regardless of function) have all the properties of [[#Entity|entities]], and several others:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Bindable ship properties
! Name !! Type !! Description
|-
| ''isBeacon'' || bool || True if the entity is a beacon.
|-
| ''isFrangible'' || bool || True if the entity is frangible, i.e. subentities can be shot off.
|-
| ''isCloaked'' || bool || True if the entity is cloaked. [b]Note:[/b] a cloaked ship will only be drawn approximately once per ten frames, regardless of shaders.
|-
| ''isJammingScanning'' || bool || True if the ship has an active military jammer.
|-
| ''hasMilitaryScannerFilter'' || bool || True if the ship has a military scanner filter.
|-
| ''messageTime'' || float || Time before a radio message may be sent, in seconds. (This is set to 6.0 seconds when an NPC ship sends a message, and decreases over time.)
|-
| ''groupID'' || int || Unique identifier for the escort group the ship belongs to.
|-
| ''escortCount'' || int || The number of active escorts the ship has.
|-
| ''hasHostileTarget'' || bool || True if the ship has a target and the ship’s current AI behaviour is one of hostile intent.
|-
| ''weaponRange'' || float || Maximum range (in metres) of the ship’s main weapon. [b]Note:[/b] since subentities’ shaders get the parent ship’s properties, this may not work as expected.
|-
| ''scannerRange'' || float || The distance (in metres) in which the ship will scan for enemies.
|-
| ''withinStationAegis'' || float || True if the ship is within the aegis of the system’s main station.
|-
| ''fuel'' || int || Ship’s fuel level, in tenths of a light year.
|-
| ''flightPitch'' || float || Current pitch rate.
|-
| ''flightRoll'' || float || Current roll rate.
|-
| ''flightYaw'' || float || Current yaw rate. Currently always 0 for NPC ships.
|-
| ''flightSpeed'' || float || Ship’s current speed.
|-
| ''maxFlightSpeed'' || float || Ship’s speed at full throttle. Something of a misnomer – actual speed may be higher using afterburners or hyperspeed.
|-
| ''speedFactor'' || float || ''flightSpeed'' divided by ''maxFlightSpeed''. May be greater than 1.0 (unless [[#Conversions|clamped]] is used).
|-
| ''damage'' || int || ''energy'' expressed as a percentage of ''maxEnergy''.
|-
| ''laserHeatLevel'' || float || The temperature level of the current weapon.
|-
| ''hullHeatLevel'' || float || The temperature level of the hull, due to proximity to stars, atmospheric drag or combat hits. When it reaches 1.0, the ship starts taking damage rapidly.
|-
| ''entityPersonality'' || float || A randomly-generated value in the range 0.0 to 1.0 that stays with the entity for its lifetime. Useful for adding random variations.
|-
| ''entityPersonalityInt'' || float || Same as ''entity_personality'', scaled to the range 0 to 32767.
|-
| ''numberOfScannedShips'' || int || The number of ships within scanner range (but no more than 16).
|-
| ''destination'' || vector || The location, in system co-ordinates, that the AI is trying to fly to. This may not always be meaningful depending on AI state.
|-
| ''rangeToDestination'' || float || The distance in metres between ''position'' and ''destination''.
|-
| ''rangeToPrimaryTarget'' || float || The distance in metres to the AI’s target (i.e., the ship it is trying to shoot). 0 if no target.
|-
| ''laserColor'' || colour || The colour of the ship’s laser.
|-
| ''isHulk'' || bool || True if the ship has been abandoned.
|-
| ''lightsActive'' || bool || True if flashers are turned on, false otherwise.
|-
|}

==== Player ship ====
The player ship has all the properties of [[#Entity|entities]] and [[#Ship|ships]], and several others:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Bindable player ship properties
! Name !! Type !! Description
|-
| ''massLocked'' || bool || True if the ship is too close to a large object to be able to make a witchspace jump.
|-
| ''atHyperspeed'' || bool || True if the ship is at hyperspeed.
|-
| ''velocityVector'' || vector || The ship’s velocity.
|-
| ''dialForwardShield'' || float || The forward shield level, ranging from 0.0 to 1.0.
|-
| ''dialAftShield'' || float || The aft shield level, ranging from 0.0 to 1.0.
|-
| ''dialMissileStatus'' || int || State of selected missile – 0 for safe/no missile, 1 for active, 2 for locked.
|-
| ''dialFuelScoopStatus'' || int || State of cargo scoop – 0 for no scoop installed, 1 for full hold, 2 for idle with space in hold, 3 for actively scooping.
|-
| ''compassMode'' || int || State of advanced space compass – 0 for no advanced space compass installed, 1 for planet mode, 2 for station mode, 3 for sun mode, 4 for target mode, 5 for any beacon. More may be added in future.
|-
| ''activeMissile'' || int || Which missile slot is currently selected, from 0 to ''dialMaxMissiles'' - 1.
|-
| ''dialMaxMissiles'' || int || The number of missile slots on the ship.
|-
| ''dialIdentEngaged'' || bool || True if ident (targeting) mode is active.
|-
| ''alertCondition'' || int || Current alert condition – 0 for docked, 1 for green, 2 for yellow, 3 for red.
|-
| ''trumbleCount'' || int || Number of trumbles with which the player’s ship is infected.
|-
|}
Additionally, all [[Methods#Querying states|state query scripting methods]] ending with ''_number'' may be used for the player.

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

Shaders in Oolite: uniforms

2012-01-19T17:28:24Z

Ahruman: /* Basic syntax */ Formatting fixes.

:The information presented on this page applies to Oolite test release 1.69 and later.

A '''uniform''' in a [[Shaders in Oolite|shader]] is a variable whose value is specified by the host application – in this case, [[Oolite]]. Oolite allows arbitrary uniforms to be specified for shaders applied to ships, and these may either take constant values specified in ''shipdata.plist'', or be “bound” to an attribute of the ship. This allows shader authors to access numerous properties of a game entity without having to ask for them and wait for an updated version of Oolite. ('''Note:''' in the case of subentities, bound properties are fetched from the parent ship.)

=== Basic syntax ===
Uniforms are specified in the ''materials'' or ''shaders'' dictionary of a ship’s ''shipdata.plist'' entry:
"ahruman_shady_cobra_example" =
{
 like_ship = "cobra3-player";
 shaders =
 {
 "cobra3_redux.png" =
 {
 textures = ( "cobra3_redux.png" );
 fragment_shader = "ahruman_shady_cobra_example.fragment";
uniforms =
{
shininess =
{
type = float;
value = 42.0;
};
withinAegis = "withinStationAegis";
compassMode = "compassMode";
}
 }
 }
}
This contrived example declares three uniforms, ''shininess'', ''withinAegis'' and ''compassMode''. ''shininess'' is a constant <code>float</code>; it is always 42. ''withinAegis'' is bound to the ship’s ''withinStationAegis'' property. (See below for information on available properties.) This is a boolean, that is, a number whose value is either 0 (meaning no) or 1 (meaning yes). ''compassMode'' is a binding to the ''compassMode'' property. To use the uniforms within a shader (either a vertex shader or a fragment shader), they are declared as follows:
uniform float shininess;
uniform int withinAegis;
uniform int compassMode;
...
void main(void)
{
if (withinAegis)
{
// Do aegis-specific effect here
}
...
}

=== Uniform property types ===
Every bindable property has a '''type'''. The simplest types, ''int'' and ''float'', correspond directly to the same types in GLSL. Both represent numbers, with the difference that a ''float'' can represent fractional values and very large values, but always has the same level of precision (about six digits), while ''int''s can represent any integer (non-fractional value) in a limited range. A ''bool'' is an integer whose value can be only 0 (meaning no or false) or 1 (meaning yes or true). ('''Note:''' the GLSL specification is deliberately vague on the ranges of the number types. It also points out that most hardware will actually use floating-point calculations for ''int'' variables, which implies that integer calculations will incur rounding overhead.)

The ''vector'' type is translated to a GLSL ''vec4'', whose ''x'', ''y'' and ''z'' components correspond to those of the Oolite vector, and whose ''w'' component is always 1.0.

The ''quaternion'' type can be translated to a ''mat4x4'' representing a rotation matrix, or to a ''vec4'' whose ''x'', ''y'', ''z'' and ''w'' components correspond to those of the Oolite quaternion.

The ''matrix'' type is translated into a GLSL ''mat4x4''.

The ''colour'' type is translated into a GLSL ''vec4'' type, whose ''r'', ''g'', ''b'' and ''a'' components correspond to those of the Oolite colour object.

==== Conversions ====
Several types of binding can be modified by conversion options, specified in the '''uniforms''' dictionary, for example:
haveFuel =
{
binding = "fuel";
clamped = true;
};
The '''clamped''' conversion option, when applied to a property of type ''float'', causes the value to be clamped to the range [0, 1]. When applied to an ''int'' propertie, any value other than 0 (including negative values) is converted to 1. The default value is ''false''.

The '''normalized''' option causes vector properties to be normalized, that is, scaled so they have the same direction but length 1. The default value is ''false''.

The '''asMatrix''' option causes quaternion properties to be converted to rotation matrix, rather than having their components packed into a ''vec4''. The default value is ''true''.

=== Bindable property reference ===
The following sections list entity properties which can be used in a uniform binding, regardless of apparent usefullness. Note, however, that '''some of these names may change before the next stable release'''.

==== Entity ====
The following properties are available for all entities:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Bindable entity properties
! Name !! Type !! Description
|-
| ''position'' || vector || The location of the entity in system co-ordinates.
|-
| ''orientation'' || quaternion || The orientation of the entity.
|-
| ''relativePosition'' || vector || The location of the entity, relative to the player.
|-
| ''viewpointOffset'' || vector || The location of the current camera, in entity co-ordinates. Although this is defined for all entities, it is only meaningful for the player ship.
|-
| ''collisionRadius'' || float || Together with the ''position'', specifies a sphere completely containing the collidable volume of the entity.
|-
| ''mass'' || float || The mass of the entity.
|-
| ''energy'' || float || The current energy level of the entity.
|-
| ''maxEnergy'' || float || The current maximum energy level of the entity.
|-
| ''universalTime'' || float || The [[Time scales in Oolite#game real time|game real time]] clock. The value is the same for all entities and updates once per frame.
|-
| ''spawnTime'' || float || The [[Time scales in Oolite#game real time|game real time]] at which the entity came into existance.
|-
| ''timeElapsedSinceSpawn'' || float || The number of seconds (in the [[Time scales in Oolite#game real time|game real time]] scale) since the entity came into existance – the difference between ''universalTime'' and ''spawnTime''.
|-
| ''throwingSparks'' || bool || Whether the entity is generating sparks (for instance, a ship about to explode).
|-
|}

==== Ship ====
Ships (i.e., anything set up in ''shipdata.plist'', regardless of function) have all the properties of [[#Entity|entities]], and several others:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Bindable ship properties
! Name !! Type !! Description
|-
| ''isBeacon'' || bool || True if the entity is a beacon.
|-
| ''isFrangible'' || bool || True if the entity is frangible, i.e. subentities can be shot off.
|-
| ''isCloaked'' || bool || True if the entity is cloaked. [b]Note:[/b] a cloaked ship will only be drawn approximately once per ten frames, regardless of shaders.
|-
| ''isJammingScanning'' || bool || True if the ship has an active military jammer.
|-
| ''hasMilitaryScannerFilter'' || bool || True if the ship has a military scanner filter.
|-
| ''messageTime'' || float || Time before a radio message may be sent, in seconds. (This is set to 6.0 seconds when an NPC ship sends a message, and decreases over time.)
|-
| ''groupID'' || int || Unique identifier for the escort group the ship belongs to.
|-
| ''escortCount'' || int || The number of active escorts the ship has.
|-
| ''hasHostileTarget'' || bool || True if the ship has a target and the ship’s current AI behaviour is one of hostile intent.
|-
| ''weaponRange'' || float || Maximum range (in metres) of the ship’s main weapon. [b]Note:[/b] since subentities’ shaders get the parent ship’s properties, this may not work as expected.
|-
| ''scannerRange'' || float || The distance (in metres) in which the ship will scan for enemies.
|-
| ''withinStationAegis'' || float || True if the ship is within the aegis of the system’s main station.
|-
| ''fuel'' || int || Ship’s fuel level, in tenths of a light year.
|-
| ''flightPitch'' || float || Current pitch rate.
|-
| ''flightRoll'' || float || Current roll rate.
|-
| ''flightYaw'' || float || Current yaw rate. Currently always 0 for NPC ships.
|-
| ''flightSpeed'' || float || Ship’s current speed.
|-
| ''maxFlightSpeed'' || float || Ship’s speed at full throttle. Something of a misnomer – actual speed may be higher using afterburners or hyperspeed.
|-
| ''speedFactor'' || float || ''flightSpeed'' divided by ''maxFlightSpeed''. May be greater than 1.0 (unless [[#Conversions|clamped]] is used).
|-
| ''damage'' || int || ''energy'' expressed as a percentage of ''maxEnergy''.
|-
| ''laserHeatLevel'' || float || The temperature level of the current weapon.
|-
| ''hullHeatLevel'' || float || The temperature level of the hull, due to proximity to stars, atmospheric drag or combat hits. When it reaches 1.0, the ship starts taking damage rapidly.
|-
| ''entityPersonality'' || float || A randomly-generated value in the range 0.0 to 1.0 that stays with the entity for its lifetime. Useful for adding random variations.
|-
| ''entityPersonalityInt'' || float || Same as ''entity_personality'', scaled to the range 0 to 32767.
|-
| ''numberOfScannedShips'' || int || The number of ships within scanner range (but no more than 16).
|-
| ''destination'' || vector || The location, in system co-ordinates, that the AI is trying to fly to. This may not always be meaningful depending on AI state.
|-
| ''rangeToDestination'' || float || The distance in metres between ''position'' and ''destination''.
|-
| ''rangeToPrimaryTarget'' || float || The distance in metres to the AI’s target (i.e., the ship it is trying to shoot). 0 if no target.
|-
| ''laserColor'' || colour || The colour of the ship’s laser.
|-
| ''isHulk'' || bool || True if the ship has been abandoned.
|-
| ''lightsActive'' || bool || True if flashers are turned on, false otherwise.
|-
|}

==== Player ship ====
The player ship has all the properties of [[#Entity|entities]] and [[#Ship|ships]], and several others:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Bindable player ship properties
! Name !! Type !! Description
|-
| ''massLocked'' || bool || True if the ship is too close to a large object to be able to make a witchspace jump.
|-
| ''atHyperspeed'' || bool || True if the ship is at hyperspeed.
|-
| ''velocityVector'' || vector || The ship’s velocity.
|-
| ''dialForwardShield'' || float || The forward shield level, ranging from 0.0 to 1.0.
|-
| ''dialAftShield'' || float || The aft shield level, ranging from 0.0 to 1.0.
|-
| ''dialMissileStatus'' || int || State of selected missile – 0 for safe/no missile, 1 for active, 2 for locked.
|-
| ''dialFuelScoopStatus'' || int || State of cargo scoop – 0 for no scoop installed, 1 for full hold, 2 for idle with space in hold, 3 for actively scooping.
|-
| ''compassMode'' || int || State of advanced space compass – 0 for no advanced space compass installed, 1 for planet mode, 2 for station mode, 3 for sun mode, 4 for target mode, 5 for any beacon. More may be added in future.
|-
| ''activeMissile'' || int || Which missile slot is currently selected, from 0 to ''dialMaxMissiles'' - 1.
|-
| ''dialMaxMissiles'' || int || The number of missile slots on the ship.
|-
| ''dialIdentEngaged'' || bool || True if ident (targeting) mode is active.
|-
| ''alertCondition'' || int || Current alert condition – 0 for docked, 1 for green, 2 for yellow, 3 for red.
|-
| ''trumbleCount'' || int || Number of trumbles with which the player’s ship is infected.
|-
|}
Additionally, all [[Methods#Querying states|state query scripting methods]] ending with ''_number'' may be used for the player.

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

Oolite JavaScript Reference: Global

2012-01-17T08:22:38Z

Ahruman: /* isValidFrameCallback */ Style fix

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 ot 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>. Currently, the other possible values are <code>"GUI_SCREEN_INTRO1"</code>, <code>"GUI_SCREEN_INTRO2"</code>, <code>"GUI_SCREEN_STATUS"</code>, <code>"GUI_SCREEN_MANIFEST"</code>, <code>"GUI_SCREEN_EQUIP_SHIP"</code>, <code>"GUI_SCREEN_SHIPYARD"</code>, <code>"GUI_SCREEN_LONG_RANGE_CHART"</code>, <code>"GUI_SCREEN_SHORT_RANGE_CHART"</code>, <code>"GUI_SCREEN_SYSTEM_DATA"</code>, <code>"GUI_SCREEN_MARKET"</code>, <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>. This list may change in future.

=== <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

Mission variables can also be used in legacy scripts and in [[Misc_plists|descriptions.plist]] string expansions, by prefixing the name with “mission_”. 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 were the loop "<code>for ( var i= 0 ; i < 1000 ; i++){}</code>" takes just 0.62 msec, will the same loop with missionVarriables <code>for (missionVariables.i= 0 ; missionVariables.i < 1000 ; missionVariables.i++){}</code> consume 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>worldScripts</code> ===
'''worldScripts''' : Object (read-only)
A list of world script objects.

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

=== <code>displayNameForCommodity</code> ===
function '''displayNameForCommodity'''(commodityName : 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 [[Methods#Communications|Communications]].
When local key/value pairs are provided, they take precedence over any other values.

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

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

=== <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 can be used to specify which type of message is written to the log.

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

=== <code>randomInhabitantsDescription</code> ===
function '''randomInhabitantsDescription'''([plural : boolean, default true])
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(true) +".");

=== <code>randomName</code> ===
function '''randomName'''()
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>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: 512 });

=== <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]) : Bool
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]]

Running Oolite-Mac

2012-01-08T19:29:16Z

Ahruman: /* Development Environment (Xcode) */ Linkified app store.

==Overview==
Oolite was originally developed for OS X, and as such, OS X is Oolite's home operating system. The OS X version can be considered the reference version for all other ports. It has some specific Mac OS X only support such as speech synthesis, iTunes integration and Growl integration. Joysticks are not directly supported - however, there are programs that convert joystick inputs into mouse and keyboard inputs, and these programs are reported to work well with Oolite.

==Getting and installing the game==
You can get the most recent release of the game from [http://developer.berlios.de/project/showfiles.php?group_id=3577 BerliOS].

Installation is the standard method of dragging the Oolite folder to your Applications or Games folder.

===Installing OXPs (add ons)===
In the Oolite folder that you dragged from the disk image, you will find an Oolite application and an AddOns folder. Place OXPs in the AddOns folder, and they will be loaded the next time you start the game.

==Building Oolite from source==

=== Development Environment (Xcode) ===
The supported development environment for Oolite trunk is Xcode 4.2 or later under Mac OS X 10.7. At the time of writing, earlier versions of Xcode running under Mac OS X 10.6 or later will work, but are not supported. Xcode 4 is available for free from the [http://itunes.apple.com/se/app/xcode/id448457090?mt=12 Mac App Store].

Earlier versions of Oolite, including the 1.76-maintenace branch, require Xcode 3.2.6, even under Mac OS X 10.7. For more information, see [http://wiki.alioth.net/index.php?title=Running_Oolite-Mac&oldid=28534#Building_Oolite_from_source this earlier version of this page].

You will also require the Subversion version control tool; an up-to-date binary is available [http://downloads.open.collab.net/binaries.html here].

=== Getting the source ===

The source code and data files are available from [http://developer.berlios.de/projects/oolite-linux/ the oolite-linux BerliOS project]. Don't be confused by the name 'oolite-linux'; at one point there were three separate repositories for Oolite, but the Linux one was where they ended up being merged together. The SVN url for the current development line is:

svn://svn.berlios.de/oolite-linux/trunk

Version 1.76 is:

svn://svn.berlios.de/oolite-linux/tags/1.76

The 1.76.x maintenance branch is:

svn://svn.berlios.de/oolite-linux/branches/1.76-maintenance

Note that the 1.76 versions require Xcode 3.2.6 as mentioned above.

To download the source with Subversion, the quickest way to do it is to open a Terminal window, and run the following command:

svn checkout svn://svn.berlios.de/oolite-linux/trunk

If you have a BerliOS account and are a project member, you can get it with:

svn checkout svn+ssh://''accountname''@svn.berlios.de/svnroot/repos/oolite-linux/trunk

Developers should also checkout the relevant maintenance branch:

svn checkout svn+ssh://''accountname''@svn.berlios.de/svnroot/repos/oolite-linux/branches/1.76-maintenance/

=== Building Oolite ===
For a trunk build, open Oolite.xcodeproj, select the ''Oolite – Debug'' or ''Oolite – Test Release'' scheme from the Scheme pop-up menu, and hit Build. Dependencies will be downloaded automatically (in the deps folder inside the Oolite repository).

When you open the project for the first time, Xcode will generate build schemes for all the subprojects used to build Oolite. It is unlikely that you will ever need this, so it’s a good idea to hide them. Select Manage Schemes from the Product menu and uncheck the checkboxes in the Show column, except for the schemes marked Shared.

==== Building earlier versions ====
For instructions on building earlier versions of Oolite, see [http://wiki.alioth.net/index.php?title=Running_Oolite-Mac&oldid=28534#Building_Oolite_from_source this earlier version of this page].

==== Build products ====
Building any of the shared build schemes in trunk will result in the following being created in the build results folder: ''AddOns'', ''Debug.oxp'', ''include'' (with subfolders ''js'', ''ogg'', ''png'' and ''vorbis''), ''jskwgen'', ''jsoplengen'', ''libjs_for_oolite.a'', ''libnspr4_for_oolite.a'', ''libogg_for_oolite.a'', ''libpng_for_oolite.a'', ''libvorbis_for_oolite.a'', ''Oolite.app'', ''Oolite.docktileplugin'' and ''Oolite.mdimporter''. ''AddOns'' contains a copy of ''Debug.oxp''. Oolite.app contains a copy of ''Oolite.mdimporter'' and ''Oolite.docktileplugin'', and static libraries (.a files) are linked into the Oolite executable. Everything except ''Oolite.app'' and ''AddOns'' can be considered side effects of the build process.

[[Category:Oolite]] [[Category:Factual]]

Running Oolite-Mac

2012-01-08T19:25:30Z

Ahruman: /* Building Oolite from source */ Updated for Xcode 4 regime.

==Overview==
Oolite was originally developed for OS X, and as such, OS X is Oolite's home operating system. The OS X version can be considered the reference version for all other ports. It has some specific Mac OS X only support such as speech synthesis, iTunes integration and Growl integration. Joysticks are not directly supported - however, there are programs that convert joystick inputs into mouse and keyboard inputs, and these programs are reported to work well with Oolite.

==Getting and installing the game==
You can get the most recent release of the game from [http://developer.berlios.de/project/showfiles.php?group_id=3577 BerliOS].

Installation is the standard method of dragging the Oolite folder to your Applications or Games folder.

===Installing OXPs (add ons)===
In the Oolite folder that you dragged from the disk image, you will find an Oolite application and an AddOns folder. Place OXPs in the AddOns folder, and they will be loaded the next time you start the game.

==Building Oolite from source==

=== Development Environment (Xcode) ===
The supported development environment for Oolite trunk is Xcode 4.2 or later under Mac OS X 10.7. At the time of writing, earlier versions of Xcode running under Mac OS X 10.6 or later will work, but are not supported. Xcode 4 is available for free from the Mac App Store.

Earlier versions of Oolite, including the 1.76-maintenace branch, require Xcode 3.2.6, even under Mac OS X 10.7. For more information, see [http://wiki.alioth.net/index.php?title=Running_Oolite-Mac&oldid=28534#Building_Oolite_from_source this earlier version of this page].

You will also require the Subversion version control tool; an up-to-date binary is available [http://downloads.open.collab.net/binaries.html here].

=== Getting the source ===

The source code and data files are available from [http://developer.berlios.de/projects/oolite-linux/ the oolite-linux BerliOS project]. Don't be confused by the name 'oolite-linux'; at one point there were three separate repositories for Oolite, but the Linux one was where they ended up being merged together. The SVN url for the current development line is:

svn://svn.berlios.de/oolite-linux/trunk

Version 1.76 is:

svn://svn.berlios.de/oolite-linux/tags/1.76

The 1.76.x maintenance branch is:

svn://svn.berlios.de/oolite-linux/branches/1.76-maintenance

Note that the 1.76 versions require Xcode 3.2.6 as mentioned above.

To download the source with Subversion, the quickest way to do it is to open a Terminal window, and run the following command:

svn checkout svn://svn.berlios.de/oolite-linux/trunk

If you have a BerliOS account and are a project member, you can get it with:

svn checkout svn+ssh://''accountname''@svn.berlios.de/svnroot/repos/oolite-linux/trunk

Developers should also checkout the relevant maintenance branch:

svn checkout svn+ssh://''accountname''@svn.berlios.de/svnroot/repos/oolite-linux/branches/1.76-maintenance/

=== Building Oolite ===
For a trunk build, open Oolite.xcodeproj, select the ''Oolite – Debug'' or ''Oolite – Test Release'' scheme from the Scheme pop-up menu, and hit Build. Dependencies will be downloaded automatically (in the deps folder inside the Oolite repository).

When you open the project for the first time, Xcode will generate build schemes for all the subprojects used to build Oolite. It is unlikely that you will ever need this, so it’s a good idea to hide them. Select Manage Schemes from the Product menu and uncheck the checkboxes in the Show column, except for the schemes marked Shared.

==== Building earlier versions ====
For instructions on building earlier versions of Oolite, see [http://wiki.alioth.net/index.php?title=Running_Oolite-Mac&oldid=28534#Building_Oolite_from_source this earlier version of this page].

==== Build products ====
Building any of the shared build schemes in trunk will result in the following being created in the build results folder: ''AddOns'', ''Debug.oxp'', ''include'' (with subfolders ''js'', ''ogg'', ''png'' and ''vorbis''), ''jskwgen'', ''jsoplengen'', ''libjs_for_oolite.a'', ''libnspr4_for_oolite.a'', ''libogg_for_oolite.a'', ''libpng_for_oolite.a'', ''libvorbis_for_oolite.a'', ''Oolite.app'', ''Oolite.docktileplugin'' and ''Oolite.mdimporter''. ''AddOns'' contains a copy of ''Debug.oxp''. Oolite.app contains a copy of ''Oolite.mdimporter'' and ''Oolite.docktileplugin'', and static libraries (.a files) are linked into the Oolite executable. Everything except ''Oolite.app'' and ''AddOns'' can be considered side effects of the build process.

[[Category:Oolite]] [[Category:Factual]]

Oolite JavaScript Reference: Vector3D

2012-01-06T16:41:28Z

Ahruman: /* rotationTo */ Noted that both vectors must be normal, and cleaned up.

'''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 target and <code>v</code>.

<code>u.distanceTo(v)</code> is equivalent to <code>u.[[#subtract|subtract]](v).[[#magnitude|magnitude]]()</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 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 target and <code>v</code>.

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

=== <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]]

Oolite JavaScript Reference: System

2011-12-16T21:41:02Z

Ahruman: Removed Oolite 1.75 change notes.

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

The '''<code>System</code>''' class represents the current 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>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, “Mostly Industrial”. 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, “Democracy”. 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 “Slimy Blue Frogs”.

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

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

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

== 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 function [[Oolite_JavaScript_Reference:_Vector3D#fromCoordinateSystem|fromCoordinateSystem]] to convert legacy type coordinates to absolute coordinates.

'''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>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, 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()]] 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>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.

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

=== <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>[[#shipsWithRole|shipsWithRole]]()</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 his is a dull planet."

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 "This is a dull planet." if called from galaxy 0, null from the other galaxies.

=== <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 “Inzaan”. <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: Station

2011-12-16T21:40:49Z

Ahruman: Removed Oolite 1.75 change notes.

'''Prototype:''' <code>[[Oolite JavaScript Reference: Ship|Ship]]</code> 
'''Subtypes:''' none

The '''<code>Station</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing a station or carrier (i.e., a ship with a docking port). A <code>Station</code> has all the properties and methods of a <code> [[Oolite JavaScript Reference: Ship|Ship]]</code>, and some others.

== Properties ==
=== <code>alertCondition</code> ===
'''alertCondition''' : Number (read/write, integer)
Returns the current alert condition. 1 = Green, 2 = Yellow, 3 = Red.

=== <code>allowsAutoDocking</code> ===
'''allowsAutoDocking''' : Boolean (read/write)
If <code>true</code>, the player may dock with this station using autopilot (assuming it isn’t hostile). The corresponding ''[[shipdata.plist]]'' key is <code>allows_auto_docking</code> (default: <code>true</code>).

=== <code>allowsFastDocking</code> ===
'''allowsFastDocking''' : Boolean (read/write)
If <code>true</code>, the player may dock with this station instantaneously (assuming it isn’t hostile). The corresponding ''[[shipdata.plist]]'' key is <code>allows_fast_docking</code> (default: <code>false</code>, but set to <code>true</code> when setting up the main station).

=== <code>dockedContractors</code> ===
'''dockedContractors''' : Number (read-only, integer)
Returns the number of docked contractors ships that can launch as miner or scavenger. 
There is only one counter for miners and scavengers. The maximum that can launch as miner/scavenger is determined by the shipdata-key max_scavengers. However, miners can only launch when there is no other miner in the stations scanner range, even when contractor ships are docked.

=== <code>dockedDefenders</code> ===
'''dockedDefenders''' : Number (read-only, integer)
Returns the number of docked defence ships that can launch as defence ships. 
There is only one counter for defence and police ships. However, the maximum that can launch as defenders is determined by the shipdata-key max_defense_ships.

=== <code>dockedPolice</code> ===
'''dockedPolice''' : Number (read-only, integer)
Returns the number of docked defence ships that can launch as police or patrol ships. 
There is only one counter for defence and police ships. However, the maximum that can launch as police/patrol is determined by the shipdata-key max_police.

=== <code>equipmentPriceFactor</code> ===
'''equipmentPriceFactor''' : Number (read-only, float)
Returns the equipment_price_factor for the station as defined in shipdata.plist.

=== <code>equivalentTechLevel</code> ===
'''equivalentTechLevel''' : Number (read-only, Integer)
Returns the equivalent_tech_level for the station as defined in shipdata.plist.

=== <code>hasNPCTraffic</code> ===
'''hasNPCTraffic''' : Boolean (read/write)
If <code>true</code>, the station has associated non-player traffic, such as shuttles, patrol ships and scavengers. Corresponds to the <code>has_npc_traffic</code> ''[[shipdata.plist#has_npc_traffic|shipdata.plist]]'' key.

=== <code>isMainStation</code> ===
'''isMainStation''' : Boolean (read-only)
<code>true</code> if the station is the main station of the system, <code>false</code> otherwise.

=== <code>requiresDockingClearance</code> ===
'''requiresDockingClearance''' : Boolean (read/write)
<code>true</code> if the station requires docking clearance, <code>false</code> otherwise.

=== <code>suppressArrivalReports</code> ===
'''suppressArrivalReports''' : Boolean (read/write)
If set to <code>true</code>, arrival reports are not shown when the player docks with the station.

== Methods ==
=== <code>dockPlayer</code> ===
'''dockPlayer()''' : Boolean
This method docks the player at the specified station. Returns <code>false</code> if docking fails, otherwise <code>true</code>.

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

=== <code>launchMiner</code> ===
'''launchMiner()''' : Ship
This method adds a ship with a miner role to the launching queue at the specified station. Returns the entity of the chosen ship.

=== <code>launchPatrol</code> ===
'''launchPatrol()''' : Ship
This method adds a ship with a police role and planetPatrolAI.plist to the launching queue at the specified station. Returns the entity of the chosen ship.

=== <code>launchPirateShip</code> ===
'''launchPirateShip()''' : Ship
This method adds a ship with a pirate role to the launching queue at the specified station. All ships launch with a primary role of "defense_ship" and pirateAI.plist. These pirate ships are counted as defense_ship. Returns the entity of the chosen ship.

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

=== <code>launchScavenger</code> ===
'''launchScavenger()''' : Ship
This method adds a ship with a scavenger role to the launching queue at the specified station. Launches only a scavenger when there is a contractor ship at the station and when the number of scavengers around the station is less than the maximum number of scavengers. Returns the entity of the chosen ship.

=== <code>launchShipWithRole</code> ===
'''launchShipWithRole(role : String, [abortAllDockings : Boolean])''' : Ship
This method adds a ship with given role to the launching queue at the specified station. Launches only a miner when there is a contractor ship at the station and when the number of miners around the station is zero. (there can only be one!) Returns the entity of the chosen ship. 
When <code>abortAllDockings</code> is <code>true</code> (default: <code>false</code>), all ships in the docking process get an ''abort'' message and launching of ships starts immediately. Don't use this parameter when not strictly necessary for your launching ship.

=== <code>launchShuttle</code> ===
'''launchShuttle()''' : Ship
This method adds a ship with a shuttle role to the launching queue at the specified station. Returns the entity of the chosen ship.

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Ship

2011-12-16T21:40:35Z

Ahruman: Removed Oolite 1.75 change notes.

'''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 a <code>Entity</code>, and several others.

<code>[[Oolite JavaScript Reference: Station|Station]]</code>s and the <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code> are types of ship. Note that these more specific types have additional properties and methods.

== Properties ==
=== <code>aftWeapon</code> ===
'''aftWeapon''' : EquipmentType (read-only)
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 AI.

'''See also:''' <code>[[#AIState|AIState]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>

=== <code>AIState</code> ===
'''AIState''' : String (read/write, read-only for player)
The ship’s AI’s current state.

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#reactToAIMessage|reactToAIMessage()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code>

=== <code>beaconCode</code> ===
'''beaconCode''' : String (read-only)
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>.

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

=== <code>bounty</code> ===
'''bounty''' : Number (read/write integer)
The bounty on the ship. In the case of the player, it is halved at each witchspace jump. 
It is actually the legal status of the ship that is shown here and not the bounty. For all ships both are the same but for anything with scan class Thargoid the legal status is only based on the ships mass and has no relation to its defined bounty.

=== <code>cargoSpaceCapacity</code> ===
'''cargoSpaceCapacity''' : Number (read-only integer)
The ship’s cargo capacity, in tons.

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

=== <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>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>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>displayName</code> ===
'''displayName''' : String (read/write, read-only for player)
The name of the ship as seen by the player. By default it is the same as <code>[[#name|name]]</code>.

=== <code>entityPersonality</code> ===
'''entityPersonality''' : Number (read-only integer)
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]].

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

=== <code>escorts</code> ===
'''escorts''' : Array (read-only array of [[Oolite JavaScript Reference: Entity|Entity]]s)
The ship’s deployed escorts.

=== <code>forwardWeapon</code> ===
'''forwardWeapon''' : EquipmentType (read-only)
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>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)
True 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.

=== <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 "boulder in its roleset)

=== <code>isCargo</code> ===
'''isCargo''' : Boolean (read-only)
<code>true</code> if the ship is cargo (i.e., has scan_class CLASS_CARGO 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 * 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>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>isJamming</code> ===
'''isJamming''' : Boolean (read-only)
<code>true</code> if the ship has a military scanner jammer which is currently active <code>false</code> otherwise.

=== <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 have ships, station and escape pods pilots and have cargo, rocks, missiles or buoys no pilots.

=== <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: CLASS_ROCK)

=== <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>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>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 false in their ''shipdata.plist'' declarations.

=== <code>maxSpeed</code> ===
'''maxSpeed''' : Number (read-only)
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)
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>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>passengerCapacity</code> ===
'''passengerCapacity''' : Number (read-only integer)
The ship’s maximum passenger capacity.

=== <code>passengerCount</code> ===
'''passengerCount''' : Number (read-only integer)
The ship’s current number of passengers.

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

=== <code>portWeapon</code> ===
'''portWeapon''' : EquipmentType (read-only)
The currently equipped forward weapon, or <code>null</code>. Currently, this is always <code>null</code> for non-player ships.

'''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 “pirate trader(0.5) escort”, and a ship of that type is spawned to be a trader, its <code>primaryRole</code> is <code>"trader"</code>, its <code>roles</code> is <code>["escort", "pirate", "trader"]</code> and its <code>roleWeights</code> is <code> { "escort":1, "pirate":1, "trader":0.5}</code>.

'''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> ===
'''roles''' : 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>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>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>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>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>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 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. 
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 expclicit convert its content to a number by using parseInt(scriptInfo.myKey) or parseFloat(scriptInfo.myKey).

=== <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)
The currently equipped forward weapon, or <code>null</code>. Currently, this is always <code>null</code> for non-player ships.

'''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>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>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)
The ship’s thrust, ranging from 0 to <code>maxThrust</code>. This value determines how fast the ship accelerates or decelerates, specified in m/s².

'''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 true, 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>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).

== Methods ==
=== <code>abandonShip</code> ===
function '''abandonShip'''() : Boolean
Returns <code>true</code> when the ship has an escapepod. It will launch all escapeposd on board leaving the ship behind as a empty hulk. (scanClass = CLASS_CARGO). This command does nothing when no escape-pod is present. 
Pressence of an escapepod can be tested with: <code>equipmentStatus("EQ_ESCAPE_POD") == "EQUIPMENT_OK"</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>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.

=== <code>deployEscorts</code> ===
function '''deployEscorts'''()
Launch the ship’s escorts, if any.

=== <code>dockEscorts</code> ===
function '''dockEscorts'''()
Dock the ship’s deployed escorts, if any.

=== <code>dumpCargo</code> ===
function '''dumpCargo'''() : 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.

'''See also:''' <code>[[#dumpCargo|dumpCargo]]</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 scanClass of the ejected item will always be CLASS_CARGO.

'''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 scanClass of the ejected item will always be CLASS_CARGO.

'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectItem|ejectItem]]</code>

=== <code>equipmentStatus</code> ===
function '''equipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : String
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>.

'''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>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>hasRole</code> ===
function '''hasRole'''(role : String)
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>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>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 this.shipRemoved(suppressDeathEvent) event. By default it will also trigger a this.shipDied() event, unless <code>suppressDeathEvent</code> is true.

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

=== <code>removeEquipment</code> ===
function '''removeEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]])
Removes the given piece of equipment from the ship.
This function can also be used to remove missiles (and mines). If more than one missile of the same type is found on board, only one of them will be removed.

Example:
ship.removeEquipment("EQ_ECM");

=== <code>restoreSubEntities</code> ===
function '''restoreSubEntities'''() : Boolean
Recreate all destroyed subentities of the ship. Returns <code>true</code> if any subentities were added.

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

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>

=== <code>setCargo</code> ===
function '''setCargo'''(commodity : String [, count : Number]) : Boolean
Attempts to create <code>count</code> weight units of the commodity <code>commodity</code> for a cargo barrel. (Can not be used to set cargo for ships) When more units are defined than 1 ton, the count is reduced to one ton. It returns false when the selected commodity is unknown. If <code>count</code> is not specified, one will be assumed.

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

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: PlayerShip

2011-12-16T21:40:15Z

Ahruman: Removed Oolite 1.75 change notes.

'''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 Player 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>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, nonnegative)
The rate at which the aft shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. Currently always the same as <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, but this may change in future.

'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code>

=== <code>compassMode</code> ===
'''compassMode''' : String (read-only)
Returns the current compass mode, which can be any one of the following:
* COMPASS_MODE_BASIC
* COMPASS_MODE_PLANET
* COMPASS_MODE_STATION
*COMPASS_MODE_SUN
* COMPASS_MODE_TARGET
* COMPASS_MODE_BEACONS

=== <code>compassTarget</code> ===
'''compassTarget''' : Entity(read-only)
Points at the entity currently targeted by the compass.

=== <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)
True 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>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, nonnegative)
The rate at which the forward shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. Currently always the same as <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, but this may change in future.

'''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>hudHidden</code> ===
'''hudHidden''' : Boolean (read/write)
Whether the HUD should be visible.

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

=== <code>maxAftShield</code> ===
'''maxAftShield''' : Number (read-only, nonnegative)
The highest possible value of <code>[[#aftShield|aftShield]]</code>. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. Currently always the same as <code>[[#maxForwardShield|maxForwardShield]]</code>, but this may change in future.

'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code>

=== <code>maxForwardShield</code> ===
'''maxAftShield''' : Number (read-only, nonnegative)
The highest possible value of <code>[[#forwardShield|forwardShield]]</code>. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. Currently always the same as <code>[[#maxAftShield|maxAftShield]]</code>, but this may change in future.

'''See also''': <code>[[#forwardShield|forwardShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code>

=== <code>reticleTargetSensitive</code> ===
'''reticleTargetSensitive''' : Boolean (read/write)
If true, and Scanner Targeting Enhancement is installed, the selected target reticle will light up in red when the target is in the player’s sights. This is equivalent to the <code>reticle_target_sensitive</code> key in [[hud.plist|HUD plists]].

=== <code>scoopOverride</code> ===
'''scoopOverride''' : Boolean (read/write)
If <code>true</code>, and the player has a fuel scoop, the fuel scoop effect will run even if not close to a sun or scooping cargo.

=== <code>specialCargo</code> ===
'''specialCargo''' : String (read-only)
The special cargo the player is carrying, if any; otherwise <code>null</code>.

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

=== <code>targetSystem</code> ===
'''targetSystem''' : Integer (read-only)
The ID of the selected hyperspace target system.

=== <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>weaponsOnline</code> ===
'''weaponsOnline''' : Boolean (read-only)
Returns the weapon safety status. Player can toggle the status with the underscore-key.

== Methods ==
=== <code>addPassenger</code> ===
function '''addPassenger'''(name : String, start : Number, destination : Number, arrivalTime : Number, fee : 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 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 inital payment is made.

=== <code>awardContract</code> ===
function '''awardContract'''(quantity : Number, commodity : String, start : Number, destination : Number, arrivalTime : Number, fee : 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 buy the cargo at the local market price. Using this method, no inital payment is made.

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

=== <code>removePassenger</code> ===
function '''removePassenger'''(name : String)
Remove a named passenger.

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

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

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Player

2011-12-16T21:39:53Z

Ahruman: Removed Oolite 1.75 change notes.

'''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>cargoSpaceAvailable</code> ===
'''cargoSpaceAvailable''' : Number (read-only integer)
The ship’s available cargo space, in tons.

=== <code>cargoSpaceUsed</code> ===
'''cargoSpaceUsed''' : Number (read-only integer)
The ship’s current cargo, in tons.

=== <code>contractReputation</code> ===
'''contractReputation''' : Number (read-only integer)
The player’s cargo contract reputation, ranging from -7 to +7. Reputation is based on fulfilled and unfulfilled contracts. Both individually ranging from 0 till 7. Both good and bad value erode away in time towards 0. All individually values below 7 are seen as '''unknown''' reputation. This unknown part is randomised based on the market situation.

'''See also:''' <code>[[#decreaseContractReputation|decreaseContractReputation()]]</code>, <code>[[#increaseContractReputation|increaseContractReputation()]]</code>, <code>[[#passengerReputation|passengerReputation]]</code>

=== <code>credits</code> ===
'''credits''' : Number (read/write, integer)
The amount of money the player has.

=== <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>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)
The name of the player’s character (e.g., “Jameson”).

=== <code>passengerReputation</code> ===
'''passengerReputation''' : Number (read-only integer)
The player’s passenger contract reputation, ranging from -7 to +7. Reputation is based on fulfilled and unfulfilled contracts. Both individually ranging from 0 till 7. Both good and bad value erode away in time towards 0. All individually values below 7 are seen as '''unknown''' reputation. This unknown part is randomised based on the market situation.

'''See also:''' <code>[[#contractReputation|contractReputation()]]</code>, <code>[[#decreasePassengerReputation|decreasePassengerReputation()]]</code>, <code>[[#increasePassengerReputation|increasePassengerReputation()]]</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>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>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. This is the report shown immediately after docking. Oolite is putting its own stuff on the list immediately after shipWillDockAtStation() so it will be a good moment to add the messages at that moment when you know what station will be docked. At shipDockedWithStation() it will be to late as the report is already being shown at that moment. Messages added will be on the list above oolites own arrival messages. Messages added on the list other than during shipWillDockAtStation() will trigged the report screen when using the F5 screen during flight. This will be fixed in future versions but for now, only add them at shipWillDockAtStation().

=== <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: <code>player.commsMessage("Hello, cruel universe.", 6)</code> 
NB. This commsMessage() is a property of "player". "player.ship" has also a commsMessage() property, but that belongs to ship and has a different second parameter. (see [[Oolite_JavaScript_Reference:_Ship|Oolite JavaScript Reference: Ship]])

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

=== <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>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>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>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 – for example, from the <code>escapePodSequenceOver()</code> event handler. It determines where the player will end up. <code>destination</code> may be any carrier/station entity, or 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>, the player will die of life support failure. (<code>null</code> is the default in interstellar space.)

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Planet

2011-12-16T21:39:43Z

Ahruman: Removed Oolite 1.75 change notes.

'''Prototype:''' <code>[[Oolite/Development/Scripting/Class/Entity|Entity]]</code> 
'''Subtypes:''' none

The '''<code>Planet</code>''' class is an <code>[[Oolite/Development/Scripting/Class/Entity|Entity]]</code> representing a planet or moon. A <code>Planet</code> has all the properties and methods of a <code>Entity</code>, and several others.

== Properties ==
=== <code>hasAtmosphere</code> ===
'''hasAtmosphere''' : Boolean (read-only)
<code>true</code> if the entity has an atmosphere, <code>false</code> otherwise. Planets created with the <code>System.[[Oolite/Development/Scripting/Class/System#addMoon|addMoon]]()</code> method (or corresponding legacy scripting method) have no atmosphere, other planets do.

=== <code>isMainPlanet</code> ===
'''isMainPlanet''' : Boolean (read-only)
<code>true</code> if the entity is the main planet of the current system, <code>false</code> otherwise.

=== <code>radius</code> ===
'''radius''' : Number (read-only)
The equatorial radius of the planet, in metres.

For reference: radii of main planets generated by Oolite vary between 28160 and 69110 meters. This value is shown on the planet information screen as: 2816 km to 6911 km. (Note the discrepancy of a factor 100.)

=== <code>rotationalVelocity</code> ===
'''rotationalVelocity''' : Number (read/write)
The rotation speed of a planet. A value of x means: x/Math.PI rotations per second. The main planet default value is pseudorandom and varies between 0.0 until 0.01

=== <code>texture</code> ===
'''texture''' : String (read/write)

The name of the texture file (diffuse map) used by the planet. This may only be assigned to during the <code>shipWillExitWitchspace</code> and <code>shipWillLaunchFromStation</code> events.

== Non-standard Properties ==
''These are not part of the official object model, but are used in various OXPs by the authors to allow manipulation of the OXP by other scripts and expansions. '''Important:''' the use of custom properties without a unique OXP-specific prefix is '''strongly discouraged''' and may cause conflicts with future versions of Oolite.''

=== <code>solarGasGiant</code> ===
'''solarGasGiant''' : Boolean (read/write)
<code>true</code> if the entity is a gas giant and should therefore prevent attempts to land on the planet's surface, <code>false</code> otherwise. Created for the Solar System OXP and used by the [[Planetfall OXP]].

=== <code>PFNoLand</code> and <code>PFNoLandQuiet</code> ===
'''PFNoLand''' : Boolean (read/write)
'''PFNoLandQuiet''' : Boolean (read/write)
<code>true</code> if landing will be prevented on the planet's surface (with and without a warning message), <code>false</code> otherwise. Created and used by the [[Planetfall OXP]] from version 1.40 onwards.

=== <code>isGasGiant</code> ===
'''isGasGiant''' : Boolean (read/write)
<code>true</code> if the entity is a gas giant, <code>false</code> otherwise. Created and used by the [[System Redux 2 OXP]].

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Mission

2011-12-16T21:39:33Z

Ahruman: Removed Oolite 1.75 change notes.

'''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]].

== Methods ==

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

Appends text to the currently running mission screen.

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

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

=== <code>runScreen</code> ===
'''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>model : String</code> (Role of a ship that will be shown as rotating ship)
* <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>choicesKey : String</code> (Key in [[missiontext.plist]])

Some of these are mutually exclusive; for instance, “title” overrides “titleKey”. See [[Oolite JavaScript Reference: Global#setScreenBackground|setScreenBackground()]] for a discussion of ''guiTextureSpecifier''.

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.

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

One warning: <code>runScreen()</code> will overwrite any existing missionscreen. The only safe place is using it inside a <code>missionScreenOpportunity</code> handler, 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.

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

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

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

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

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

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

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Global

2011-12-16T21:39:10Z

Ahruman: Removed Oolite 1.75 change notes.

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 ot 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>. Currently, the other possible values are <code>"GUI_SCREEN_INTRO1"</code>, <code>"GUI_SCREEN_INTRO2"</code>, <code>"GUI_SCREEN_STATUS"</code>, <code>"GUI_SCREEN_MANIFEST"</code>, <code>"GUI_SCREEN_EQUIP_SHIP"</code>, <code>"GUI_SCREEN_SHIPYARD"</code>, <code>"GUI_SCREEN_LONG_RANGE_CHART"</code>, <code>"GUI_SCREEN_SHORT_RANGE_CHART"</code>, <code>"GUI_SCREEN_SYSTEM_DATA"</code>, <code>"GUI_SCREEN_MARKET"</code>, <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>. This list may change in future.

=== <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

Mission variables can also be used in legacy scripts and in [[Misc_plists|descriptions.plist]] string expansions, by prefixing the name with “mission_”. 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 were the loop "<code>for ( var i= 0 ; i < 1000 ; i++){}</code>" takes just 0.62 msec, will the same loop with missionVarriables <code>for (missionVariables.i= 0 ; missionVariables.i < 1000 ; missionVariables.i++){}</code> consume 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>worldScripts</code> ===
'''worldScripts''' : Object (read-only)
A list of world script objects.

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

=== <code>displayNameForCommodity</code> ===
function '''displayNameForCommodity'''(commodityName : 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 [[Methods#Communications|Communications]].
When local key/value pairs are provided, they take precedence over any other values.

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

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

=== <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 can be used to specify which type of message is written to the log.

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

=== <code>randomInhabitantsDescription</code> ===
function '''randomInhabitantsDescription'''([plural : boolean, default true])
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(true) +".");

=== <code>randomName</code> ===
function '''randomName'''()
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>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: 512 });

=== <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]) : Bool
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: EquipmentInfo

2011-12-16T21:38:30Z

Ahruman: Removed Oolite 1.75 change notes.

'''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>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>description</code> ===
'''description''' : String (read-only)
A short description of the equipment, as seen on the Ship Outfitting screen.

=== <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|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|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 "EQ_MISSILE".

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

=== <code>isAvailableToNPCs</code> ===
'''isAvailableToNPCs''' : Boolean (read-only)
<code>true</code> if the equipment type can be used by non-player ships (<code>available_to_player</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)
<code>true</code> for _MISSILE and _MINE equipment types.

=== <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 ship info 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 "Missile".

=== <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>requiredCargoSpace</code> ===
'''requiredCargoSpace''' : Number (read-only nonnegative integer)

=== <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)
True 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)
True 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]]

Oolite JavaScript Reference: Entity

2011-12-16T21:38:00Z

Ahruman: Removed Oolite 1.75 change notes.

'''Prototype:''' <code>Object</code> 
'''Subtypes:''' <code>[[Oolite JavaScript Reference: Planet|Planet]]</code>, <code>[[Oolite JavaScript Reference: Ship|Ship]]</code>, <code>[[Oolite JavaScript Reference: Sun|Sun]]</code>

The '''<code>Entity</code>''' class represents an object in the game universe. <code>[[Oolite JavaScript Reference: Ship|Ship]]</code>s, <code>[[Oolite JavaScript Reference: Station|Station]]</code>s, <code>[[Oolite JavaScript Reference: Planet|Planet]]</code>s and <code>[[Oolite JavaScript Reference: Sun|Sun]]</code>s are types of entity. Note that these more specific types have additional properties and methods.

=== Stale References ===
When an entity dies or is otherwise removed from the game universe (for instance, because player jumped from the system), existing <code>Entity</code> variables referring to the entity become invalid; all their properties become <code>undefined</code>, and their methods do nothing. In addition to the undefined properties, this can be detected with the <code>[[#isValid|isValid]]</code> property.

== Properties ==
=== <code>collisionRadius</code> ===
'''collisionRadius''' : Number (read-only)
The radius of the entity, in game meters. This is the radius of the spherical entity representation Oolite calculates with for non-colliding entities.

=== <code>distanceTravelled</code> ===
'''distanceTravelled''' : Number (read-only)
The distance the entity has travelled since being spawned, in game meters.

=== <code>energy</code> ===
'''energy''' : Number (read/write)
The entity’s total energy; ranges from 0 to <code>[[#maxEnergy|maxEnergy]]</code>.

=== <code>heading</code> ===
'''heading''' : [[Oolite JavaScript Reference: Vector|Vector]] (read-only)
The heading of the entity. This is equivalent to <code>[[#orientation|orientation]]</code>, but ignoring the axial twist component (roll in the case of a ship).

<code>entity.heading()</code> is equivalent to <code>entity.[[#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#forwardVector|forwardVector]]()</code>.

=== <code>mass</code> ===
'''mass''' : Number (read-only)
The mass of the entity. Currently, this is directly proportional to the volume.

=== <code>maxEnergy</code> ===
'''maxEnergy''' : Number (read-only)
The highest permissible value of <code>[[#energy|energy]]</code>.

=== <code>orientation</code> ===
'''orientation''' : [[Oolite JavaScript Reference: Quaternion|Quaternion]] (read/write)

=== <code>owner</code> ===
'''owner''' : Entity (read-only)
The entity which owns this one. In the case of a subentity, the entity to which it is attached. In the case of a defense ship, the station it belongs to. In the case of a missile, the ship that launched it. There may be other uses.

=== <code>position</code> ===
'''position''' : [[Oolite JavaScript Reference: Vector|Vector]] (read/write)

=== <code>scanClass</code> ===
'''scanClass''' : String (read-only)
The current scan class of the entity (such as “CLASS_NEUTRAL” and “CLASS_CARGO”).

=== <code>spawnTime</code> ===
'''spawnTime''' : Number (read-only)
The time at which the entity came into existence.

=== <code>status</code> ===
'''status''' : String (read-only)
The current status of the entity (such as “STATUS_IN_FLIGHT” and “STATUS_BEING_SCOOPED”).

=== <code>isPlanet</code> ===
'''isPlanet''' : Boolean (read-only)
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Planet|Planet]], <code>false</code> otherwise.

=== <code>isPlayer</code> ===
'''isPlayer''' : Boolean (read-only)
<code>true</code> if the entity is the [[Oolite JavaScript Reference: PlayerShip|player ship]], <code>false</code> otherwise.

=== <code>isShip</code> ===
'''isShip''' : Boolean (read-only)
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Ship|Ship]], <code>false</code> otherwise.

=== <code>isStation</code> ===
'''isStation''' : Boolean (read-only)
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Station|Station]], <code>false</code> otherwise.

=== <code>isSubEntity</code> ===
'''isSubEntity''' : Boolean (read-only)
<code>true</code> if the entity is a subentity, <code>false</code> otherwise. A subentity’s owner can be acquired through the <code>[[#owner|owner]]</code> property.

=== <code>isSun</code> ===
'''isSun''' : Boolean (read-only)
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Sun|Sun]], <code>false</code> otherwise.

=== <code>isValid</code> ===
'''isValid''' : Boolean (read-only)
<code>true</code> if the entity is a valid entity variable, <code>false</code> if it is [[#Stale References|stale]].

[[Category:Oolite JavaScript Reference]]

Debug OXP

2011-12-16T21:23:14Z

Ahruman: Updated download link for 1.76.

'''Debug.oxp''' is a special OXP that enables JavaScript console support in Oolite (1.70 and later). It also adds a menu with various debug facilities under Mac OS X.

=== Downloads ===
[http://jens.ayton.se/oolite/files/debug-oxp-1.76.zip Debug OXP for Oolite 1.76]

== External JavaScript console support ==
On all platforms, installing Debug.oxp enables support for external console applications using the [[Oolite debug console TCP protocol]]. By default, it will attempt to connect to a console running on the same computer, but this can be changed by specifying a different <code>console-host</code> (and, optionally, <code>console-port</code>) in ''debugConfig.plist''. For external console support on the same computer under Mac OS X, <code>console-host</code> must be explicitly set to “127.0.0.1”; if this is not done, the [[#Integrated JavaScript console|integrated JavaScript console]] will be used instead. For information on using a console (integrated or external), see [[#Using the JavaScript console|Using the JavaScript console]] below.

'''Note:''' A cross-platform, python based, external console application is available in the [http://developer.berlios.de/project/showfiles.php?group_id=3577 Berlios Oolite files] area.

It contains a precompiled console for windows based computers, and the original python based console for Linux and Posix compliant computers.

On Debian or Ubuntu Linux you will need python 2.6.x installed and (at least) the packages <code>blt python-tk tk8.5</code> (or the equivalents in other distros.)

== Mac OS X-specific features ==
Under Mac OS X, the Debug OXP provides a menu with various debugging options and an integrated JavaScript console, as well as enabling external console support as on all platforms.

=== Debug menu ===
[[Image:Oolite-debug-menu.png|494px]]

The Debug menu provides options to
* Show the Oolite run log in the standard Console application.
* Enable or disable various classes of log message at runtime (like editing ''logcontrol.plist'', without the need to restart Oolite).
* Enable various testing features, such as drawing of bounding boxes.
* Show the JavaScript console, and specify when it should be shown automatically. (This may not have any effect with external consoles, depending on the external console implementation.)
* Create a ship of any role near the main station (equivalent to the <code>:spawn</code> [[#Macros|macro]]).
Note: some of these features are implemented by sending JavaScript messages to the [[#The console script|console script]]. If the script has been modified, some features may not work properly.

The Log Message Classes submenu can be modified by editing ''debugLogMessageClassesMenu.plist'', found inside the OXP. This is merged from Config directories in the usual fashion.

=== Integrated JavaScript console ===
[[Image:Oolite debug protocol example 1.png|594px]]

The integrated JavaScript console provides a window within Oolite which acts as a [[#Using the JavaScript console|JavaScript console]]. It can be shown using the Show JavaScript Console command in the Debug menu, unless external console mode has been enabled by setting <code>console-host</code> in ''debugConfig.plist''.

The integrated console has a 100-line memory. To see previous commands, press ⇞ (Page Up) or ⌥↑ (Option-Up Arrow). You can go the other way in the obvious manner.

== Using the JavaScript console ==
The JavaScript console, whether integrated or external, provides a powerful mechanism for interactively manipulating the game world. It can be used to issue simple commands, like <code>player.awardEquipment("EQ_FUEL_INJECTION")</code>. It can be used to inspect properties of entities in the game world. And it can be used to develop scripts, by rewriting and testing methods of live ship scripts and world scripts.

=== Macros ===
Macros are a special type of command prefixed with a colon. Instead of being interpreted as a JavaScript command, a macro is looked up in a dictionary, and the result is used as the “real” command. For instance, if you enter the command <code>:listM</code> (short for “list macros”), the macro dictionary is queried for the string “listM”, and (by default) the code <code>for (let prop in macros) { ConsoleMessage('macro-list', ':' + prop) }</code> is found and executed. This code is called the ''expansion'' of the macro. The result is a list of macros being printed:
:clr
:clear
:spawn
:bgColor
:showM
:rmFgColor
::
:d
:ds
:listM
:setM
:delM
:fgColor
:rmBgColor
:resetM

As you can see in the example, To see the expansion of a macro without executing it, use <code>:showM</code>:
> :showM :delM
:delM = deleteMacro(PARAM)

When a macro with the word <code>PARAM</code> is executed, <code>PARAM</code> is replaced with any text following the macro name, surrounded in quotation marks. This is how <code>:showM</code> functions, for example; the string “:showM :delM” is expanded to “showMacro(":delM")”, causing the JavaScript function <code>showMacro()</code>, which is part of the [[#The console script|console script]], to be called. You can see the implementation of <code>showMacro()</code> by entering <code>showMacro</code> – without any parentheses – into the console.

An initial set of macros is loaded from ''debugConfig.plist''. If you edit any macros, using <code>:setM</code> or <code>:delM</code>, all macros are saved in Oolite’s preferences from that point forwards. This means that you don’t have to re-enter any macros you write with <code>:setM</code> after restarting Oolite.

The following example creates a simple :msg macro:
> :setM msg ConsoleMessage(' ',PARAM)
If you then type:
> :msg Hello World
The macro will be expanded, and you'll see “Hello World” on the console. However, macros are not functions, so you cannot use macros in the middle of javascript, or as part of another macro.

=== The console script ===
While an external or integrated console is required to provide a means of user interaction, most of the actual behaviour of the console is implemented in JavaScript, in a script called ''oolite-debug-console.js''. Input typed into the console is passed to the console script, which then generates output. The console script is also informed of log messages and JavaScript errors, and provides a global function, <code>ConsoleMessage(colorCode: String, message: String)</code>, to write messages to the console using its background colour support. Lastly, the console script implements the entire macro system.

This means that the console’s behaviour can be extensively customized, for instance, by replacing the macro system with something more powerful. There are two basic approaches to doing this:
* Creating a custom script (or a copy) with the same name, in an OXP which loads later than Debug.oxp (e.g., one which has a name which comes later in alphabetical order).
* Using a normal world script, and changing the console script object at startup.
The latter approach has the advantage that it can continue to work with future versions of the console script, and multiple patches can coexist. For example, a modification to supplement the macro system with a better one might look as follows:
this.name = "my-super-console-macros"

this.startUp = function()
{
// Ensure debug console is installed
if (!debugConsole) return

// Save original implementation of consolePerformJSCommand
// Note the prefix, used to ensure uniqueness. If several scripts patch
// the same method, it's important that they use different names.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand = debugConsole.consolePerformJSCommand

// Replace debugConsole.consolePerformJSCommand with custom function
debugConsole.consolePerformJSCommand = function(command)
{
// Note that in this function "this" will refer to debugconsole, not
// my-super-console-macros, since the function will be called as a
// method of debugConsole.

// Strip leading spaces, same code as original function.
while (command.charAt(0) == " ")
{
command = command.substring(1)
}

if (command.charAt(0) == "!")
{
// Super macro call detected.
// Insert super macro system here.
}
else
{
// Otherwise, call through to original method.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand(command)
}
}
}
This same patching technique, incidentally, can be used to modify scripts at runtime, either from the console or from other scripts.

{{misc-OXP}}
[[Category:Oolite utilities]]

Running Oolite-Mac

2011-07-21T12:54:59Z

Ahruman: /* Building earlier versions */ Fixed horrible URL

==Overview==
Oolite was originally developed for OS X, and as such, OS X is Oolite's home operating system. The OS X version can be considered the reference version for all other ports. It has some specific Mac OS X only support such as speech synthesis, iTunes integration and Growl integration. Joysticks are not directly supported - however, there are programs that convert joystick inputs into mouse and keyboard inputs, and these programs are reported to work well with Oolite.

==Getting and installing the game==
You can get the most recent release of the game from [http://developer.berlios.de/project/showfiles.php?group_id=3577 BerliOS].

Installation is the standard method of dragging the Oolite folder to your Applications or Games folder.

===Installing OXPs (add ons)===
In the Oolite folder that you dragged from the disk image, you will find an Oolite application and an AddOns folder. Place OXPs in the AddOns folder, and they will be loaded the next time you start the game.

==Building Oolite from source==

=== Development Environment (Xcode) ===
To start, you will need Mac OS X 10.5 or later and Xcode tools 3.2 or later from the [http://connect.apple.com/ Apple Developer Connection] or your Mac OS install DVD. You will need an Apple Developer Connection membership to obtain download Xcode; however, the free online membership is sufficient. You can register [http://developer.apple.com/programs/register/ here]. You will also need to ensure you have installed the Mac OS X 10.4 Universal SDK, which is available through the Xcode Tools installer. Lastly, you will require the Subversion version control tool; an up-to-date binary is available [http://downloads.open.collab.net/binaries.html here].

The Oolite projects have not been updated for Xcode 4, and won’t be (in trunk) before the next stable release.

=== Getting the Source ===

The source code and data files are available from [http://developer.berlios.de/projects/oolite-linux/ the oolite-linux BerliOS project]. Don't be confused by the name 'oolite-linux'; at one point there were three separate repositories for Oolite, but the Linux one was where they ended up being merged together. The SVN url for 1.65 is:

svn://svn.berlios.de/oolite-linux/tags/v165-final

1.74.2 is:
svn://svn.berlios.de/oolite-linux/tags/1.74.2

You can also get the latest work-in-progress from:

svn://svn.berlios.de/oolite-linux/trunk

To download the source with Subversion, the quickest way to do it is to open a Terminal window, and run the following command:

svn checkout svn://svn.berlios.de/oolite-linux/trunk

If you have a BerliOS account and are a project member, you can get it with:

svn checkout svn+ssh://''accountname''@svn.berlios.de/svnroot/repos/oolite-linux/trunk

Developers should also checkout the relevant maintenance branch:

svn checkout svn+ssh://''accountname''@svn.berlios.de/svnroot/repos/oolite-linux/branches/1.74-maintenance/

=== Building Oolite ===
Oolite must be built using Xcode 3.2; Xcode 4 is not supported. Multiple versions of Xcode can be installed side-by-side, but installing Xcode 3.2.6 on OS X Lion is currently problematic. See [http://aegidian.org/bb/viewtopic.php?p=148396#p148396 this forum post] for more information.

For a trunk build (as of revision 4026), just open Oolite.xcodeproj and hit Build. Dependencies will be downloaded automatically (in the deps folder inside the Oolite repository). The default target is Build All, which includes the Debug OXP, joystick support and a dock tile plug-in. The last can only be built under Snow Leopard or later; to build under Leopard you must switch to the Oolite project, or remove the dependency on Oolite-docktile.

==== Building earlier versions ====
For 1.74.x and earlier versions, you must download the source release of [http://libpng.org/pub/png/libpng.html libpng]. This will decompress as a folder called “libpng-1.4.5” or similar. Rename it to “libpng” and move it to deps/Cross-platforms-deps in the Oolite repository. The trunk project now does this automatically. To build the “Build All” target, which includes the Debug OXP, you must install the [http://www.brockerhoff.net/src/rbs.html RBSplitView Interface Builder plug-in]. (To install it, simply put it somewhere tidy and open it; Interface Builder should load and register the plug-in.) '''Important:''' due to an unfortunate change between versions, you must use the 1.1.4 version of the RBSplitView IB plug-in, ''or'' use 1.2 but change its bundle identifier from <code>net.brockerhoff.RB'''S'''plitView.IBPlugin</code> to <code>net.brockerhoff.RB'''s'''plitView.IBPlugin</code>.

These steps do not need to be repeated after updating the repository using the <code>svn update</code> command.

Versions prior to r4584 (1.75.4) will not build under OS X Lion. To make them build, you will need to apply [http://svn.berlios.de/wsvn/oolite-linux?op=comp&compare%5B%5D=%2Ftrunk@4583&compare%5B%5D=%2Ftrunk%2F@4584 these changes] and set the “Header Search Paths” setting of the Oolite target to <code>$(SDKROOT)/usr/include/libkern/</code> for all configurations.

==== Build products ====
Building the Build All target (in trunk) will result in the following being created in the build results folder: AddOns, Debug.oxp, include (with subfolders js, ogg and vorbis), libjs_for_oolite.a, libnspr4_for_oolite.a, libogg_for_oolite.a, libpng_for_oolite.a, Oolite.app, Oolite Leopard Support.bundle, Oolite.mdimporter and Oolite.docktileplugin. AddOns contains a copy of Debug.oxp. Oolite.app contains a copy of Oolite Leopard Support.bundle, Oolite.mdimporter and Oolite.docktileplugin, and static libraries (.a files) are linked into the Oolite executable. Everything except Oolite.app and AddOns can be considered side effects of the build process.

[[Category:Oolite]] [[Category:Factual]]

Running Oolite-Mac

2011-07-21T12:50:55Z

Ahruman: /* Building Oolite */ Updated for Lion and added some subheadings.

==Overview==
Oolite was originally developed for OS X, and as such, OS X is Oolite's home operating system. The OS X version can be considered the reference version for all other ports. It has some specific Mac OS X only support such as speech synthesis, iTunes integration and Growl integration. Joysticks are not directly supported - however, there are programs that convert joystick inputs into mouse and keyboard inputs, and these programs are reported to work well with Oolite.

==Getting and installing the game==
You can get the most recent release of the game from [http://developer.berlios.de/project/showfiles.php?group_id=3577 BerliOS].

Installation is the standard method of dragging the Oolite folder to your Applications or Games folder.

===Installing OXPs (add ons)===
In the Oolite folder that you dragged from the disk image, you will find an Oolite application and an AddOns folder. Place OXPs in the AddOns folder, and they will be loaded the next time you start the game.

==Building Oolite from source==

=== Development Environment (Xcode) ===
To start, you will need Mac OS X 10.5 or later and Xcode tools 3.2 or later from the [http://connect.apple.com/ Apple Developer Connection] or your Mac OS install DVD. You will need an Apple Developer Connection membership to obtain download Xcode; however, the free online membership is sufficient. You can register [http://developer.apple.com/programs/register/ here]. You will also need to ensure you have installed the Mac OS X 10.4 Universal SDK, which is available through the Xcode Tools installer. Lastly, you will require the Subversion version control tool; an up-to-date binary is available [http://downloads.open.collab.net/binaries.html here].

The Oolite projects have not been updated for Xcode 4, and won’t be (in trunk) before the next stable release.

=== Getting the Source ===

The source code and data files are available from [http://developer.berlios.de/projects/oolite-linux/ the oolite-linux BerliOS project]. Don't be confused by the name 'oolite-linux'; at one point there were three separate repositories for Oolite, but the Linux one was where they ended up being merged together. The SVN url for 1.65 is:

svn://svn.berlios.de/oolite-linux/tags/v165-final

1.74.2 is:
svn://svn.berlios.de/oolite-linux/tags/1.74.2

You can also get the latest work-in-progress from:

svn://svn.berlios.de/oolite-linux/trunk

To download the source with Subversion, the quickest way to do it is to open a Terminal window, and run the following command:

svn checkout svn://svn.berlios.de/oolite-linux/trunk

If you have a BerliOS account and are a project member, you can get it with:

svn checkout svn+ssh://''accountname''@svn.berlios.de/svnroot/repos/oolite-linux/trunk

Developers should also checkout the relevant maintenance branch:

svn checkout svn+ssh://''accountname''@svn.berlios.de/svnroot/repos/oolite-linux/branches/1.74-maintenance/

=== Building Oolite ===
Oolite must be built using Xcode 3.2; Xcode 4 is not supported. Multiple versions of Xcode can be installed side-by-side, but installing Xcode 3.2.6 on OS X Lion is currently problematic. See [http://aegidian.org/bb/viewtopic.php?p=148396#p148396 this forum post] for more information.

For a trunk build (as of revision 4026), just open Oolite.xcodeproj and hit Build. Dependencies will be downloaded automatically (in the deps folder inside the Oolite repository). The default target is Build All, which includes the Debug OXP, joystick support and a dock tile plug-in. The last can only be built under Snow Leopard or later; to build under Leopard you must switch to the Oolite project, or remove the dependency on Oolite-docktile.

==== Building earlier versions ====
For 1.74.x and earlier versions, you must download the source release of [http://libpng.org/pub/png/libpng.html libpng]. This will decompress as a folder called “libpng-1.4.5” or similar. Rename it to “libpng” and move it to deps/Cross-platforms-deps in the Oolite repository. The trunk project now does this automatically. To build the “Build All” target, which includes the Debug OXP, you must install the [http://www.brockerhoff.net/src/rbs.html RBSplitView Interface Builder plug-in]. (To install it, simply put it somewhere tidy and open it; Interface Builder should load and register the plug-in.) '''Important:''' due to an unfortunate change between versions, you must use the 1.1.4 version of the RBSplitView IB plug-in, ''or'' use 1.2 but change its bundle identifier from <code>net.brockerhoff.RB'''S'''plitView.IBPlugin</code> to <code>net.brockerhoff.RB'''s'''plitView.IBPlugin</code>.

These steps do not need to be repeated after updating the repository using the <code>svn update</code> command.

Versions prior to r4584 (1.75.4) will not build under OS X Lion. To make them build, you will need to apply [http://svn.berlios.de/wsvn/oolite-linux?op=comp&compare[]=%2Ftrunk@4583&compare[]=%2Ftrunk%2F@4584 these changes] and set the “Header Search Paths” setting of the Oolite target to <code>$(SDKROOT)/usr/include/libkern/</code> for all configurations.

==== Build products ====
Building the Build All target (in trunk) will result in the following being created in the build results folder: AddOns, Debug.oxp, include (with subfolders js, ogg and vorbis), libjs_for_oolite.a, libnspr4_for_oolite.a, libogg_for_oolite.a, libpng_for_oolite.a, Oolite.app, Oolite Leopard Support.bundle, Oolite.mdimporter and Oolite.docktileplugin. AddOns contains a copy of Debug.oxp. Oolite.app contains a copy of Oolite Leopard Support.bundle, Oolite.mdimporter and Oolite.docktileplugin, and static libraries (.a files) are linked into the Oolite executable. Everything except Oolite.app and AddOns can be considered side effects of the build process.

[[Category:Oolite]] [[Category:Factual]]

Oolite JavaScript Reference: Ship

2011-07-16T12:28:56Z

Ahruman: /* Properties */ Moving cargoSpaceAvailable and cargoSpaceUsed from Ship to PlayerShip. (Bug #18243)

'''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 a <code>Entity</code>, and several others.

<code>[[Oolite JavaScript Reference: Station|Station]]</code>s and the <code>[[Oolite JavaScript Reference: PlayerShip|PlayerShip]]</code> are types of ship. Note that these more specific types have additional properties and methods.

== Properties ==
=== <code>aftWeapon</code> ===
'''aftWeapon''' : EquipmentType (read-only)
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 AI.

'''See also:''' <code>[[#AIState|AIState]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>

=== <code>AIState</code> ===
'''AIState''' : String (read/write, read-only for player)
The ship’s AI’s current state.

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#reactToAIMessage|reactToAIMessage()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code>

=== <code>beaconCode</code> ===
'''beaconCode''' : String (read-only)
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>.

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

=== <code>bounty</code> ===
'''bounty''' : Number (read/write integer)
The bounty on the ship. In the case of the player, it is halved at each witchspace jump. 
It is actually the legal status of the ship that is shown here and not the bounty. For all ships both are the same but for anything with scan class Thargoid the legal status is only based on the ships mass and has no relation to its defined bounty.

=== <code>cargoSpaceCapacity</code> ===
'''cargoSpaceCapacity''' : Number (read-only integer)
The ship’s cargo capacity, in tons.

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

=== <code>cloakAutomatic</code> ===
{{oolite-prop-added|1.75|beta}}
'''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>cruiseSpeed</code> ===
{{Oolite-prop-added|1.75|beta}}
'''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>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>displayName</code> ===
'''displayName''' : String (read/write, read-only for player)
The name of the ship as seen by the player. By default it is the same as <code>[[#name|name]]</code>.

=== <code>entityPersonality</code> ===
'''entityPersonality''' : Number (read-only integer)
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]].

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

=== <code>escorts</code> ===
'''escorts''' : Array (read-only array of [[Oolite JavaScript Reference: Entity|Entity]]s)
The ship’s deployed escorts.

=== <code>forwardWeapon</code> ===
'''forwardWeapon''' : EquipmentType (read-only)
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>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> ===
{{oolite-prop-added|1.75|beta}}
'''hasHyperspaceMotor''' : Boolean (read-only)
True 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.

=== <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 "boulder in its roleset)

=== <code>isCargo</code> ===
'''isCargo''' : Boolean (read-only)
<code>true</code> if the ship is cargo (i.e., has scan_class CLASS_CARGO 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 * 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>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>isJamming</code> ===
'''isJamming''' : Boolean (read-only)
<code>true</code> if the ship has a military scanner jammer which is currently active <code>false</code> otherwise.

=== <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> ===
{{Oolite-prop-added|1.75}}
'''isPiloted''' : Boolean (read-only)
<code>true</code> if the ship has a pilot on board, <code>false</code> otherwise. Generally have ships, station and escape pods pilots and have cargo, rocks, missiles or buoys no pilots.

=== <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: CLASS_ROCK)

=== <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>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>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 false in their ''shipdata.plist'' declarations.

=== <code>maxSpeed</code> ===
'''maxSpeed''' : Number (read-only)
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)
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>missileCapacity</code> ===
'''missileCapacity''' : Number (read-only integer)
The maximum number of missiles the ship can carry.

=== <code>missileLoadTime</code> ===
{{Oolite-prop-added|1.75|beta}}
'''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>passengerCapacity</code> ===
'''passengerCapacity''' : Number (read-only integer)
The ship’s maximum passenger capacity.

=== <code>passengerCount</code> ===
'''passengerCount''' : Number (read-only integer)
The ship’s current number of passengers.

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

=== <code>portWeapon</code> ===
'''portWeapon''' : EquipmentType (read-only)
The currently equipped forward weapon, or <code>null</code>. Currently, this is always <code>null</code> for non-player ships.

'''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 “pirate trader(0.5) escort”, and a ship of that type is spawned to be a trader, its <code>primaryRole</code> is <code>"trader"</code>, its <code>roles</code> is <code>["escort", "pirate", "trader"]</code> and its <code>roleWeights</code> is <code> { "escort":1, "pirate":1, "trader":0.5}</code>.

'''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> ===
'''roles''' : 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>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>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>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>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> ===
{{oolite-prop-added|1.75|beta}}
'''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>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 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. 
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 expclicit convert its content to a number by using parseInt(scriptInfo.myKey) or parseFloat(scriptInfo.myKey).

=== <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)
The currently equipped forward weapon, or <code>null</code>. Currently, this is always <code>null</code> for non-player ships.

'''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>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>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)
The ship’s thrust, ranging from 0 to <code>maxThrust</code>. This value determines how fast the ship accelerates or decelerates, specified in m/s².

'''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 true, 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>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).

== Methods ==
=== <code>abandonShip</code> ===
function '''abandonShip'''() : Boolean
Returns <code>true</code> when the ship has an escapepod. It will launch all escapeposd on board leaving the ship behind as a empty hulk. (scanClass = CLASS_CARGO). This command does nothing when no escape-pod is present. 
Pressence of an escapepod can be tested with: <code>equipmentStatus("EQ_ESCAPE_POD") == "EQUIPMENT_OK"</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>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.

=== <code>deployEscorts</code> ===
function '''deployEscorts'''()
Launch the ship’s escorts, if any.

=== <code>dockEscorts</code> ===
function '''dockEscorts'''()
Dock the ship’s deployed escorts, if any.

=== <code>dumpCargo</code> ===
function '''dumpCargo'''() : 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.

'''See also:''' <code>[[#dumpCargo|dumpCargo]]</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 scanClass of the ejected item will always be CLASS_CARGO.

'''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 scanClass of the ejected item will always be CLASS_CARGO.

'''See also:''' <code>[[#dumpCargo|dumpCargo]]</code>, <code>[[#ejectItem|ejectItem]]</code>

=== <code>equipmentStatus</code> ===
function '''equipmentStatus'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : String
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>.

'''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>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>hasRole</code> ===
function '''hasRole'''(role : String)
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>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>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 this.shipRemoved(suppressDeathEvent) event. By default it will also trigger a this.shipDied() event, unless <code>suppressDeathEvent</code> is true.

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

=== <code>removeEquipment</code> ===
function '''removeEquipment'''(equipmentType : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]])
Removes the given piece of equipment from the ship.
This function can also be used to remove missiles (and mines). If more than one missile of the same type is found on board, only one of them will be removed.

Example:
ship.removeEquipment("EQ_ECM");

=== <code>restoreSubEntities</code> ===
{{oolite-method-added|1.75|beta}}
function '''restoreSubEntities'''() : Boolean
Recreate all destroyed subentities of the ship. Returns <code>true</code> if any subentities were added.

=== <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> ===
{{Oolite-method-added|1.75}}
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.

'''See also:''' <code>[[#AI|AI]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>

=== <code>setCargo</code> ===
function '''setCargo'''(commodity : String [, count : Number]) : Boolean
Attempts to create <code>count</code> weight units of the commodity <code>commodity</code> for a cargo barrel. (Can not be used to set cargo for ships) When more units are defined than 1 ton, the count is reduced to one ton. It returns false when the selected commodity is unknown. If <code>count</code> is not specified, one will be assumed.

=== <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>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>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>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>updateEscortFormation</code> ===
{{oolite-method-added|1.75|beta}}
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.

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: Player

2011-07-16T12:28:33Z

Ahruman: /* Properties */ Moving cargoSpaceAvailable and cargoSpaceUsed from Ship to PlayerShip. (Bug #18243)

'''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>cargoSpaceAvailable</code> ===
'''cargoSpaceAvailable''' : Number (read-only integer)
The ship’s available cargo space, in tons.

=== <code>cargoSpaceUsed</code> ===
'''cargoSpaceUsed''' : Number (read-only integer)
The ship’s current cargo, in tons.

=== <code>contractReputation</code> ===
'''contractReputation''' : Number (read-only integer)
The player’s cargo contract reputation, ranging from -7 to +7. Reputation is based on fulfilled and unfulfilled contracts. Both individually ranging from 0 till 7. Both good and bad value erode away in time towards 0. All individually values below 7 are seen as '''unknown''' reputation. This unknown part is randomised based on the market situation.

'''See also:''' <code>[[#decreaseContractReputation|decreaseContractReputation()]]</code>, <code>[[#increaseContractReputation|increaseContractReputation()]]</code>, <code>[[#passengerReputation|passengerReputation]]</code>

=== <code>credits</code> ===
'''credits''' : Number (read/write, integer)
The amount of money the player has.

=== <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>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)
The name of the player’s character (e.g., “Jameson”).

=== <code>passengerReputation</code> ===
'''passengerReputation''' : Number (read-only integer)
The player’s passenger contract reputation, ranging from -7 to +7. Reputation is based on fulfilled and unfulfilled contracts. Both individually ranging from 0 till 7. Both good and bad value erode away in time towards 0. All individually values below 7 are seen as '''unknown''' reputation. This unknown part is randomised based on the market situation.

'''See also:''' <code>[[#contractReputation|contractReputation()]]</code>, <code>[[#decreasePassengerReputation|decreasePassengerReputation()]]</code>, <code>[[#increasePassengerReputation|increasePassengerReputation()]]</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>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>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. This is the report shown immediately after docking. Oolite is putting its own stuff on the list immediately after shipWillDockAtStation() so it will be a good moment to add the messages at that moment when you know what station will be docked. At shipDockedWithStation() it will be to late as the report is already being shown at that moment. Messages added will be on the list above oolites own arrival messages. Messages added on the list other than during shipWillDockAtStation() will trigged the report screen when using the F5 screen during flight. This will be fixed in future versions but for now, only add them at shipWillDockAtStation().

=== <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: <code>player.commsMessage("Hello, cruel universe.", 6)</code> 
NB. This commsMessage() is a property of "player". "player.ship" has also a commsMessage() property, but that belongs to ship and has a different second parameter. (see [[Oolite_JavaScript_Reference:_Ship|Oolite JavaScript Reference: Ship]])

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

=== <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>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>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>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> ===
{{oolite-method-added|1.75|beta}}
function '''setEscapePodDestination'''(destination)
This method can only be called after the player has launched an escape pod – for example, from the <code>escapePodSequenceOver()</code> event handler. It determines where the player will end up. <code>destination</code> may be any carrier/station entity, or 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>, the player will die of life support failure. (<code>null</code> is the default in interstellar space.)

[[Category:Oolite JavaScript Reference]]

Materials in Oolite

2011-07-14T19:58:03Z

Ahruman: /* Important concepts */ Linked specular map demo video

:This page applies to Oolite test releases.
Traditionally, the surface appearance of ships in Oolite has been defined entirely by textures specified in the ship’s model file and the ''[[#smooth|smooth]]'' attribute. Test release 1.67 added support for [[Shaders in Oolite|shaders]], and test release 1.69 expanded this to a more flexible '''material model'''. Under the new model, the texture file names in model files have been repurposed as '''material keys'''. A material key specifies an entry in the ship’s '''material dictionary''', specified in the ship’s ''[[shipdata.plist]]'' entry. For backwards compatibility, if no material of a given name is found, a material is generated using the material key as a diffuse texture name – providing the same functionality as previous versions of Oolite.

This page documents the material model as of Oolite test release 1.74.

== Important concepts ==
The following concepts are important in understanding how materials work and how they interact with lights.
* '''Colour''': Oolite uses a basic low dynamic range lighting model. Colours are considered to be lists of three values, representing red, green and blue colours, each ranging from 0 to 1. These are often encoded as integers ranging from 0 to 255 for technical reasons, but 0 to 1 is the true range of values. There may also be an associated ''alpha channel'', which is traditionally used for blending effects. In shaders, any colour channel can be used for any purpose, and textures often encode values that are not treated as colours.
* '''Fragment''': roughty speaking, an on-screen pixel. When objects are rendered, their geometry is used to generate a fragments, which are then coloured based on lighting and materials.
* '''Modulation''': multiplying two colours together, by channel. For instance, if the calculated light colour for a given fragment is pale yellow – [1, 1, 0.8] – and the corresponding part of the diffuse map is turquoise – [0.2, 0.8, 0.8] – the ''diffuse contribution'' is [0.2, 0.8, 0.64] (a greenish tint). In graphics programs, this blending mode is usually called ''Multiply''.
* '''Additive blending''': adding two colours together, by channel. In Oolite’s low dynamic range lighting model, the result is always clipped to the range 0..1. In graphics programs, this blending mode is usually called ''Lighten''.
* '''Normals''': All lighting calculations require a concept of the orientation of a surface relative to a light and, for reflections, relative to the camera. A surface oriented towards the light will be lighter than a surface oriented away from it. The ''normal'' for any given point on a surface is a vector pointing straight out, which for our purposes ''defines'' the concept of “straight out”. By default, Oolite models have constant normals across each face. By setting the <code>smooth</code> attribute in [[shipdata.plist]], normals are instead interpolated across each face, with each vertex having a normal that is a weighted average of surounding faces’ normals, and each point on a surface getting a weighted average of the normals at the corners of the face. Using ''smooth groups'', a model can be divided into regions which are smoothed but have sharp boundaries between them. As of Oolite 1.74, models can also include explicit per-vertex normals instead of having Oolite calculate them – most 3D modellers export this information. When using smoothing, it is important to understand that Oolite does not add any geometry,and will result in each vertex being lit as if it is locally flat. This is generally inappropriate for any sharp corner. If you set <code>smooth</code> on a basic cube, the result will be badly lit.
* '''Diffuse reflection''': light that is reflected evenly in all directions. A “dull” surface primarily reflects diffusely. Because the light is reflected evenly in all directions, the diffuse term is independent of the camera position; it is a function of the light and the surface normal. The standard diffuse reflection term is the cosine of the angle between the direction to the light and the normal, or zero if this is negative – this is known as the [http://en.wikipedia.org/wiki/Lambertian_reflectance Lambertian reflectance model]. This value is then modulated with the material’s diffuse colour and diffuse map.
* '''Specular reflection''': light that is reflected in a particular direction, producing a shiny effect. In real life, this is simply a mirror reflection which is generally darkened and blurred, leaving an enlarged, blurry reflection of bright light sources, with other objects being washed out so they aren’t noticeable. In Oolite, a simpler mathematical model called the [http://en.wikipedia.org/wiki/Blinn–Phong_shading_model Blinn-Phong shading model] is used. [http://www.youtube.com/watch?v=76jvMmV1ih0 This video] demonstrates the effects of specular lighting and specular mapping on the built-in scarred alloy model.

== The material dictionary ==
The '''material dictionary''' is actually specified as two separate dictionaries in the ''shipdata.plist'' entry. The first is called ''materials'', the second ''shaders''. If [[Shaders in Oolite|shader support]] is available and enabled, the entries in ''shaders'' are used in preference to those in ''materials''. Otherwise, ''shaders'' is ignored. The entries in the two dictionaries take exactly the same form, however; it is possible to specify a shader in the ''materials'' dictionary, and it will simply be ignored if shader support is not available. The ''materials'' and ''shaders'' dictionaries, merged together, are known as a ''material dictionary''.

=== Material specifiers ===
The material dictionary is a [[property list]] dictionary whose keys are ''material keys'' as defined below, and whose values are '''material specifiers''', which are either dictionaries or strings. When a string is used as a material specifier, it is equivalent to a dictionary with that string as the value for '''diffuse_map''', and no other properties. Currently-supported material specifier keys are listed here; “texture specifier” and similar are defined below.

Most of these keys have no effect when a custom shader is in effect.

When shaders are disabled or not available, emission and illumination maps are supported only if reduced detail is disabled and the graphics hardware supports multi-texturing. If '''emission_modulate_color''', '''illumination_map''', or '''emission_and_illumination_map''' are used, Oolite must combine them into a single emission map. It is generally preferable to do this in advance (by modulating the illumination map with the diffuse map and blending it additively with the emission map, after applying any colouring). This is more efficient when using shaders, too.

{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ General material attribues
! Name !! Type !! Description
|-
| '''ambient_color''' || [[#Colour specifiers|colour specifier]] || The ambient colour of the entity, that is, the colour reflected evenly in all directions by starlight. If there is a '''diffuse_map''', the '''ambient_color''' is modulated by the '''diffuse_map'''. Default: white (1.0, 1.0, 1.0, 1.0).
|-
| '''diffuse_color''' || [[#Colour specifiers|colour specifier]] || Overall diffuse colour of the entity; that is, the colour reflected in a “non-shiny” way on the sunlit side of the entity. If there is a '''diffuse_map''', the '''diffuse_color''' is modulated by the '''diffuse_map'''. Default: white (1.0, 1.0, 1.0, 1.0).
|-
| '''diffuse_map''' || [[#Texture specifiers|texture specifier]] || A texture specifying the basic colour of the material. This is a “normal” texture, the same as you get without a material dictionary. If not specified, the material key will be used. To specify no texture, use an empty string for '''diffuse_map'''. Ignored when using shaders.
|-
| '''emission_color''' || [[#Colour specifiers|colour specifier]] || The emitted (glow) colour of the material. This is ignored when '''emission_map''' is in use (but see also: '''emission_modulate_color'''). Default: black (0.0, 0.0, 0.0, 1.0).
|-
| '''emission_map''' || [[#Texture specifiers|texture specifier]] || A texture specifying emission (glow) colours. This is blended additively with all other colour terms. If '''emission_modulate_color''' is specified, the emission map is modulated by the modulate colour. Emission maps are used when shaders are active, and without shaders on supported hardware.
|-
| '''emission_modulate_color''' || [[#Colour specifiers|colour specifier]] || A colour with which to modulate the '''emission_map'''. If the emission map is in full colour, it is best to apply the colouring in advance using a graphics program. However, if the emission map is a single colour, using a greyscale emission map and a modulate colour will reduce memory usage by a factor of four when shaders are in use. Default: white (1.0, 1.0, 1.0, 1.0).
|-
| '''emission_and_illumination_map''' || [[#Texture specifiers|texture specifier]] || A texture whose RGB channels act like '''emission_map''', and whose alpha channel acts like '''illumination_map''' (and can be coloured with '''illumination_modulate_color'''). This uses less memory (on systems with shaders) than using separate shaders, although blending the emission and illumination maps into a single emission map, as described above, is still preferable.
|-
| '''illumination_map''' || [[#Texture specifiers|texture specifier]] || A texture specifying local illumination colour, which is added to incoming light. It differs from an emission map in that it is modulated with the diffuse colour before being added to the final colour. See example below.
|-
| '''illumination_modulate_color''' || [[#Colour specifiers|colour specifier]] || A colour with which to modulate the '''illumination_map'''. Default: white (1.0, 1.0, 1.0, 1.0).
|-
| '''normal_map''' || [[#Texture specifiers|texture specifier]] || A texture modifying [[#Important concepts|normals]]. The red, green and blue channels are the x, y and z coordinates of normals relative to the underlying normal (“[http://en.wikipedia.org/wiki/Normal_mapping tangent-space normal mapping]”), and the alpha channel is ingored. This is only used when shaders are active and no custom shader is used.
|-
| '''normal_and_parallax_map''' || [[#Texture specifiers|texture specifier]] || Like '''normal_map''', except that the alpha channel is includes a depth value used to add [http://en.wikipedia.org/wiki/Parallax_mapping simulated perspective]. If specified, '''normal_map''' is ignored.
|-
| '''parallax_bias''' || number || A value added to the parallax component of '''normal_and_parallax_map''', after multiplying by '''parallax_scale''' (default: 0).
|-
| '''parallax_scale''' || number || A scale factor for the parallax component of '''normal_and_parallax_map''' (default: 0.01). This value is the depth of the parallax map relative to the size of the texture. For instance, a value of 0.01 on a texture 100 metres wide will produce a maximum indentation of 1 metre. High parallax_scale values tend to lead to unacceptable texture distortion and “creeping” artefacts.
|-
| '''specular_color''' || [[#Colour specifiers|colour specifier]] || The colour to use for specular reflection over the entire model when '''specular_map''' is not used. The specular term is added to the diffuse term; for less intense specular highlights, use a darker colour. Default: black (0.0, 0.0, 0.0, 1.0) if '''shininess''' is zero, (0.2, 0.2, 0.2, 1.0) otherwise.
|-
| '''specular_map''' || [[#Texture specifiers|texture specifier]] || A texture specifying the specular highlight colour in its red, green and blue channels, and '''shininess''' in its alpha channel. 1 (fully opaque) means the value of '''shininess''' is used. 0 means a very low shininess is used. This is only used when shaders are active and no custom shader is used.
|-
| '''specular_modulate_color''' || [[#Colour specifiers|colour specifier]] || A colour with which to modulate the '''specular_map'''. Default: white (1.0, 1.0, 1.0, 1.0).
|-
| '''shininess''' || integer || The “tightness” of specular reflection, ranging from 0 to 128. 0 means no specular highlight. 128 is maximally shiny. Default: 128 if '''specular_map''' is used, 10 otherwise. '''Limitation:''' to use different shininess values with '''specular_map''' or '''specular_color''', you must either use the default or use different “shaders” and “materials” dictionaries. This should be fixed for 1.75.
|-
| '''vertex_shader''' || file name || name of GLSL vertex program to use.
|-
| '''fragment_shader''' || file name || name of GLSL fragment program to use.
|-
| '''textures''' || array of [[#Texture specifiers|texture specifier]]s || Textures to use in shader program.
|-
| '''uniforms''' || dictionary of uniform variable specifiers || uniform variables to use in shader program.
|-
|}

==== Illumination mapping vs. emission mapping ====
This image demonstrates the distinction between illumination mapping (top row) and emission mapping (bottom row).

[[Image:Emission-vs-illumination.png]]

=== Colour specifiers ===
'''Colour specifiers''' are used to declare colours in material attribute dictionaries, and in other contexts such as lasers in ''[[shipdata.plist]]''. Colour specifiers take any of several forms:

==== Named colours ====
The simplest form of colour specifier is a string containing a colour name. The following names are supported:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Colour names
! Name !! RGBA value
|-
| blackColor || 0, 0, 0, 1
|-
| darkGrayColor || 1/3, 1/3, 1/3, 1
|-
| lightGrayColor || 2/3, 2/3, 2/3, 1
|-
| whiteColor || 1, 1, 1, 1
|-
| grayColor || 1/2, 1/2, 1/2, 1
|-
| redColor || 1, 0, 0, 1
|-
| greenColor || 0, 1, 0, 1
|-
| blueColor || 0, 0, 1, 1
|-
| cyanColor || 0, 1, 1, 1
|-
| yellowColor || 1, 1, 0, 1
|-
| magentaColor || 1, 0, 1, 1
|-
| orangeColor || 1, 1/2, 0, 1
|-
| purpleColor || 1/2, 0, 1/2, 1
|-
| brownColor || 0.6, 0.4, 0.2, 1
|-
| clearColor || 0, 0, 0, 0
|-
|}

==== RGBA tuples ====
Colours may also be specified in RGB or RGBA (red, green, blue, alpha [transparency]). RGB or RGBA tuples may be specified as arrays or as strings separated by spaces. The values may range from 0 to 1 or 0 to 255. (If no value is greater than 1, 0–1 is assumed, otherwise 0–255.) Examples:
* <code>"1 1 0"</code> — yellow
* <code>"0 128 0 128"</code> — medium green at 50% opacity
* <code>(1, 0, 0)</code> – red

==== RGBA dictionaries ====
Just in case you’re unsure of the order the RGB[A] components come in, you can use a dictionary:
{
blue = 0.8;
green = 0.8;
}
Accepted keys are '''red''', '''green''', '''blue''' and '''alpha''' (or '''opacity'''), all optional (default: 0.0 for red, green and blue, 1.0 for alpha).

==== HSBA dictionaries ====
But wait, there’s more! Colours may also be specified as dictionaries in the [http://en.wikipedia.org/wiki/HSB_colour_space HSB colour space]. Accepted keys are '''hue''' (hue angle in degrees, required), '''saturation''', '''brightness''' (or '''value''') and '''alpha''' (or '''opacity'''). The default for the optional keys is 1.0.
{
// Pale magenta
hue = 300;
saturation = 0.3;
}

=== Texture specifiers ===
'''Texture specifiers''' are used to, er, specify textures. The simplest form of texture specifier is a string: <code>"ahruman-example-texture.png"</code>. The very simplest texture specifier is the empty string, <code>""</code>, meaning no texture. More complex texture specifiers are dictionaries, which can be used to specify a number of texture options.
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Texture specifier attributes
! Name !! Type !! Description
|-
| '''anisotropy''' || real || The degree of [http://en.wikipedia.org/wiki/Anisotropic_filtering anisotropic filtering] to use. Anisotropic filtering is used to reduce blurriness of MIP mapped textures shown at an angle (and thus only applies to textures whose '''min_filter''' is '''mipmap''' or '''default'''). The '''anisotropy''' setting is multiplied by the maximum anisotropy level specified by the system, and anisotropic filtering is used only if the result is greater than 1. (For example, on a GeForce FX 5200 card, the maximum level is 8, so an anisotropy value of 0.5 means an effective anisotropic filtering strength of 4. The precise meaning of this number is hardware-dependant. Fun, eh?) Anisotropic filtering is disabled in Reduced Detail mode and is not available on all hardware. Default: 0.5.
|-
| '''cube_map''' || boolean || If this is true, and the texture file is six times as high as it is wide, the texture will be treated as a cube map. If cube maps are not supported, it will be converted to a latitude/longitude map; if used as a diffuse map or emission/illumination map, you must ensure the model has appropriate texture coordinates. Note that cube maps are always available if shaders are supported, so custom shaders do not need to worry about this.

'''cube_map''' is always true for planet textures. To convert textures to and from cube maps, see [[planettool]].
|-
| '''extract_channel''' || string || Indicates that one of the channels of the texture should be extracted into a new greyscale texture. Allowed values: '''r''', '''g''', '''b''' and '''a'''.

This obviously involves extra work for Oolite, which is always a bad thing, but it makes it possible to combine multiple effect maps in a single texture for shaders and then extract channels for use as emission or illumination maps without shipping a redundant texture. If this means nothing to you, you probably don’t want to use '''extract_channel'''.
|-
| '''mag_filter''' || string || Specifies how to scale up the texture when it is near the camera. Either of:
* '''nearest''' (use nearest-neighbour sampling, which produces a pixellated effect)
* '''linear''' (use linear interpolation, which produces a blurry effect).
Default: '''linear'''.
|-
| '''min_filter''' || string || Specifies how to scale down the texture when it is far from the camera. One of:
* '''nearest''': nearest-neighbour sampling; generally very ugly, but sometimes useful for shaders using textures for special purposes.
* '''linear''': efficient, but rather ugly for textures with significant contrast or details.
* '''mipmap''': use trilinear MIP map filtering to improve scaling quality; generally also fast and least ugly, but uses 1/3 more memory, potentially slowing down systems with limited RAM or video memory.
* '''default''': '''linear''' in reduced detail mode, otherwise '''mipmap'''.
Default: '''default'''.
|-
| '''name''' || string || The file name of the texture to use. Must be a PNG image, in the Textures folder of Oolite or an OXP. In the specific case of '''diffuse_map''' textures, '''name''' is implicitly the same as the material key; to use no texture, you must specify <code>diffuse_map = ""</code>.
|-
| '''no_shrink''' || boolean || Indicates that Oolite should not scale the texture down, except to meet hardware requirements. Default: false.
|-
| '''repeat_s''' || boolean || Whether Oolite should repeat the texture in the ''s'' (or ''u'') co-ordinate, rather than clamping it. Default: false.
|-
| '''repeat_t''' || boolean || Whether Oolite should repeat the texture in the ''t'' (or ''v'') co-ordinate, rather than clamping it. Default: false.
|-
| '''texture_LOD_bias''' || real || tweak factor for MIP mapping (which does not apply to other '''min_filter''' modes). MIP mapping involves a trade-off between scaling artefacts and blurriness; the LOD (level of detail) bias affects this. Positive values mean more blur, negative ones mean more artefacts. The default value is −0.25 (mostly so people won’t say “hey, why is everything blurrier in the new Oolite?”). Texture LOD bias is not available on all hardware.
|-
|}

=== Uniform specifiers ===
:''Main article: [[Shaders in Oolite: uniforms]]''
A ''uniform specifier'' is used to specify game information to pass to a [[Shaders in Oolite|shader program]]. As with [[#Texture specifiers|texture specifiers]], the simple case is a string, which is treated as <code>{ binding = "the string" }</code>. For instance, uHullHeatLevel = hullHeatLevel</code> will bind a shader’s <code>uHullHeatLevel</code> uniform to a ship’s <code>hullHeatLevel</code> property. Additional properties can be specified in a dictionary.
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Texture specifier attributes
! Name !! Type !! Description
|-
| '''asMatrix''' || boolean || For a '''binding''' uniform whose bound property is of type ''quaternion'', setting '''asMatrix''' to true causes the value to be converted to a rotation matrix. If '''asMatrix''' is false, the quaternion will be converted to a vector, whose w, x, y and z values match those of the quaternion. For any other type of uniform, '''asMatrix''' is ignored. Default: true.
|-
| '''binding''' || string || The entity property to bind to, for a '''binding''' uniform. Ignored for other types of uniform.
|-
| '''clamped''' || boolean || For a '''binding''' uniform whose bound property is of type ''float'', setting '''clamped''' to true causes the value to be restricted to the range 0 to 1, inclusive. For a binding of type ''int'', causes the value to be set to either 0 or 1; 1 indicates that the underlying property has any value other than 0. For any other type of uniform, '''clamped''' is ignored. Default: false.
|-
| '''normalized''' || boolean || For a '''binding''' uniform whose bound property is of type ''vector'', setting '''normalized''' to true causes the value to be normalized, that is, scaled to a length of 1. For any other type of uniform, '''normalized''' is ignored. The spelling '''normalised''' is also accepted. Default: false.
|-
| '''type''' || string || One of:
* '''binding''': indicates that the '''binding''' property specifies an entity property to be set dynamically each time the shader is used.
* '''float''' or '''real''': indicates that the '''value''' property is an floating-point number.
* '''int''' or '''integer''': indicates that the '''value''' property is an integer, or whole number.
* '''texture''': indicates that the '''value''' property is an integer specifying a texture unit, that is, an index in the '''textures''' array.
Default: '''float'''.
|-
| '''value''' || number || The value to use for a '''float''', '''int''' or '''texture''' uniform. Ignored for '''binding''' uniforms.
|-
|}

=== Material dictionary example ===
Here is an example from the [[Material Test Suite OXP]]:
materials =
{
"cube-face" =
{
diffuse_map = "oolite_shader_test_suite_7_diffuse.png";
emission_and_illumination_map = "oolite_shader_test_suite_emission_and_illumination.png";
emission_modulate_color = (160, 255, 160);
illumination_modulate_color = (180, 180, 200);
};
};
Here, the “cube-face” material is assigned the diffuse texture “oolite_shader_test_suite_7_diffuse.png” and a combined emission and illumination map (which is a greyscale+alpha texture). The emission and illumination components are then given coloured tints (slightly green and slightly blue, respectively), producing this:

[[File:Oolite Material Test Suite 7.png|320px]]

== See also ==
* [[Material Test Suite OXP]] — demonstrates most material properties.

[[Category: Oolite]]

Debug OXP

2011-07-10T18:36:05Z

Ahruman:

'''Debug.oxp''' is a special OXP that enables JavaScript console support in test releases of Oolite (1.70 and later). It also adds a menu with various debug facilities under Mac OS X.

=== Downloads ===
[http://jens.ayton.se/oolite/files/debug-oxp-1.75-3.zip Debug OXP for Oolite 1.75.3]

== External JavaScript console support ==
On all platforms, installing Debug.oxp enables support for external console applications using the [[Oolite debug console TCP protocol]]. By default, it will attempt to connect to a console running on the same computer, but this can be changed by specifying a different <code>console-host</code> (and, optionally, <code>console-port</code>) in ''debugConfig.plist''. For external console support on the same computer under Mac OS X, <code>console-host</code> must be explicitly set to “127.0.0.1”; if this is not done, the [[#Integrated JavaScript console|integrated JavaScript console]] will be used instead. For information on using a console (integrated or external), see [[#Using the JavaScript console|Using the JavaScript console]] below.

'''Note:''' A cross-platform, python based, external console application is available in the [http://developer.berlios.de/project/showfiles.php?group_id=3577 Berlios Oolite files] area.

It contains a precompiled console for windows based computers, and the original python based console for Linux and Posix compliant computers.

On Debian or Ubuntu Linux you will need python 2.6.x installed and (at least) the packages <code>blt python-tk tk8.5</code> (or the equivalents in other distros.)

== Mac OS X-specific features ==
Under Mac OS X, the Debug OXP provides a menu with various debugging options and an integrated JavaScript console, as well as enabling external console support as on all platforms.

=== Debug menu ===
[[Image:Oolite-debug-menu.png|494px]]

The Debug menu provides options to
* Show the Oolite run log in the standard Console application.
* Enable or disable various classes of log message at runtime (like editing ''logcontrol.plist'', without the need to restart Oolite).
* Enable various testing features, such as drawing of bounding boxes.
* Show the JavaScript console, and specify when it should be shown automatically. (This may not have any effect with external consoles, depending on the external console implementation.)
* Create a ship of any role near the main station (equivalent to the <code>:spawn</code> [[#Macros|macro]]).
Note: some of these features are implemented by sending JavaScript messages to the [[#The console script|console script]]. If the script has been modified, some features may not work properly.

The Log Message Classes submenu can be modified by editing ''debugLogMessageClassesMenu.plist'', found inside the OXP. This is merged from Config directories in the usual fashion.

=== Integrated JavaScript console ===
[[Image:Oolite debug protocol example 1.png|594px]]

The integrated JavaScript console provides a window within Oolite which acts as a [[#Using the JavaScript console|JavaScript console]]. It can be shown using the Show JavaScript Console command in the Debug menu, unless external console mode has been enabled by setting <code>console-host</code> in ''debugConfig.plist''.

The integrated console has a 100-line memory. To see previous commands, press ⇞ (Page Up) or ⌥↑ (Option-Up Arrow). You can go the other way in the obvious manner.

== Using the JavaScript console ==
The JavaScript console, whether integrated or external, provides a powerful mechanism for interactively manipulating the game world. It can be used to issue simple commands, like <code>player.awardEquipment("EQ_FUEL_INJECTION")</code>. It can be used to inspect properties of entities in the game world. And it can be used to develop scripts, by rewriting and testing methods of live ship scripts and world scripts.

=== Macros ===
Macros are a special type of command prefixed with a colon. Instead of being interpreted as a JavaScript command, a macro is looked up in a dictionary, and the result is used as the “real” command. For instance, if you enter the command <code>:listM</code> (short for “list macros”), the macro dictionary is queried for the string “listM”, and (by default) the code <code>for (let prop in macros) { ConsoleMessage('macro-list', ':' + prop) }</code> is found and executed. This code is called the ''expansion'' of the macro. The result is a list of macros being printed:
:clr
:clear
:spawn
:bgColor
:showM
:rmFgColor
::
:d
:ds
:listM
:setM
:delM
:fgColor
:rmBgColor
:resetM

As you can see in the example, To see the expansion of a macro without executing it, use <code>:showM</code>:
> :showM :delM
:delM = deleteMacro(PARAM)

When a macro with the word <code>PARAM</code> is executed, <code>PARAM</code> is replaced with any text following the macro name, surrounded in quotation marks. This is how <code>:showM</code> functions, for example; the string “:showM :delM” is expanded to “showMacro(":delM")”, causing the JavaScript function <code>showMacro()</code>, which is part of the [[#The console script|console script]], to be called. You can see the implementation of <code>showMacro()</code> by entering <code>showMacro</code> – without any parentheses – into the console.

An initial set of macros is loaded from ''debugConfig.plist''. If you edit any macros, using <code>:setM</code> or <code>:delM</code>, all macros are saved in Oolite’s preferences from that point forwards. This means that you don’t have to re-enter any macros you write with <code>:setM</code> after restarting Oolite.

The following example creates a simple :msg macro:
> :setM msg ConsoleMessage(' ',PARAM)
If you then type:
> :msg Hello World
The macro will be expanded, and you'll see “Hello World” on the console. However, macros are not functions, so you cannot use macros in the middle of javascript, or as part of another macro.

=== The console script ===
While an external or integrated console is required to provide a means of user interaction, most of the actual behaviour of the console is implemented in JavaScript, in a script called ''oolite-debug-console.js''. Input typed into the console is passed to the console script, which then generates output. The console script is also informed of log messages and JavaScript errors, and provides a global function, <code>ConsoleMessage(colorCode: String, message: String)</code>, to write messages to the console using its background colour support. Lastly, the console script implements the entire macro system.

This means that the console’s behaviour can be extensively customized, for instance, by replacing the macro system with something more powerful. There are two basic approaches to doing this:
* Creating a custom script (or a copy) with the same name, in an OXP which loads later than Debug.oxp (e.g., one which has a name which comes later in alphabetical order).
* Using a normal world script, and changing the console script object at startup.
The latter approach has the advantage that it can continue to work with future versions of the console script, and multiple patches can coexist. For example, a modification to supplement the macro system with a better one might look as follows:
this.name = "my-super-console-macros"

this.startUp = function()
{
// Ensure debug console is installed
if (!debugConsole) return

// Save original implementation of consolePerformJSCommand
// Note the prefix, used to ensure uniqueness. If several scripts patch
// the same method, it's important that they use different names.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand = debugConsole.consolePerformJSCommand

// Replace debugConsole.consolePerformJSCommand with custom function
debugConsole.consolePerformJSCommand = function(command)
{
// Note that in this function "this" will refer to debugconsole, not
// my-super-console-macros, since the function will be called as a
// method of debugConsole.

// Strip leading spaces, same code as original function.
while (command.charAt(0) == " ")
{
command = command.substring(1)
}

if (command.charAt(0) == "!")
{
// Super macro call detected.
// Insert super macro system here.
}
else
{
// Otherwise, call through to original method.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand(command)
}
}
}
This same patching technique, incidentally, can be used to modify scripts at runtime, either from the console or from other scripts.

{{misc-OXP}}
[[Category:Oolite utilities]]

Misjump Analyzer

2011-05-29T13:57:51Z

Ahruman: Redirected page to Misjump Analyser

#REDIRECT [[Misjump Analyser]]

Missile Analyzer

2011-05-29T13:56:49Z

Ahruman: Redirected page to Missile Analyser

#REDIRECT [[Missile Analyser]]

File:Oolite-logo2.png

2011-05-07T13:03:36Z

Ahruman:

Former [[Oolite]] icon (versions 1.74 and earlier).

File:Oolite-logo2.png

2011-05-07T13:03:24Z

Ahruman:

Former Oolite icon (versions 1.74 and earlier).

Category:Oolite Ship Lists

2011-05-07T13:02:51Z

Ahruman: Updated icon.

This is the category for articles related to [[Oolite Ships|ship]] lists in the game Oolite. For information on the game, see the game’s page, [[Oolite]].
<center>[[Image:oolite-logo3.png|196px]]</center>

[[Category:Oolite ships| Oolite Ship Lists]]
[[Category:Oolite| Oolite Ship Lists]]