Elite Wiki - User contributions [en]

Oolite JavaScript OM Specification

2007-03-25T07:48:44Z

Dajt:

Use this page to define the object model exposed by Oolite to the JavaScript interpreter.

<tt><pre>
class Vector3
{
float x, z, y;
}

class Quaternion
{
float x, y, z, w;
}

class Commodity
{
readonly string Name;
readonly integer unitofMass; // grams, kgs, tons
}

class Consignment
{
Commodity commodity;
float quantity;
}

class Entity
{
readonly integer ID;
readonly Entity[] subentities;
Vector3 position;
Vector3 velocity;
Quaternion rotation;
// some property to set change in rotation per second?

static Entity getEntityWithID(integer ID);

void setAI(string AIName);
void pushAI(string AIName);
void popAI();
}

// Note all methods which take an Entity as an argument can also accept an entity ID instead.
class Vessel
{
float foreShieldStrength;
float aftShieldStrength;
float energy;

float foreShieldMaxStrength;
float aftShieldMaxStrength;
float maxEnergy;

// something measure of max and current hull integrity?

// need to represent docking ports somehow

float cabinTemperature;
integer maxCargoCapacity;
integer freeCargoCapacity;

Consignment[] cargo;

Entity currentTarget;
Entity[] escorts;

string roleName;
string commanderName;

// short form of getScanClassRelativeTo(0) - ie the player
integer getScanClass();
integer getScanClassRelativeTo(Entity other);

float getDistanceFrom(Entity other);
void Goto(Vector3 destination);
void GotoEntity(Entity other, integer minimumDistance);

// These methods return the ID of the launched entity, or -1 on error or if the target vessel cannot
// launch other vessels.
integer launchVesselWithRole(string role);
integer launchVesselWithName(string name);
}
</pre></tt>

Oolite JavaScript OM Specification

2007-03-25T03:27:47Z

Dajt: New page: Use this page to define the object model exposed by Oolite to the JavaScript interpreter. The syntax used should be obvious to anyone with some OO programming experience. <tt><pre> class...

Use this page to define the object model exposed by Oolite to the JavaScript interpreter.

The syntax used should be obvious to anyone with some OO programming experience.

<tt><pre>
class Vector3
{
float x, z, y;
}

class Quaternion
{
float x, y, z, w;
}

class Commodity
{
readonly string Name;
readonly integer unitofMass; // grams, kgs, tons
}

class Consignment
{
Commodity commodity;
float quantity;
}

class Entity
{
readonly integer ID;
readonly Entity[] subentities;
Vector3 position;
Vector3 velocity;
Quaternion rotation;
// some property to set change in rotation per second?

static Entity getEntityWithID(integer ID);

void setAI(string AIName);
void pushAI(string AIName);
void popAI();
}

// Note all methods which take an Entity as an argument can also accept an entity ID instead.
class Vessel
{
float foreShieldStrength;
float aftShieldStrength;
float energy;

float foreShieldMaxStrength;
float aftShieldMaxStrength;
float maxEnergy;

// something measure of max and current hull integrity?

// need to represent docking ports somehow

float cabinTemperature;
integer maxCargoCapacity;
integer freeCargoCapacity;

Consignment[] cargo;

Entity currentTarget;
Entity[] escorts;

string roleName;
string commanderName;

// short form of getScanClassRelativeTo(0) - ie the player
integer getScanClass();
integer getScanClassRelativeTo(Entity other);

float getDistanceFrom(Entity other);
void Goto(Vector3 destination);
void GotoEntity(Entity other, integer minimumDistance);

// These methods return the ID of the launched entity, or -1 on error or if the target vessel cannot
// launch other vessels.
integer launchVesselWithRole(string role);
integer launchVesselWithName(string name);
}
</pre></tt>

OXP howto

2007-03-25T03:18:17Z

Dajt:

[[Image:oolite-oxp-icon.png|100px|right|OXP icon]]
An '''Oolite Expansion Pack''' can cause many big changes or additions to Oolite's gameplay, or it may represent just a small, subtle alteration. By appearances, there is no way to tell what is inside, as it's merely a folder with the added extention '''.oxp'''. Inside, it will at least contain a folder named ''Config'', and possibly other folders such as ''AIs'', ''Models'', ''Textures'', ''Sounds'', etc. It is down to the goal of the OXP, which ways to combine elements to the OXP's contents.

=== AIs ===

The folder named AIs would contain any AI.plist additions the OXP might use.

* [[OXP howto AI|Making Oolite AI]]

=== Config===

This folder contains [[Property lists]] such as:

* ''[[shipdata.plist]]'' that introduces any new entity (ships, stations, objects etc.) to Oolite.
* ''[[shipyard.plist]]'' that introduces new ships available for player purchase.
* ''[[script.plist]]'' or ''[[script.oos]]'' that plots conditional ''script actions''. script.oos will be loaded in preference to script.plist if both exist.
* ''[[planetinfo.plist]]'' that plots system specific changes from the default. may also contain ''script actions''.
* ''[[commodities.plist]]'' that contains information for each commodity in a market.
* ''[[misc plists|descriptions.plist]]'' that adds vocabulary to Oolite texts.
* ''[[hud.plist]]'' that allows for changes or a radically new ''Head-Up Display''.
* ''[[characters.plist]]'' that adds non-player characters to Oolite.
* ''[[missiontext.plist]]'', ''[[misc plists|demoships.plist]]'', ''[[speech_pronunciation_guide.plist]]'' are some of the other custom methods.

All plist files except for those introducing new AI, belong in Config.

In its simplest form, an OXP could contain only a Config with an altering ''script.plist'' or ''planetinfo.plist''. An OXP that adds a new ship needs a ''shipdata.plist'' entry, and unless it is based entirely on existing Oolite data, would include a model and texture.

* [[OXP howto plist|Making Oolite plists]]

=== Models===

Oolite models need to be in the '''.dat''' format. There are utilities available that convert models made in Wings 3D (.obj) and Meshwork (.mesh) into this. A .dat file can be opened in a plain text editor to view the object's assigned texture names and see that they correspond with the actual file names in the Textures folder. The .dat file must be named exactly as it is referenced in the shipdata ''model'' entry.

* [[OXP howto model|Making Oolite models]]

=== Textures===

Oolite's textures are in the '''.png''' format, usually at a standard 512x512 size, and must be named exactly as they are named in the .dat file.

* [[OXP howto texture|Making Oolite textures]]

=== A preview of things to come ===

The scripting environment is being reworked to use JavaScript as the core scripting language. See what is available in the current implementation of the JavaScript branch at [[Oolite JavaScript ObjectModel]], and a proposed object model for the trunk [[Oolite JavaScript OM Specification]].

== External links ==

*[http://oolite.aegidian.org/cyoship/ Oolite Tutorial-Meshwork Shipbuilding]
*[http://oolite.aegidian.org/cyoship2/ Oolite Tutorial-Wings 3D Shipbuilding]

[[Category:Oolite]]

Scripting Oolite with JavaScript

2007-02-02T04:46:38Z

Dajt: /* KeyPressed */

== JavaScript file format ==

To use JavaScript for an OXP, place a file script.js in the OXP's Config directory. Do not also include a script.plist or script.oos file.

OXP scripts written in JavaScript are "event driven" - different functions of the script are called in response to state changes in the game, or when other events of interest happen.

Sometimes the event function will be called periodically, such as <tt>STATUS_DOCKED</tt> and <tt>STATUS_IN_FLIGHT</tt>. These functions will be called about every 10 seconds as long as the game is in that state.

Other event functions will only be called when that state becomes true, like <tt>KeyPressed</tt> and <tt>STATUS_EXITING_WITCHSPACE</tt>.

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

<pre>
this.Name = "OXPName"
this.Description = "A description of what the OXP does."
this.Version = "1.0"

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

=== Scripting Events ===

The following events are available to OXP scripts written in JavaScript.

==== Initialise ====

The <tt>Initialise</tt> event is called after all OXPs have been loaded. It can be used to do once-off initialisation such as registering to listen for certain keystrokes etc.

this.Initialise = function () {
}

==== KeyPressed ====

''' Broken due to merge from trunk '''

The <tt>KeyPressed</tt> event is called when a key the OXP is listening for has been pressed. It will be called once for each time the key is pressed, and will not be called again until the key is released and then pressed again.

The <tt>keycode</tt> argument gives the keycode of the key that was pressed. This can be used to determine which key was pressed if the OXP is listening for more than one key.

this.KeyPressed = function (keycode) {
}

==== AlertConditionChanged ====

The <tt>AlertConditionChanged</tt> event is called when the alert condition changes. The current alert condition can be read from <tt>Player.AlertCondition</tt> and the current alert flags can be read from <tt>Player.AlertFlags</tt>.

this.AlertConditionChanged = function (keycode) {
}

==== STATUS_DOCKED ====

The <tt>STATUS_DOCKED</tt> event is called periodically while the player is docked at a station or other entity with a docking port.

this.STATUS_DOCKED = function () {
}

==== STATUS_IN_FLIGHT ====

The <tt>STATUS_IN_FLIGHT</tt> event is called periodically while the player is flying in normal space or interstellar space (due to a misjump).

this.STATUS_IN_FLIGHT = function () {
}

==== STATUS_LAUNCHING ====

The <tt>STATUS_LAUNCHING</tt> event is called once when the player has launched from a dock.

this.STATUS_LAUNCHING = function () {
}

==== STATUS_EXITING_WITCHSPACE ====

The <tt>STATUS_EXITING_WITCHSPACE</tt> event is called once when the player arrives in a new system.

this.STATUS_EXITING_WITCHSPACE = function () {
}

Scripting Oolite with JavaScript

2007-01-16T03:42:01Z

Dajt: /* script.js File Template */

== JavaScript file format ==

To use JavaScript for an OXP, place a file script.js in the OXP's Config directory. Do not also include a script.plist or script.oos file.

OXP scripts written in JavaScript are "event driven" - different functions of the script are called in response to state changes in the game, or when other events of interest happen.

Sometimes the event function will be called periodically, such as <tt>STATUS_DOCKED</tt> and <tt>STATUS_IN_FLIGHT</tt>. These functions will be called about every 10 seconds as long as the game is in that state.

Other event functions will only be called when that state becomes true, like <tt>KeyPressed</tt> and <tt>STATUS_EXITING_WITCHSPACE</tt>.

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

<pre>
this.Name = "OXPName"
this.Description = "A description of what the OXP does."
this.Version = "1.0"

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

=== Scripting Events ===

The following events are available to OXP scripts written in JavaScript.

==== Initialise ====

The <tt>Initialise</tt> event is called after all OXPs have been loaded. It can be used to do once-off initialisation such as registering to listen for certain keystrokes etc.

this.Initialise = function () {
}

==== KeyPressed ====

The <tt>KeyPressed</tt> event is called when a key the OXP is listening for has been pressed. It will be called once for each time the key is pressed, and will not be called again until the key is released and then pressed again.

The <tt>keycode</tt> argument gives the keycode of the key that was pressed. This can be used to determine which key was pressed if the OXP is listening for more than one key.

this.KeyPressed = function (keycode) {
}

==== AlertConditionChanged ====

The <tt>AlertConditionChanged</tt> event is called when the alert condition changes. The current alert condition can be read from <tt>Player.AlertCondition</tt> and the current alert flags can be read from <tt>Player.AlertFlags</tt>.

this.AlertConditionChanged = function (keycode) {
}

==== STATUS_DOCKED ====

The <tt>STATUS_DOCKED</tt> event is called periodically while the player is docked at a station or other entity with a docking port.

this.STATUS_DOCKED = function () {
}

==== STATUS_IN_FLIGHT ====

The <tt>STATUS_IN_FLIGHT</tt> event is called periodically while the player is flying in normal space or interstellar space (due to a misjump).

this.STATUS_IN_FLIGHT = function () {
}

==== STATUS_LAUNCHING ====

The <tt>STATUS_LAUNCHING</tt> event is called once when the player has launched from a dock.

this.STATUS_LAUNCHING = function () {
}

==== STATUS_EXITING_WITCHSPACE ====

The <tt>STATUS_EXITING_WITCHSPACE</tt> event is called once when the player arrives in a new system.

this.STATUS_EXITING_WITCHSPACE = function () {
}

Scripting Oolite with JavaScript

2007-01-16T01:59:37Z

Dajt:

== JavaScript file format ==

To use JavaScript for an OXP, place a file script.js in the OXP's Config directory. Do not also include a script.plist or script.oos file.

OXP scripts written in JavaScript are "event driven" - different functions of the script are called in response to state changes in the game, or when other events of interest happen.

Sometimes the event function will be called periodically, such as <tt>STATUS_DOCKED</tt> and <tt>STATUS_IN_FLIGHT</tt>. These functions will be called about every 10 seconds as long as the game is in that state.

Other event functions will only be called when that state becomes true, like <tt>KeyPressed</tt> and <tt>STATUS_EXITING_WITCHSPACE</tt>.

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

<pre>
this.Name = "OXPName"
this.Descriptipn = "A description of what the OXP does."
this.Version = "1.0"

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

The following events are available to OXP scripts written in JavaScript.

==== Initialise ====

The <tt>Initialise</tt> event is called after all OXPs have been loaded. It can be used to do once-off initialisation such as registering to listen for certain keystrokes etc.

this.Initialise = function () {
}

==== KeyPressed ====

The <tt>KeyPressed</tt> event is called when a key the OXP is listening for has been pressed. It will be called once for each time the key is pressed, and will not be called again until the key is released and then pressed again.

The <tt>keycode</tt> argument gives the keycode of the key that was pressed. This can be used to determine which key was pressed if the OXP is listening for more than one key.

this.KeyPressed = function (keycode) {
}

==== AlertConditionChanged ====

The <tt>AlertConditionChanged</tt> event is called when the alert condition changes. The current alert condition can be read from <tt>Player.AlertCondition</tt> and the current alert flags can be read from <tt>Player.AlertFlags</tt>.

this.AlertConditionChanged = function (keycode) {
}

==== STATUS_DOCKED ====

The <tt>STATUS_DOCKED</tt> event is called periodically while the player is docked at a station or other entity with a docking port.

this.STATUS_DOCKED = function () {
}

==== STATUS_IN_FLIGHT ====

The <tt>STATUS_IN_FLIGHT</tt> event is called periodically while the player is flying in normal space or interstellar space (due to a misjump).

this.STATUS_IN_FLIGHT = function () {
}

==== STATUS_LAUNCHING ====

The <tt>STATUS_LAUNCHING</tt> event is called once when the player has launched from a dock.

this.STATUS_LAUNCHING = function () {
}

==== STATUS_EXITING_WITCHSPACE ====

The <tt>STATUS_EXITING_WITCHSPACE</tt> event is called once when the player arrives in a new system.

this.STATUS_EXITING_WITCHSPACE = function () {
}

Scripting Oolite with JavaScript

2007-01-16T00:37:16Z

Dajt:

== JavaScript file format ==

To use JavaScript for an OXP, place a file script.js in the OXP's Config directory. Do not also include a script.plist or script.oos file.

=== script.js File Template ===
<pre>
// Copy and paste this template into a file called script.js in the OXP Config directory
//
this.Name = "OXPName"
this.Descriptipn = "A description of what the OXP does."
this.Version = "1.0"

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

The following events are available to OXP scripts written in JavaScript.

==== Initialise ====

The initialise event is called after all OXPs have been loaded. It can be used to do once-off initialisation such as registering to listen for certain keystrokes etc.

this.Initialise = function () {
}

==== KeyPressed ====

The KeyPressed event is called when a key the OXP is listening for has been pressed. It will be called once for each time the key is pressed, and will not be called again until the key is released and then pressed again.

The keycode argument gives the keycode of the key that was pressed. This can be used to determine which key was pressed if the OXP is listening for more than one key.

this.KeyPressed = function (keycode) {
}

==== AlertConditionChanged ====

The AlertConditionChanged event is called when the alert condition changes. The current alert condition can be read from Player.AlertCondition and the current alert flags can be read from Player.AlertFlags.

this.AlertConditionChanged = function (keycode) {
}

==== STATUS_DOCKED ====

The STATUS_DOCKED event is called periodically while the player is docked at a station or other entity with a docking port.

this.STATUS_DOCKED = function () {
}

==== STATUS_IN_FIGHT ====

The STATUS_IN_FIGHT event is called periodically while the player is flying in normal space or interstellar space (due to a misjump).

this.STATUS_IN_FIGHT = function () {
}

==== STATUS_LAUNCHING ====

The STATUS_LAUNCHING event is called once when the player has launched from a dock.

this.STATUS_LAUNCHING = function () {
}

==== STATUS_EXITING_WITCHSPACE ====

The STATUS_EXITING_WITCHSPACE event is called once when the player arrives in a new system.

this.STATUS_EXITING_WITCHSPACE = function () {
}

Running Oolite-Windows

2006-10-20T06:06:07Z

Dajt: /* Building Oolite from source */

==Overview==
The Windows port of Oolite is built from the same source as the Linux and OS-X versions, and has all the features of those versions.

All OXPs should be compatible with the Windows port.

==Getting and installing the game==
The game may be downloaded from [http://oolite-pc.berlios.de the BerliOS project page] for Oolite-PC. The installer is also mirrored at ftp://ftp.alioth.net/oolite

To install, run the executable that you have just downloaded. You will get the familiar Windows installer.

A regular build of changes from the SVN source is being carried out on a regular basis. The complete installer above must be installed before any of the updates will work. The update filename changes with each build, so get the latest update file by following the link here: [http://aegidian.org/bb/viewtopic.php?t=1529].

The game has been tested on Windows XP and Windows 2000. '''It will not run on the DOS-extender versions of Windows''' such as Windows 95, 98 or ME. It is expected it will run with Vista, so long as drivers are available for the hardware you have. You are advised to run the latest 3D graphics drivers from your 3D card manufacturer.

===Errata===
There was a problem in the 1.62 build that caused memory exhaustion. [http://www.aegidian.org/bb/viewtopic.php?t=1416 Please read this page] to find out how to manually patch the Windows installation. Users of later builds (for example, the current -344 build on the BerliOS site) will not suffer from this issue.

==Running the game==
Find the Oolite icon in the Start -> Programs menu and click on it. Alternatively double click the Oolite program icon on the desktop. Note that the following key combination will get you out of 'graphics related trouble':

Shift-Escape: Quit Oolite immediately

===Installing OXPs===
You will need to find where the oolite.app folder is placed: it should be in C:\Program Files\Oolite. Create an AddOns folder beside the oolite.app folder. Put OXPs in here. Note that some OXPs when unzipped contain a folder with a README file and then the OXP - in this case, it's best to unzip the OXP somewhere other than AddOns and copy the OXP folder once unpacked into AddOns.

===Notes for amd64 users===
No builds for 64-bit versions of Windows have yet been made, however, given the proper availability of graphics and sound drivers, the 32-bit version should run on 64-bit Windows. 32 bit Windows running on amd64 hardware should not have an issue.

==Building Oolite from source==
# Download and install the necessary software
## Download and install svn for Windows: [http://subversion.tigris.org/project_packages.html#binary-packages]. Accept all defaults given by the installer.
## Download and install GNUstep for windows: [ftp://ftp.gnustep.org/pub/gnustep/binaries/windows/base-1.11.1-gui-0.10.1/GNUstep-base-1.11.1-gui-0.10.1-3.exe]. Accept all defaults given by the installer.
## Download the SDL files required to build Oolite: [http://prdownload.berlios.de/oolite-pc/Local.zip]
## Unzip this file to <code>c:\GNUstep\Local</code>
# Get the source and build it (note, the source comes from the oolite-linux project)
## Start the GNUstep command line (<i>Start -> Programs -> GNUstep Development -> MSYS for GNUstep</i>) and issue the following commands:
## <code>cd $GNUSTEP_LOCAL_ROOT</code>
## <code>export PATH=$PATH:$GNUSTEP_LOCAL_ROOT/bin</code>
## <code>mkdir oolite</code>
## <code>cd oolite</code>
## <code>svn checkout svn://svn.berlios.de/oolite-linux/trunk</code>
## <code>cd trunk</code>
## <code>make</code>
# To run the game in the build environment:
## Before running the first time: <code>cp $GNUSTEP_LOCAL_ROOT/bin/*.dll oolite.app</code>
## <code>openapp oolite.app</code>

Assuming you have installed one of Nic's releases as detailed above, you can easily keep updating the installation from the latest source. In the <code>$GNUSTEP_LOCAL_ROOT/oolite/trunk</code> directory, issue the commands:

# <code>export PATH=$PATH:$GNUSTEP_LOCAL_ROOT/bin</code>
# <code>svn up</code>
# <code>rm -rf oolite.app/Resources; make</code>

You only need to issue the export PATH command when you first start the command line. The rm -rf command before make is required because GNUstep for Windows cannot parse the XML plist file format, and the build fails when it tries to read one of these generated each time the build is performed. This failure is not important, and the process still works, but it is annoying.

Then use the following script to copy the new files over the existing installation:

<pre>
OA="/c/Program Files/Oolite/oolite.app"
cd $GNUSTEP_LOCAL_ROOT/oolite/trunk
if [ oolite.app/oolite.exe -nt "$OA/oolite.exe" ]; then
echo "Updating oolite.exe"
cp oolite.app/oolite.exe "$OA/oolite.exe"
fi

for a in AIs Config Images Models Music Sounds Textures; do
for b in Resources/$a/*; do
c=`basename $b`
if [ $b -nt "$OA/Contents/Resources/$a/$c" ]; then
echo "Updating with $b"
cp $b "$OA/Contents/Resources/$a/$c"
fi
done
done
</pre>

If you want to edit the source, Notepad++ has good Objective-C support and is free: [http://notepad-plus.sourceforge.net/]

Also see the Oolite-PC forum: [http://www.aegidian.org/bb/viewforum.php?f=8]

[[Category:Oolite]]

Shipdata.plist

2006-04-21T04:12:02Z

Dajt: /* smooth */

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

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

Example:
<key>aft_eject_position</key>
<string>0.0 -4.5 -23.0</string>

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

Example:
<key>ai_type</key>
<string>pirateAI.plist</string>

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

Example:
<key>beacon</key>
<string>X-code</string>

== bounty ==
Sets a Cr. reward on the NPC's head, and is bound to give it trouble with the law .

Example:
<key>bounty</key>
<integer>50</integer>

== cargo_carried ==
Determines the type of cargo carried as described in [[commodities.plist]], only one type can be specified.

Example:
<key>cargo_carried</key>
<string>Gold</string>

== cargo_type ==
Determines if object is indeed cargo (CARGO_RANDOM, CARGO_SLAVES, CARGO_THARGOID) or a ship, as below, which is not cargo. Another notable type of cargo is the scripted item (CARGO_SCRIPTED_ITEM), as examplified by the cloacking device. Only works for randomly generated cargopods.

Example:
<key>cargo_type</key>
<string>CARGO_NOT_CARGO</string>

In v1.63, more controll will be available through the CARGO_CARRIED string. (see also discussion)

Example:
<key>cargo_type</key>
<string>CARGO_CARRIED</string>
<key>cargo_carried</key>
<string>4 Gold</string>

== death_actions ==
Gives an oportunity to have a ship do something special as it's dying.

Example:
<key>death_actions</key>
<array>
<string>spawn: explosive_shrapnel 1</string>
</array>

== max_defense_ships ==
Designates how many ships a dockable entity (station, carrier) can launch in defense.

== defense_ship_role ==
Gives an oportunity to designate a particular (group of) ships that will defend a station/carrier. This has to be specified in the [[Shipdata.plist#roles|roles]] of the ship(s) that are assigned to defend.

Example:
<key> defense_ship_role </key>
<string>carrier_defenders</string>

== energy_recharge_rate ==
The rate at which energy is replenished. Stations are at 100, Adders at 2..

Example:
<key>energy_recharge_rate</key>
<real>4.5</real>

== escorts ==
Determines how many escorts an NPC shall have.

Example:
<key>escorts</key>
<integer>4</integer>

== escort-role ==
Assigns the specific ship type to be the escort, by the ship's role

Example:
<key>escort-role</key>
<string>my_custom_escort_role</string>

== escort-ship ==
Assigns the specific ship type to be the escort, by the ship's name.

Example:
<key>escort-ship</key>
<string>cobramk1</string>

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

x y z width height length

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

'''width''' in metres, how wide a plume is on x axis.

'''height''' in metres, how tall a plume is on y axis.

'''length''' in metres, how long a plume is on z axis.

Below are 2 assigned plumes at coords 5, 0, -25 and -5, 0, -25, and each plume is 6 m wide, 4 m tall and m 10 long

Example:
<key>exhaust</key>
<array>
<string>5 0.0 -25 6.0 4.0 10.0</string>
<string>-5 0.0 -25 6.0 4.0 10.0</string>
</array>

== extra_cargo ==
New in version 1.62rc3
Cargobay extension size can now be customised.

Example:
<key>extra_cargo</key>
<integer>value</integer

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

Example:
<key>forward_weapon_type</key>
<string>WEAPON_BEAM_LASER</string>

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

Example:
<key>frangible</key>
<false/>

== fuel ==
Determines an NPC ship's fuel storage, which will affect how it uses its Fuel Injectors.

Example:
<key>fuel</key>
<integer>70</integer>

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

Example:
<key>has_ecm</key>
<real>0.5</real>
or
<key>has_ecm</key>
<false/>

== has_escape_pod ==
Determines if a ship has an escape pod.

Example:
<key>has_escape_pod</key>
<false/>

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

Example:
<key>has_fuel_injection </key>
<real>0.99</real>

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

Example:
<key>has_scoop</key>
<false/>

== has_shield_enhancer ==
Determines if a ship has the coveted shield enhancer.

Example:
<key>has_shield_enhancer</key>
<real>0.45000000000000001</real>

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

Example:
<key>hud</key>
<string>specialhud.plist</string>

== laser_color ==
Determines a ship's laser colour. NPCs that is, not the player's laser.

Example:
<key>laser_color</key>
<string>pinkColor</string>

== like_ship ==
Allows a shipdata entry (of a ship with many matching characteristics to another) to be short and sweet, adopting data of stated ship (name), and allowing for any differences between these ships that will be listed. (It is best not to refer to other references.)

Example:
<key>like_ship</key>
<string>adder</string>
<key>max_flight_speed</key>
<real>700</real>
<key>name</key>
<string>Freak Turbo Adder</string>

== likely_cargo ==
Sets a probable number of tons cargo carried by an NPC, as something else than the stated maximum cargo limit.

Example:
<key>likely_cargo</key>
<integer>2</integer>

== max_cargo ==
Sets the ship's cargo limit.

Example:
<key>max_cargo</key>
<integer>5</integer>

== max_energy ==
Sets the ship's energy value.

Example:
<key>max_energy</key>
<real>300</real>

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

Example:
<key>max_flight_pitch</key>
<real>2.2</real>

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

Example:
<key>max_flight_roll</key>
<real>4.2000000000000002</real>

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

Example:
<key>max_flight_speed</key>
<real>320</real>

== max_missiles ==
Sets a ship's missile limit.

Example:
<key>max_missiles</key>
<integer>1</integer>

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

Example:
<key>missile_launch_position</key>
<string>0.0 -2.25 10.0</string>

== missiles ==
Sets a ship's probable number of missiles.

Example:
<key>missiles</key>
<integer>0</integer>

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

Example:
<key>model</key>
<string>example_ship.dat</string>

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

Example:
<key>name</key>
<string>ExampleShip Mark IX</string>

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

In the example below the ship in question will be considered twice as often (2.0) when a trader is called for, only one quarter as often (0.25) when looking for a hunter, and as often as any other pirate ships when looking for a pirate.

Example:
<key>roles</key>
<string>hunter(0.25) trader(2.0) pirate</string>

or simply

<key>roles</key>
<string>just_custom_role</string>

== rotational_velocity ==
May be applied to a sub-entity, like the following entry to the [[Weeviloid 2]]s spines.
Takes the form of [[Quaternions]], below example enables rotation around the Z-axis.

Example:
<key>rotational_velocity</key>
<string>0.707 0.0 0.0 0.707</string>

== scanClass ==
Will alter the model's appearance on the [[IFF system]]. If this line is omitted, it will become by default a standard ship entity, appearing as yellow flag on the radar. There are other options.
* CLASS_BUOY
* CLASS_CARGO
* CLASS_MILITARY
* CLASS_MISSILE
* CLASS_POLICE
* CLASS_ROCK
* CLASS_STATION
* CLASS_THARGOID

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

Example:
<key>scanClass</key>
<string>CLASS_ROCK</string>

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

Example:
<key>script_actions</key>
<array>
<string>debugOn</string>
<string>testForEquipment: EQ_CLOAKING_DEVICE</string>
<dict>
<key>conditions</key>
<array>
<string>foundEquipment_bool equal NO</string>
</array>
<key>do</key>
<array>
<string>awardEquipment: EQ_CLOAKING_DEVICE</string>
</array>
<key>else</key>
<array>
<string>awardCargo: 100 Gold</string>
</array>
</dict>
<string>debugOff</string>
</array>

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

Example:
<key>setup_actions</key>
<array>
<string>initialiseTurret</string>
</array>

== smooth ==
Determines if the model will have magic smoothing method applied (very rare).

Example:
<key>smooth</key>
<true/>

== subentities ==
Can assign other objects, lights and turrets, to be associated with the model. The first three numbers are XYZ positions, however, controlling positioning of enslaved objects is done by means of [[quaternions]].

Lights follow their own recipe.
*FLASHER* x y z hue speed offset size

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

'''hue''' describes the colour of the light as a position on a color wheel.

'''speed''' describes how fast the light pulses (on a sine wave) in Hertz (at 0 the light constantly lit)

'''offset''' is the offset to the sine wave (0..1) to time-shift each light

'''size''' is the size of the light's corona in metres

Example:
<key>subentities</key>
<array>
<string>mySubEntity 0 -5 10 1 0 0 0</string>
<string>*FLASHER* 0 5.5 10 30.0 1 0.0 12</string>
</array>

note: armed subentities always fire along their Z-axis. When rotating along the Z(t=0)-axis.

== thrust ==
Gives the entity an 'inertia' value, translating size and speed into a form of velocity. 0 for rocks and cargo, 50 for a very fast ship, 100 for a station..

Example:
<key>thrust</key>
<real>25</real>

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

Example:
<key>view_position_aft</key>
<string>0.0 5.0 -20.0</string>
<key>view_position_forward</key>
<string>0.0 1.9375 5.0</string>
<key>view_position_port</key>
<string>-11.85 2.825 -3.5</string>
<key>view_position_starboard</key>
<string>11.85 2.825 -3.5</string>

== weapon_energy ==
Gives a weapon energy value to the ship's laser that is different than the default.

Example:
<key>weapon_energy</key>
<real>15</real>

== weapon_offset ==
must ask Aegidian. does it make a poor shot?

Example:
<key>weapon_offset_x</key>
<real>10</real>

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

Example:
<key>weapon_position_aft</key>
<string>0.0 -5.0 -20.0</string>
<key>weapon_position_forward</key>
<string>0.0 0.0417 16.6667</string>
<key>weapon_position_port</key>
<string>-13.75 -2.0625 -1.875</string>
<key>weapon_position_starboard</key>
<string>13.75 -2.0625 -1.875</string>

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

Shipdata.plist

2006-04-21T04:11:35Z

Dajt: /* script_actions */

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

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

Example:
<key>aft_eject_position</key>
<string>0.0 -4.5 -23.0</string>

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

Example:
<key>ai_type</key>
<string>pirateAI.plist</string>

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

Example:
<key>beacon</key>
<string>X-code</string>

== bounty ==
Sets a Cr. reward on the NPC's head, and is bound to give it trouble with the law .

Example:
<key>bounty</key>
<integer>50</integer>

== cargo_carried ==
Determines the type of cargo carried as described in [[commodities.plist]], only one type can be specified.

Example:
<key>cargo_carried</key>
<string>Gold</string>

== cargo_type ==
Determines if object is indeed cargo (CARGO_RANDOM, CARGO_SLAVES, CARGO_THARGOID) or a ship, as below, which is not cargo. Another notable type of cargo is the scripted item (CARGO_SCRIPTED_ITEM), as examplified by the cloacking device. Only works for randomly generated cargopods.

Example:
<key>cargo_type</key>
<string>CARGO_NOT_CARGO</string>

In v1.63, more controll will be available through the CARGO_CARRIED string. (see also discussion)

Example:
<key>cargo_type</key>
<string>CARGO_CARRIED</string>
<key>cargo_carried</key>
<string>4 Gold</string>

== death_actions ==
Gives an oportunity to have a ship do something special as it's dying.

Example:
<key>death_actions</key>
<array>
<string>spawn: explosive_shrapnel 1</string>
</array>

== max_defense_ships ==
Designates how many ships a dockable entity (station, carrier) can launch in defense.

== defense_ship_role ==
Gives an oportunity to designate a particular (group of) ships that will defend a station/carrier. This has to be specified in the [[Shipdata.plist#roles|roles]] of the ship(s) that are assigned to defend.

Example:
<key> defense_ship_role </key>
<string>carrier_defenders</string>

== energy_recharge_rate ==
The rate at which energy is replenished. Stations are at 100, Adders at 2..

Example:
<key>energy_recharge_rate</key>
<real>4.5</real>

== escorts ==
Determines how many escorts an NPC shall have.

Example:
<key>escorts</key>
<integer>4</integer>

== escort-role ==
Assigns the specific ship type to be the escort, by the ship's role

Example:
<key>escort-role</key>
<string>my_custom_escort_role</string>

== escort-ship ==
Assigns the specific ship type to be the escort, by the ship's name.

Example:
<key>escort-ship</key>
<string>cobramk1</string>

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

x y z width height length

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

'''width''' in metres, how wide a plume is on x axis.

'''height''' in metres, how tall a plume is on y axis.

'''length''' in metres, how long a plume is on z axis.

Below are 2 assigned plumes at coords 5, 0, -25 and -5, 0, -25, and each plume is 6 m wide, 4 m tall and m 10 long

Example:
<key>exhaust</key>
<array>
<string>5 0.0 -25 6.0 4.0 10.0</string>
<string>-5 0.0 -25 6.0 4.0 10.0</string>
</array>

== extra_cargo ==
New in version 1.62rc3
Cargobay extension size can now be customised.

Example:
<key>extra_cargo</key>
<integer>value</integer

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

Example:
<key>forward_weapon_type</key>
<string>WEAPON_BEAM_LASER</string>

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

Example:
<key>frangible</key>
<false/>

== fuel ==
Determines an NPC ship's fuel storage, which will affect how it uses its Fuel Injectors.

Example:
<key>fuel</key>
<integer>70</integer>

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

Example:
<key>has_ecm</key>
<real>0.5</real>
or
<key>has_ecm</key>
<false/>

== has_escape_pod ==
Determines if a ship has an escape pod.

Example:
<key>has_escape_pod</key>
<false/>

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

Example:
<key>has_fuel_injection </key>
<real>0.99</real>

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

Example:
<key>has_scoop</key>
<false/>

== has_shield_enhancer ==
Determines if a ship has the coveted shield enhancer.

Example:
<key>has_shield_enhancer</key>
<real>0.45000000000000001</real>

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

Example:
<key>hud</key>
<string>specialhud.plist</string>

== laser_color ==
Determines a ship's laser colour. NPCs that is, not the player's laser.

Example:
<key>laser_color</key>
<string>pinkColor</string>

== like_ship ==
Allows a shipdata entry (of a ship with many matching characteristics to another) to be short and sweet, adopting data of stated ship (name), and allowing for any differences between these ships that will be listed. (It is best not to refer to other references.)

Example:
<key>like_ship</key>
<string>adder</string>
<key>max_flight_speed</key>
<real>700</real>
<key>name</key>
<string>Freak Turbo Adder</string>

== likely_cargo ==
Sets a probable number of tons cargo carried by an NPC, as something else than the stated maximum cargo limit.

Example:
<key>likely_cargo</key>
<integer>2</integer>

== max_cargo ==
Sets the ship's cargo limit.

Example:
<key>max_cargo</key>
<integer>5</integer>

== max_energy ==
Sets the ship's energy value.

Example:
<key>max_energy</key>
<real>300</real>

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

Example:
<key>max_flight_pitch</key>
<real>2.2</real>

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

Example:
<key>max_flight_roll</key>
<real>4.2000000000000002</real>

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

Example:
<key>max_flight_speed</key>
<real>320</real>

== max_missiles ==
Sets a ship's missile limit.

Example:
<key>max_missiles</key>
<integer>1</integer>

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

Example:
<key>missile_launch_position</key>
<string>0.0 -2.25 10.0</string>

== missiles ==
Sets a ship's probable number of missiles.

Example:
<key>missiles</key>
<integer>0</integer>

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

Example:
<key>model</key>
<string>example_ship.dat</string>

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

Example:
<key>name</key>
<string>ExampleShip Mark IX</string>

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

In the example below the ship in question will be considered twice as often (2.0) when a trader is called for, only one quarter as often (0.25) when looking for a hunter, and as often as any other pirate ships when looking for a pirate.

Example:
<key>roles</key>
<string>hunter(0.25) trader(2.0) pirate</string>

or simply

<key>roles</key>
<string>just_custom_role</string>

== rotational_velocity ==
May be applied to a sub-entity, like the following entry to the [[Weeviloid 2]]s spines.
Takes the form of [[Quaternions]], below example enables rotation around the Z-axis.

Example:
<key>rotational_velocity</key>
<string>0.707 0.0 0.0 0.707</string>

== scanClass ==
Will alter the model's appearance on the [[IFF system]]. If this line is omitted, it will become by default a standard ship entity, appearing as yellow flag on the radar. There are other options.
* CLASS_BUOY
* CLASS_CARGO
* CLASS_MILITARY
* CLASS_MISSILE
* CLASS_POLICE
* CLASS_ROCK
* CLASS_STATION
* CLASS_THARGOID

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

Example:
<key>scanClass</key>
<string>CLASS_ROCK</string>

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

Example:
<key>script_actions</key>
<array>
<string>debugOn</string>
<string>testForEquipment: EQ_CLOAKING_DEVICE</string>
<dict>
<key>conditions</key>
<array>
<string>foundEquipment_bool equal NO</string>
</array>
<key>do</key>
<array>
<string>awardEquipment: EQ_CLOAKING_DEVICE</string>
</array>
<key>else</key>
<array>
<string>awardCargo: 100 Gold</string>
</array>
</dict>
<string>debugOff</string>
</array>

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

Example:
<key>setup_actions</key>
<array>
<string>initialiseTurret</string>
</array>

== smooth ==
Determines if the model will have magic smoothening method applied (very rare).

Example:
<key>smooth</key>
<true/>

== subentities ==
Can assign other objects, lights and turrets, to be associated with the model. The first three numbers are XYZ positions, however, controlling positioning of enslaved objects is done by means of [[quaternions]].

Lights follow their own recipe.
*FLASHER* x y z hue speed offset size

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

'''hue''' describes the colour of the light as a position on a color wheel.

'''speed''' describes how fast the light pulses (on a sine wave) in Hertz (at 0 the light constantly lit)

'''offset''' is the offset to the sine wave (0..1) to time-shift each light

'''size''' is the size of the light's corona in metres

Example:
<key>subentities</key>
<array>
<string>mySubEntity 0 -5 10 1 0 0 0</string>
<string>*FLASHER* 0 5.5 10 30.0 1 0.0 12</string>
</array>

note: armed subentities always fire along their Z-axis. When rotating along the Z(t=0)-axis.

== thrust ==
Gives the entity an 'inertia' value, translating size and speed into a form of velocity. 0 for rocks and cargo, 50 for a very fast ship, 100 for a station..

Example:
<key>thrust</key>
<real>25</real>

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

Example:
<key>view_position_aft</key>
<string>0.0 5.0 -20.0</string>
<key>view_position_forward</key>
<string>0.0 1.9375 5.0</string>
<key>view_position_port</key>
<string>-11.85 2.825 -3.5</string>
<key>view_position_starboard</key>
<string>11.85 2.825 -3.5</string>

== weapon_energy ==
Gives a weapon energy value to the ship's laser that is different than the default.

Example:
<key>weapon_energy</key>
<real>15</real>

== weapon_offset ==
must ask Aegidian. does it make a poor shot?

Example:
<key>weapon_offset_x</key>
<real>10</real>

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

Example:
<key>weapon_position_aft</key>
<string>0.0 -5.0 -20.0</string>
<key>weapon_position_forward</key>
<string>0.0 0.0417 16.6667</string>
<key>weapon_position_port</key>
<string>-13.75 -2.0625 -1.875</string>
<key>weapon_position_starboard</key>
<string>13.75 -2.0625 -1.875</string>

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

Script.oos

2006-04-05T06:54:27Z

Dajt:

'''script.oos''' Used by [[OXP]]'s to check [[conditions]] and perform scripted [[methods|actions]] accordingly.

The "oos" file format allows scripts to be written using a more BASIC-like syntax than the plist file format permits. Scripts in "oos" format
have all the same features available as the plist scripts, except only one script per file can be defined.

If both script.plist and script.oos files exist in an OXP's Config directory, script.oos is loaded in preference to script.plist.

This format cannot be used in other plist files such as planetinfo.plist. It can only be used to replace script.plist.

== Structure ==

A script.oos file consists of the script name on the first non-comment, non-blank line, followed by one or more "if/then/else/endif" clauses.

Blank lines, leading and trailing whitespace, and lines starting with "//" are ignored.

The body of an "if/then" or "else" consists of one or more [[methods|actions]], one per line. Nested "if/then/else/endif" clauses may also be included in the actions.

A trivial script is:

<pre>
testscript
if dockedAtMainStation_bool = YES then
debugMessage: Player is docked at the main station.
else
debugMessage: Player is not docked at the main station.
endif
</pre>

An example of a nested if statement:
<pre>
testscript
if dockedAtMainStation_bool = YES then
debugMessage: Player is docked at the main station, now checking mission variable.
if mission_started undefined then
set: mission_started YES
// you would probably put up a mission page here
else
// the mission has already been started, do some stuff here
endif
endif
</pre>
=== Specifying "if" conditions ===

An "if" statement must be followed by one or more conditions. If multiple conditions are required they must be separated by the keyword "and". There is no option for an "or".

Where multiple conditions are specified they must all be true for the actions following "then" to be executed.

If any of the conditions of an "if" are false and an "else" clause is present, the actions given in the "else" clause are executed.

The form of the conditions is the same as for [[script.plist|conditions]], except that <, >, and = are used in place of the words lessthan, greaterthan, and equal.

<pre>
if X op Y [ and X op Y ] then
actions
else
actions
endif
</pre>

Where:
* X is one of mission_var, local_var, function_string, function_number, function_bool
* op is one of <, =, >, undefined, oneof
* Y is one of function_string, function_number, function_bool, or a set of one or more words

If op is "<" or ">" then Y should only be a single value and both X and Y are converted to numbers and compared.

If op is "=" then a string comparison is performed between X and Y. This is the only valid value for op when X is a function_bool and in this case Y must be one of "YES" or "NO".

If op is "undefined" then X must be a mission_var or local_var and Y is ignored. The condition is true if the mission or local variable has not yet been defined, or false if it has.

If op is "oneof" then Y is considered to be a list of values separated by commas and the condition is true if X is equal to any one of them.

Each condition is terminated by the word "and" or "then" and each condition can be on a separate line, for example:
<pre>
if mission_x = A and
mission_y = B then
// some actions here
endif
</pre>

=== Actions ===

If all the conditions in an "if" statement are met then the actions bounded by the "then" and the "else" or "endif" statement are executed. If any of the conditions in an "if" statement are not met and there is an "else" clause then the actions between the "else" and "endif" statement are executed.

Each action takes one line, and if finished by the end-of-line character(s).

The first word on an action line specifies the action to be performed. Some actions do not require any parameters, so the action line is a single word - "debugOn" for example. If the action requires any parameters, they are specified after a ":". There are examples of this above - "set" and "debugMessage".

Any word in the set of parameters surrounded by square brakets is assumed to be either a variable or the name of a function. If the word '''''starts''''' with mission_, local_, or commander_ it is assumed to be a variable and the variable's value replaces the variable name and the square brackets before the action is executed. If the word '''''ends''''' with _string, _number, or _bool it is assumed to be a function and the function's return value replaces the function name and the square brackets before the action is executed.

Some examples of actions with replacements:

// set the script local variable local_x to a number between 1 and 100
set: local_x [d100_number]

// then set the script local variable local_y to a number between 1 and 100
set: local_y [d100_number]

// and add local_x to it - notice local_y isn't in brackets because the first word has
// to be the name of the variable to be acted upon, not it's value
add: local_y [local_x]

// print a message to the log
debugMessage: Commander [commander_name] has [local_x] widgets and [local_y] twigs

Here is the longway.oxp script converted to oos format, with comments added:
<pre>
// Giles Williams' LongWay mission converted to oos format
//
long_way_round

// This is a pretty fast way to ensure no unnecessary processing is performed.
// This single condition can avoid all the other conditions getting evaluated
// if the player isn't in galaxy 0
//
if galaxy_number equal 0 then

// As above, this one condition can save evaluating the three enclosed conditions
// while the player is in space.
//
if dockedAtMainStation_bool equal YES then

// If the player docks at the main station at XXX then start the
// mission. Doesn't seem to be a way to refuse to do the mission.
//
if mission_longwayround undefined and planet_number equal 3 then
setMissionMusic: none
setGuiToMissionScreen
addMissionText: long_way_round_Biarge_briefing
set: mission_longwayround STAGE1
setMissionDescription: em1_short_desc1
endif

// If the player docks at the main station of YYY and they're doing
// the longway mission then reward them for partially completing it and
// send them on the next step.
//
if mission_longwayround equal STAGE1 and plaent_number equal 248 then
setMissionMusic: none
setGuiToMissionScreen
addMissionText: long_way_round_Soladies_briefing
awardCredits: 500
set: mission_longwayround STAGE2
setMissionDescription: em1_short_desc2
endif

// If the player docks at the main station of ZZZ and they're on the
// 2nd step of the mission, mark it complete and reward the player again.
//
if mission_longwayround equal STAGE2 and planet_number equal 233 then
setMissionMusic: none
setMissionImage: loyalistflag.png
setGuiToMissionScreen
addMissionText: long_way_round_Qubeen_briefing
awardCredits: 2000
setMissionImage: none
set: mission_longwayround MISSION_COMPLETE
clearMissionDescription
endif
endif

// If the player is on the second step of the mission and jumps in system ZZZ
// to complete the mission, ambush them with a couple of rebel ships!
//
if mission_longwayround equal STAGE2 and
planet_number equal 233 and
status_string equal STATUS_EXITING_WITCHSPACE then
addShips: rebel 2
endif

// Continually harass the player while they're in system ZZZ trying to finish
// the mission.
//
if mission_longwayround equal STAGE2 and
status_string equal STATUS_IN_FLIGHT and
planet_number equal 233 and
scriptTimer_number lessthan 60 then
checkForShips: rebel
if shipsFound_number lessthan 5 and d100_number lessthan 50 then
addShips: rebel 1
endif
endif
endif
</pre>

[[Category:Oolite]]

Methods

2006-04-05T06:53:23Z

Dajt:

'''Methods'''

Methods are the actions that are performed when conditions (defined in a script) are met, or when a particular set of actions (like ''[[Shipdata.plist#death_actions|death_actions]]'' or ''[[Shipdata.plist#script_actions|script_actions]]'') are called for, or when an AI calls for a script action to be performed.

All methods are stored in plists as strings (in XML this means between a <string> tag and a </string> closing tag). If they take any parameters then these follow a colon and a space (''': ''') after the 'command' part of the method.

For example: if the ship containing this ''death_actions'' entry is destroyed - the player gets a message and the sun goes Nova two seconds later!

<key>death_actions</key>
<array>
<string>commsMessage: Oh dear [commander_name]!</string>
<string>setSunNovaIn: 2.0</string>
</array>

== The Mission Screen ==

'''setGuiToMissionScreen'''
// opens the mission screen

'''addMissionText: <[[missiontext.plist]] key> '''
// adds text to the mission screen from an entry in [[missiontext.plist]]
// with the given key

'''showShipModel: <role>'''
// shows a rotating model of a ship with the role given
// role refers to a value in one of [[shipdata.plist]]'s entries'
// ''roles'' key value pair

'''setMissionMusic: <filename>'''
// plays the music file given
// if it exists within any OXP's ''Music'' folder

'''setMissionImage: <filename>'''
// displays the picture file given
// if it exists within any OXP's ''Images'' folder

'''setMissionChoices: <[[missiontext.plist]] key>'''
// sets the array of choices presented at the bottom of the mission page to those described in the
// entry in missiontext.plist that corresponds to the key given

'''resetMissionChoice'''
// makes missionChoice ''UNDEFINED''

'''setMissionDescription: <[[missiontext.plist]] key>'''
// sets the short description given on the player's manifest screen

'''clearMissionDescription'''
// clears the short description

'''resetScriptTimer'''
// resets a timer for scripting purposes '''deprecated - do not use''

== Star charts ==

'''addMissionDestination: <pnum>'''
// causes the given planets to be marked on the short and long range star charts
// multiple planet numbers may be supplied separated by spaces

'''removeMissionDestination: <pnum>'''
// causes the given planets to have their marks remove from the short and long range star charts
// multiple planet numbers may be supplied separated by spaces

== Looking for, and adding ships ==

'''checkForShips: <role>'''
// returns the number of ships found in the current system that match the role
// this number can be queried with [[Methods#Results_from_other_methods|'''shipsFound_number''']]

'''addShips: <role> <number>'''
// causes a number of ships matching the given role to appear near the withpoint

'''addSystemShips: <role> <number> <position>'''
// causes a number of ships matching the given role to appear near a point
// on a line from the witchpoint to the planet's station. <position> should be a floating point
// number where 0.0 represents the witchpoint and 1.0 represents the station

'''addShipsAt: <role> <number> <coordinate scheme> <x> <y> <z>'''
// causes a number of ships matching the given role to appear ''near'' a point
// defined by the <coordinate scheme> and the floating point coordinates x,y and z
// <coordinate scheme> consists of a three letter code:
//
// The first letter indicates the feature that is the origin of the coordinate system.
// w => witchpoint
// s => sun
// p => planet
//
// The next letter indicates the feature on the 'z' axis of the coordinate system.
// w => witchpoint
// s => sun
// p => planet
//
// Then the 'y' axis of the system is normal to the plane formed by the planet, sun and witchpoint.
// And the 'x' axis of the system is normal to the y and z axes.
// So:
// ps: z axis = (planet -> sun) y axis = normal to (planet - sun - witchpoint) x axis = normal to y and z axes
// pw: z axis = (planet -> witchpoint) y axis = normal to (planet - witchpoint - sun) x axis = normal to y and z axes
// sp: z axis = (sun -> planet) y axis = normal to (sun - planet - witchpoint) x axis = normal to y and z axes
// sw: z axis = (sun -> witchpoint) y axis = normal to (sun - witchpoint - planet) x axis = normal to y and z axes
// wp: z axis = (witchpoint -> planet) y axis = normal to (witchpoint - planet - sun) x axis = normal to y and z axes
// ws: z axis = (witchpoint -> sun) y axis = normal to (witchpoint - sun - planet) x axis = normal to y and z axes
//
// The third letter denotes the units used:
// m: meters
// p: planetary radii
// s: solar radii
// u: distance between first two features indicated (eg. spu means that u = distance from sun to the planet)
//
// in witchspace (== no sun) coordinates are absolute irrespective of the system used

'''addShipsAtPrecisely: <role> <number> <coordinate scheme> <x> <y> <z>'''
// This adds the ships as close as possible to the specified point

'''addShipsWithinRadius: <role> <number> <coordinate-system> <x> <y> <z> <radius in metres>'''
// Example:
// "addShipsWithinRadius: asteroid 48 wpm 0 0 15000 5000"
// would add a 5km-wide asteroid field with 48 asteroids at a position roughly 15000m towards
// the planet from the witchpoint.

'''spawn: <role> <number>'''
// adds a number of ships matching <role> near the ship
// that's the target of this script (as [[Shipdata.plist#script_actions|script_actions]] or [[Shipdata.plist#death_actions|death_actions]])

'''spawnShip: <[[shipdata.plist]] key>'''
// adds a ship with the unique [[shipdata.plist]] key given
// the position and facing of the ship are determined by a ''spawn'' dictionary in the
// ship's shipdata.plist entry with ''position'' and ''facing_position'' as strings describing
// coordinates according to one of the schemes above

== Changing the universe ==

'''setSunNovaIn: <seconds>'''
// Sets the sun to go nova after the given time in seconds

'''sendAllShipsAway'''
// Makes all the ships in the system hyperspace away

'''setPlanetinfo: <key>=<value>'''
// sets an override to the [[planetinfo.plist]] entry for the current system
// the value for the given key is set to match the value
// (see [[planetinfo.plist]])
//
// eg '''setPlanetinfo: description=a very dull planet'''
// (Note the '=' is required)

'''setSpecificPlanetInfo: <gnum>=<pnum>=<key>=<value>
// sets an override to the [[planetinfo.plist]] entry for the system
// specified by galaxy gnum and planet pnum
//
// eg '''setSpecificPlanetInfo: 0=7=description=Lave is not a very dull planet'''
// (Note the '=' is required between all 4 values)

'''addPlanet: <[[planetinfo.plist]] key>'''
// adds a planet to the universe from data in [[planetinfo.plist]].

'''addMoon: <[[planetinfo.plist]] key>'''
// adds a moon to the universe from data in [[planetinfo.plist]].
// (Moons do not get an atmosphere or clouds like planets).

== Mission Variables ==

As of 1.65? these methods can also be used with script local variables by suppling a
"local_" variable rather than a "mission_" varaible.

'''set: [[mission_variable]] <value>'''
// sets the [[mission_variable]] to the value given
// the value can be a particular string or numeric value,
// or a queriable state

'''reset: [[mission_variable]] <value>'''
// sets the [[mission_variable]] to be ''UNDEFINED''

'''increment: [[mission_variable]]'''
// increases the mission variable's value by 1.0

'''decrement: [[mission_variable]]'''
// decreases the mission variable's value by 1.0

'''add: [[mission_variable]] <value>'''
// adds the value given to the [[mission_variable]]
// the value can be a number or a queriable state
// like ''shipsFound_number''

'''subtract: [[mission_variable]] <value>'''
// subtracts the value given from the [[mission_variable]]
// the value can be a number or a queriable state
// like ''shipsFound_number''

== Player rewards and penalties==
These methods work on the player, not any other ship.

'''awardCredits: <number>'''
// awards number of tenths of credits.

'''awardShipKills: <number>'''
// Adds to the number of kills accredited to the player

'''setLegalStatus: <number>'''
// Sets the bounty on the player's head.

'''setFuelLeak: <amount>'''
// removes this amount from the fuel tank every second
// until the tanks drain and self-seal

'''awardFuel: <amount>'''
// The amount can be positive or negative, expressed in LY of range
// the fuel level is adjusted to a maximum of 7.0LY and minimum of 0.0.

=== Equipment ===

'''awardEquipment: <equipment key>'''
// if the player doesn't have the equipment already
// and their ship can be equipped witth it then this fits the
// player's ship with the equipment given
// valid keys can be found in [[equipment.plist]] (they all begin '''EQ_'''):-
// EQ_FUEL
// EQ_MISSILE
// EQ_CARGO_BAY
// EQ_ECM
// EQ_FUEL_SCOOPS
// EQ_ESCAPE_POD
// EQ_ENERGY_BOMB
// EQ_ENERGY_UNIT
// EQ_NAVAL_ENERGY_UNIT
// EQ_DOCK_COMP
// EQ_GAL_DRIVE
// EQ_CLOAKING_DEVICE
// EQ_PASSENGER_BERTH
// EQ_HARDENED_MISSILE
// EQ_FUEL_INJECTION
// EQ_SCANNER_SHOW_MISSILE_TARGET
// EQ_MULTI_TARGET
// EQ_ADVANCED_COMPASS
// EQ_QC_MINE
// EQ_SHIELD_BOOSTER
// EQ_NAVAL_SHIELD_BOOSTER
// EQ_WEAPON_TWIN_PLASMA_CANNON
// EQ_MILITARY_JAMMER
// EQ_MILITARY_SCANNER_FILTER

'''removeEquipment: <equipment key>'''
// removes the indicated equipment from the player's ship

'''testForEquipment: <equipment key>'''
// tests whether the player ship has a piece of equipment installed
// returns the result in [[Methods#Results_from_other_methods|'''foundEquipment_bool''']]

=== Cargo ===

'''awardCargo: <amount> <[[Commodities|Commodity]] name>'''
// awards a quantity of the cargo named
// the cargo name must match the name in [[commodities.plist]] exactly

'''removeAllCargo'''
// removes all cargo from the hold with no compensation to the player
// any special cargo is also removed (see below) restoring use of the cargo bay
// Gold, Platinum, and Gemstones are unaffected (they're in the cabin safe).

'''useSpecialCargo: <description of cargo>'''
// fills the cargo bay withthe cargo described effectively
// disabling the use of the cargo bay until the cargo is removed

=== Special ===

'''ejectItem: <[[shipdata.plist]] key>'''
// Creates a ship or other entity from [[shipdata.plist]] and ejects from
// the ship's aft hatch

'''launchFromStation'''
// forces the player ship to launch

== Communications ==

'''commsMessage: ''message'' '''
// sends the player a message
// if the message contains elements enclosed in square brackets ''[like_this]''
// that corresponds to a [[mission_variable]] or keys in [[descriptions.plist]]
// or to special expansions like [commander_name] then these are expanded
// and substituted into the original message

== Querying states ==

=== Player status ===

// '''mission_string'''
// returns the key for the current mission

// '''status_string'''
// returns one of:
// ''STATUS_AUTOPILOT_ENGAGED''
// ''STATUS_DEAD''
// ''STATUS_DEMO''
// ''STATUS_DOCKING''
// ''STATUS_DOCKED''
// ''STATUS_EFFECT''
// ''STATUS_ENTERING_WITCHSPACE''
// ''STATUS_ESCAPE_SEQUENCE''
// ''STATUS_EXITING_WITCHSPACE''
// ''STATUS_EXPERIMENTAL''
// ''STATUS_IN_FLIGHT''
// ''STATUS_IN_HOLD''
// ''STATUS_INACTIVE''
// ''STATUS_LAUNCHING''
// ''STATUS_TEST''
// ''STATUS_WITCHSPACE_COUNTDOWN''
// ''UNDEFINED''

// '''gui_screen_string'''
// returns one of:
// ''GUI_SCREEN_EQUIP_SHIP''
// ''GUI_SCREEN_INTRO1''
// ''GUI_SCREEN_INTRO2''
// ''GUI_SCREEN_INVENTORY''
// ''GUI_SCREEN_LONG_RANGE_CHART''
// ''GUI_SCREEN_MAIN''
// ''GUI_SCREEN_MARKET''
// ''GUI_SCREEN_MISSION''
// ''GUI_SCREEN_OPTIONS''
// ''GUI_SCREEN_SHORT_RANGE_CHART''
// ''GUI_SCREEN_STATUS''
// ''GUI_SCREEN_SYSTEM_DATA''
// ''UNDEFINED''

// '''galaxy_number'''
// returns a value between 0 and 7

// '''planet_number'''
// returns a value between 0 and 255

// '''score_number'''
// returns the number of the player's current ship kills

// '''credits_number'''
// returns the player's credits x10

// '''legalStatus_number'''
// returns the bounty on the players head

// '''fuel_level_number'''
// returns the fuel level in LY

// '''dockedAtMainStation_bool'''
// returns ''YES'' if docked at a systems main station, ''NO'' otherwise

// '''dockedStationName_string'''
// returns ''NONE'' if the player isn't docked, the name of the station (from [[shipdata.plist]]) if it is, ''UNKNOWN'' otherwise

=== Results from other methods ===

// '''shipsFound_number'''
// returns the number of ships found by ''checkForShips:''

// '''foundEquipment_bool'''
// returns the result of the last ''testForEquipment''
// returns ''YES'' if the equipment was found, ''NO'' otherwise

// '''missionChoice_string'''
// returns the result of the player's selection from a list of missionChoices
// returns ''UNDEFINED'' or the key for the chosen option

=== Random numbers ===

// '''d100_number'''
// returns a random value from 0 to 99

// '''pseudoFixedD100_number'''
// returns a random number from 0 to 99 that will
// remain fixed as long as the player remains in this system

=== Time ===

// '''clock_number'''
// returns the game time in seconds
// '''clock_secs_number'''
// returns the game time in seconds
// '''clock_mins_number'''
// returns the game time in minutes
// '''clock_hours_number'''
// returns the game time in hours
// '''clock_days_number'''
// returns the game time in days

=== System states ===

// '''sunWillGoNova_bool'''
// returns whether the sun is going to go nova, either ''YES'' or ''NO''

// '''sunGoneNova_bool'''
// returns whether the sun has gone nova, either ''YES'' or ''NO''

// '''systemGovernment_string'''
// returns one of:-
// ''Anarchy''
// ''Feudal''
// ''Multi-Government''
// ''Dictatorship''
// ''Communist''
// ''Confederacy''
// ''Democracy''
// ''Corporate State''

// '''systemGovernment_number'''
// returns a value from 0 to 7

// '''systemEconomy_number'''
// returns a value from 0 to 7

// '''systemTechLevel_number'''
// returns a value from 0 to 14

// '''systemPopulation_number'''
// returns a value representing the system's population

// '''systemProductivity_number'''
// returns a value representing the system's productivity

// '''scriptTimer_number'''
// returns the script timer's current value in seconds '''(deprecated - do not use)'''

== Debugging scripts ==

'''debugOn'''
// sends script debugging messages to the console.

'''debugOff'''
// cancels script debugging messages

'''debugMessage: <message>'''
// sends the given message to the console. The message is written to the console regardless
// of whether debugOn has been performed or not. For GNUstep versions of Oolite, the console
// is a file called stderr.txt located in the game's installation directory. Mission variables
// and queriable states may be included in the message, eg:
//
// ''debugMessage: current galaxy is galaxy_number''

== AI ==

Note that although most of these methods affect the player, some can also be utilised by an AI.
*[[OXP howto AI]].

[[Category:Oolite]]

Methods

2006-04-05T06:45:15Z

Dajt: /* Changing the universe */

'''Methods'''

Methods are the actions that are performed when conditions (defined in a script) are met, or when a particular set of actions (like ''[[Shipdata.plist#death_actions|death_actions]]'' or ''[[Shipdata.plist#script_actions|script_actions]]'') are called for, or when an AI calls for a script action to be performed.

All methods are stored in plists as strings (in XML this means between a <string> tag and a </string> closing tag). If they take any parameters then these follow a colon and a space (''': ''') after the 'command' part of the method.

For example: if the ship containing this ''death_actions'' entry is destroyed - the player gets a message and the sun goes Nova two seconds later!

<key>death_actions</key>
<array>
<string>commsMessage: Oh dear [commander_name]!</string>
<string>setSunNovaIn: 2.0</string>
</array>

== The Mission Screen ==

'''setGuiToMissionScreen'''
// opens the mission screen

'''addMissionText: <[[missiontext.plist]] key> '''
// adds text to the mission screen from an entry in [[missiontext.plist]]
// with the given key

'''showShipModel: <role>'''
// shows a rotating model of a ship with the role given
// role refers to a value in one of [[shipdata.plist]]'s entries'
// ''roles'' key value pair

'''setMissionMusic: <filename>'''
// plays the music file given
// if it exists within any OXP's ''Music'' folder

'''setMissionImage: <filename>'''
// displays the picture file given
// if it exists within any OXP's ''Images'' folder

'''setMissionChoices: <[[missiontext.plist]] key>'''
// sets the array of choices presented at the bottom of the mission page to those described in the
// entry in missiontext.plist that corresponds to the key given

'''resetMissionChoice'''
// makes missionChoice ''UNDEFINED''

'''setMissionDescription: <[[missiontext.plist]] key>'''
// sets the short description given on the player's manifest screen

'''clearMissionDescription'''
// clears the short description

'''resetScriptTimer'''
// resets a timer for scripting purposes '''deprecated - do not use''

== Looking for, and adding ships ==

'''checkForShips: <role>'''
// returns the number of ships found in the current system that match the role
// this number can be queried with [[Methods#Results_from_other_methods|'''shipsFound_number''']]

'''addShips: <role> <number>'''
// causes a number of ships matching the given role to appear near the withpoint

'''addSystemShips: <role> <number> <position>'''
// causes a number of ships matching the given role to appear near a point
// on a line from the witchpoint to the planet's station. <position> should be a floating point
// number where 0.0 represents the witchpoint and 1.0 represents the station

'''addShipsAt: <role> <number> <coordinate scheme> <x> <y> <z>'''
// causes a number of ships matching the given role to appear ''near'' a point
// defined by the <coordinate scheme> and the floating point coordinates x,y and z
// <coordinate scheme> consists of a three letter code:
//
// The first letter indicates the feature that is the origin of the coordinate system.
// w => witchpoint
// s => sun
// p => planet
//
// The next letter indicates the feature on the 'z' axis of the coordinate system.
// w => witchpoint
// s => sun
// p => planet
//
// Then the 'y' axis of the system is normal to the plane formed by the planet, sun and witchpoint.
// And the 'x' axis of the system is normal to the y and z axes.
// So:
// ps: z axis = (planet -> sun) y axis = normal to (planet - sun - witchpoint) x axis = normal to y and z axes
// pw: z axis = (planet -> witchpoint) y axis = normal to (planet - witchpoint - sun) x axis = normal to y and z axes
// sp: z axis = (sun -> planet) y axis = normal to (sun - planet - witchpoint) x axis = normal to y and z axes
// sw: z axis = (sun -> witchpoint) y axis = normal to (sun - witchpoint - planet) x axis = normal to y and z axes
// wp: z axis = (witchpoint -> planet) y axis = normal to (witchpoint - planet - sun) x axis = normal to y and z axes
// ws: z axis = (witchpoint -> sun) y axis = normal to (witchpoint - sun - planet) x axis = normal to y and z axes
//
// The third letter denotes the units used:
// m: meters
// p: planetary radii
// s: solar radii
// u: distance between first two features indicated (eg. spu means that u = distance from sun to the planet)
//
// in witchspace (== no sun) coordinates are absolute irrespective of the system used

'''addShipsAtPrecisely: <role> <number> <coordinate scheme> <x> <y> <z>'''
// This adds the ships as close as possible to the specified point

'''addShipsWithinRadius: <role> <number> <coordinate-system> <x> <y> <z> <radius in metres>'''
// Example:
// "addShipsWithinRadius: asteroid 48 wpm 0 0 15000 5000"
// would add a 5km-wide asteroid field with 48 asteroids at a position roughly 15000m towards
// the planet from the witchpoint.

'''spawn: <role> <number>'''
// adds a number of ships matching <role> near the ship
// that's the target of this script (as [[Shipdata.plist#script_actions|script_actions]] or [[Shipdata.plist#death_actions|death_actions]])

'''spawnShip: <[[shipdata.plist]] key>'''
// adds a ship with the unique [[shipdata.plist]] key given
// the position and facing of the ship are determined by a ''spawn'' dictionary in the
// ship's shipdata.plist entry with ''position'' and ''facing_position'' as strings describing
// coordinates according to one of the schemes above

== Changing the universe ==

'''setSunNovaIn: <seconds>'''
// Sets the sun to go nova after the given time in seconds

'''sendAllShipsAway'''
// Makes all the ships in the system hyperspace away

'''setPlanetinfo: <key>=<value>'''
// sets an override to the [[planetinfo.plist]] entry for the current system
// the value for the given key is set to match the value
// (see [[planetinfo.plist]])
//
// eg '''setPlanetinfo: description=a very dull planet'''
// (Note the '=' is required)

'''setSpecificPlanetInfo: <gnum>=<pnum>=<key>=<value>
// sets an override to the [[planetinfo.plist]] entry for the system
// specified by galaxy gnum and planet pnum
//
// eg '''setSpecificPlanetInfo: 0=7=description=Lave is not a very dull planet'''
// (Note the '=' is required between all 4 values)

'''addPlanet: <[[planetinfo.plist]] key>'''
// adds a planet to the universe from data in [[planetinfo.plist]].

'''addMoon: <[[planetinfo.plist]] key>'''
// adds a moon to the universe from data in [[planetinfo.plist]].
// (Moons do not get an atmosphere or clouds like planets).

== Mission Variables ==

'''set: [[mission_variable]] <value>'''
// sets the [[mission_variable]] to the value given
// the value can be a particular string or numeric value,
// or a queriable state

'''reset: [[mission_variable]] <value>'''
// sets the [[mission_variable]] to be ''UNDEFINED''

'''increment: [[mission_variable]]'''
// increases the mission variable's value by 1.0

'''decrement: [[mission_variable]]'''
// decreases the mission variable's value by 1.0

'''add: [[mission_variable]] <value>'''
// adds the value given to the [[mission_variable]]
// the value can be a number or a queriable state
// like ''shipsFound_number''

'''subtract: [[mission_variable]] <value>'''
// subtracts the value given from the [[mission_variable]]
// the value can be a number or a queriable state
// like ''shipsFound_number''

== Player rewards and penalties==
These methods work on the player, not any other ship.

'''awardCredits: <number>'''
// awards number of tenths of credits.

'''awardShipKills: <number>'''
// Adds to the number of kills accredited to the player

'''setLegalStatus: <number>'''
// Sets the bounty on the player's head.

'''setFuelLeak: <amount>'''
// removes this amount from the fuel tank every second
// until the tanks drain and self-seal

'''awardFuel: <amount>'''
// The amount can be positive or negative, expressed in LY of range
// the fuel level is adjusted to a maximum of 7.0LY and minimum of 0.0.

=== Equipment ===

'''awardEquipment: <equipment key>'''
// if the player doesn't have the equipment already
// and their ship can be equipped witth it then this fits the
// player's ship with the equipment given
// valid keys can be found in [[equipment.plist]] (they all begin '''EQ_'''):-
// EQ_FUEL
// EQ_MISSILE
// EQ_CARGO_BAY
// EQ_ECM
// EQ_FUEL_SCOOPS
// EQ_ESCAPE_POD
// EQ_ENERGY_BOMB
// EQ_ENERGY_UNIT
// EQ_NAVAL_ENERGY_UNIT
// EQ_DOCK_COMP
// EQ_GAL_DRIVE
// EQ_CLOAKING_DEVICE
// EQ_PASSENGER_BERTH
// EQ_HARDENED_MISSILE
// EQ_FUEL_INJECTION
// EQ_SCANNER_SHOW_MISSILE_TARGET
// EQ_MULTI_TARGET
// EQ_ADVANCED_COMPASS
// EQ_QC_MINE
// EQ_SHIELD_BOOSTER
// EQ_NAVAL_SHIELD_BOOSTER
// EQ_WEAPON_TWIN_PLASMA_CANNON
// EQ_MILITARY_JAMMER
// EQ_MILITARY_SCANNER_FILTER

'''removeEquipment: <equipment key>'''
// removes the indicated equipment from the player's ship

'''testForEquipment: <equipment key>'''
// tests whether the player ship has a piece of equipment installed
// returns the result in [[Methods#Results_from_other_methods|'''foundEquipment_bool''']]

=== Cargo ===

'''awardCargo: <amount> <[[Commodities|Commodity]] name>'''
// awards a quantity of the cargo named
// the cargo name must match the name in [[commodities.plist]] exactly

'''removeAllCargo'''
// removes all cargo from the hold with no compensation to the player
// any special cargo is also removed (see below) restoring use of the cargo bay
// Gold, Platinum, and Gemstones are unaffected (they're in the cabin safe).

'''useSpecialCargo: <description of cargo>'''
// fills the cargo bay withthe cargo described effectively
// disabling the use of the cargo bay until the cargo is removed

=== Special ===

'''ejectItem: <[[shipdata.plist]] key>'''
// Creates a ship or other entity from [[shipdata.plist]] and ejects from
// the ship's aft hatch

'''launchFromStation'''
// forces the player ship to launch

== Communications ==

'''commsMessage: ''message'' '''
// sends the player a message
// if the message contains elements enclosed in square brackets ''[like_this]''
// that corresponds to a [[mission_variable]] or keys in [[descriptions.plist]]
// or to special expansions like [commander_name] then these are expanded
// and substituted into the original message

== Querying states ==

=== Player status ===

// '''mission_string'''
// returns the key for the current mission

// '''status_string'''
// returns one of:
// ''STATUS_AUTOPILOT_ENGAGED''
// ''STATUS_DEAD''
// ''STATUS_DEMO''
// ''STATUS_DOCKING''
// ''STATUS_DOCKED''
// ''STATUS_EFFECT''
// ''STATUS_ENTERING_WITCHSPACE''
// ''STATUS_ESCAPE_SEQUENCE''
// ''STATUS_EXITING_WITCHSPACE''
// ''STATUS_EXPERIMENTAL''
// ''STATUS_IN_FLIGHT''
// ''STATUS_IN_HOLD''
// ''STATUS_INACTIVE''
// ''STATUS_LAUNCHING''
// ''STATUS_TEST''
// ''STATUS_WITCHSPACE_COUNTDOWN''
// ''UNDEFINED''

// '''gui_screen_string'''
// returns one of:
// ''GUI_SCREEN_EQUIP_SHIP''
// ''GUI_SCREEN_INTRO1''
// ''GUI_SCREEN_INTRO2''
// ''GUI_SCREEN_INVENTORY''
// ''GUI_SCREEN_LONG_RANGE_CHART''
// ''GUI_SCREEN_MAIN''
// ''GUI_SCREEN_MARKET''
// ''GUI_SCREEN_MISSION''
// ''GUI_SCREEN_OPTIONS''
// ''GUI_SCREEN_SHORT_RANGE_CHART''
// ''GUI_SCREEN_STATUS''
// ''GUI_SCREEN_SYSTEM_DATA''
// ''UNDEFINED''

// '''galaxy_number'''
// returns a value between 0 and 7

// '''planet_number'''
// returns a value between 0 and 255

// '''score_number'''
// returns the number of the player's current ship kills

// '''credits_number'''
// returns the player's credits x10

// '''legalStatus_number'''
// returns the bounty on the players head

// '''fuel_level_number'''
// returns the fuel level in LY

// '''dockedAtMainStation_bool'''
// returns ''YES'' if docked at a systems main station, ''NO'' otherwise

// '''dockedStationName_string'''
// returns ''NONE'' if the player isn't docked, the name of the station (from [[shipdata.plist]]) if it is, ''UNKNOWN'' otherwise

=== Results from other methods ===

// '''shipsFound_number'''
// returns the number of ships found by ''checkForShips:''

// '''foundEquipment_bool'''
// returns the result of the last ''testForEquipment''
// returns ''YES'' if the equipment was found, ''NO'' otherwise

// '''missionChoice_string'''
// returns the result of the player's selection from a list of missionChoices
// returns ''UNDEFINED'' or the key for the chosen option

=== Random numbers ===

// '''d100_number'''
// returns a random value from 0 to 99

// '''pseudoFixedD100_number'''
// returns a random number from 0 to 99 that will
// remain fixed as long as the player remains in this system

=== Time ===

// '''clock_number'''
// returns the game time in seconds
// '''clock_secs_number'''
// returns the game time in seconds
// '''clock_mins_number'''
// returns the game time in minutes
// '''clock_hours_number'''
// returns the game time in hours
// '''clock_days_number'''
// returns the game time in days

=== System states ===

// '''sunWillGoNova_bool'''
// returns whether the sun is going to go nova, either ''YES'' or ''NO''

// '''sunGoneNova_bool'''
// returns whether the sun has gone nova, either ''YES'' or ''NO''

// '''systemGovernment_string'''
// returns one of:-
// ''Anarchy''
// ''Feudal''
// ''Multi-Government''
// ''Dictatorship''
// ''Communist''
// ''Confederacy''
// ''Democracy''
// ''Corporate State''

// '''systemGovernment_number'''
// returns a value from 0 to 7

// '''systemEconomy_number'''
// returns a value from 0 to 7

// '''systemTechLevel_number'''
// returns a value from 0 to 14

// '''systemPopulation_number'''
// returns a value representing the system's population

// '''systemProductivity_number'''
// returns a value representing the system's productivity

// '''scriptTimer_number'''
// returns the script timer's current value in seconds '''(deprecated - do not use)'''

== Debugging scripts ==

'''debugOn'''
// sends script debugging messages to the console.

'''debugOff'''
// cancels script debugging messages

'''debugMessage: <message>'''
// sends the given message to the console. The message is written to the console regardless
// of whether debugOn has been performed or not. For GNUstep versions of Oolite, the console
// is a file called stderr.txt located in the game's installation directory. Mission variables
// and queriable states may be included in the message, eg:
//
// ''debugMessage: current galaxy is galaxy_number''

== AI ==

Note that although most of these methods affect the player, some can also be utilised by an AI.
*[[OXP howto AI]].

[[Category:Oolite]]

Script.oos

2006-04-05T06:41:09Z

Dajt: /* Actions */

'''script.oos''' Used by [[OXP]]'s to check [[conditions]] and perform scripted [[methods|actions]] accordingly.

The "oos" file format allows scripts to be written using a more BASIC-like syntax than the plist file format permits. Scripts in "oos" format
have all the same features available as the plist scripts, except only one script per file can be defined.

If both script.plist and script.oos files exist in an OXP's Config directory, script.oos is loaded in preference to script.plist.

== Structure ==

A script.oos file consists of the script name on the first non-comment, non-blank line, followed by one or more "if/then/else/endif" clauses.

Blank lines, leading and trailing whitespace, and lines starting with "//" are ignored.

The body of an "if/then" or "else" consists of one or more [[methods|actions]], one per line. Nested "if/then/else/endif" clauses may also be included in the actions.

A trivial script is:

<pre>
testscript
if dockedAtMainStation_bool = YES then
debugMessage: Player is docked at the main station.
else
debugMessage: Player is not docked at the main station.
endif
</pre>

An example of a nested if statement:
<pre>
testscript
if dockedAtMainStation_bool = YES then
debugMessage: Player is docked at the main station, now checking mission variable.
if mission_started undefined then
set: mission_started YES
// you would probably put up a mission page here
else
// the mission has already been started, do some stuff here
endif
endif
</pre>
=== Specifying "if" conditions ===

An "if" statement must be followed by one or more conditions. If multiple conditions are required they must be separated by the keyword "and". There is no option for an "or".

Where multiple conditions are specified they must all be true for the actions following "then" to be executed.

If any of the conditions of an "if" are false and an "else" clause is present, the actions given in the "else" clause are executed.

The form of the conditions is the same as for [[script.plist|conditions]], except that <, >, and = are used in place of the words lessthan, greaterthan, and equal.

<pre>
if X op Y [ and X op Y ] then
actions
else
actions
endif
</pre>

Where:
* X is one of mission_var, local_var, function_string, function_number, function_bool
* op is one of <, =, >, undefined, oneof
* Y is one of function_string, function_number, function_bool, or a set of one or more words

If op is "<" or ">" then Y should only be a single value and both X and Y are converted to numbers and compared.

If op is "=" then a string comparison is performed between X and Y. This is the only valid value for op when X is a function_bool and in this case Y must be one of "YES" or "NO".

If op is "undefined" then X must be a mission_var or local_var and Y is ignored. The condition is true if the mission or local variable has not yet been defined, or false if it has.

If op is "oneof" then Y is considered to be a list of values separated by commas and the condition is true if X is equal to any one of them.

Each condition is terminated by the word "and" or "then" and each condition can be on a separate line, for example:
<pre>
if mission_x = A and
mission_y = B then
// some actions here
endif
</pre>

=== Actions ===

If all the conditions in an "if" statement are met then the actions bounded by the "then" and the "else" or "endif" statement are executed. If any of the conditions in an "if" statement are not met and there is an "else" clause then the actions between the "else" and "endif" statement are executed.

Each action takes one line, and if finished by the end-of-line character(s).

The first word on an action line specifies the action to be performed. Some actions do not require any parameters, so the action line is a single word - "debugOn" for example. If the action requires any parameters, they are specified after a ":". There are examples of this above - "set" and "debugMessage".

Any word in the set of parameters surrounded by square brakets is assumed to be either a variable or the name of a function. If the word '''''starts''''' with mission_, local_, or commander_ it is assumed to be a variable and the variable's value replaces the variable name and the square brackets before the action is executed. If the word '''''ends''''' with _string, _number, or _bool it is assumed to be a function and the function's return value replaces the function name and the square brackets before the action is executed.

Some examples of actions with replacements:

// set the script local variable local_x to a number between 1 and 100
set: local_x [d100_number]

// then set the script local variable local_y to a number between 1 and 100
set: local_y [d100_number]

// and add local_x to it - notice local_y isn't in brackets because the first word has
// to be the name of the variable to be acted upon, not it's value
add: local_y [local_x]

// print a message to the log
debugMessage: Commander [commander_name] has [local_x] widgets and [local_y] twigs

Here is the longway.oxp script converted to oos format, with comments added:
<pre>
// Giles Williams' LongWay mission converted to oos format
//
long_way_round

// This is a pretty fast way to ensure no unnecessary processing is performed.
// This single condition can avoid all the other conditions getting evaluated
// if the player isn't in galaxy 0
//
if galaxy_number equal 0 then

// As above, this one condition can save evaluating the three enclosed conditions
// while the player is in space.
//
if dockedAtMainStation_bool equal YES then

// If the player docks at the main station at XXX then start the
// mission. Doesn't seem to be a way to refuse to do the mission.
//
if mission_longwayround undefined and planet_number equal 3 then
setMissionMusic: none
setGuiToMissionScreen
addMissionText: long_way_round_Biarge_briefing
set: mission_longwayround STAGE1
setMissionDescription: em1_short_desc1
endif

// If the player docks at the main station of YYY and they're doing
// the longway mission then reward them for partially completing it and
// send them on the next step.
//
if mission_longwayround equal STAGE1 and plaent_number equal 248 then
setMissionMusic: none
setGuiToMissionScreen
addMissionText: long_way_round_Soladies_briefing
awardCredits: 500
set: mission_longwayround STAGE2
setMissionDescription: em1_short_desc2
endif

// If the player docks at the main station of ZZZ and they're on the
// 2nd step of the mission, mark it complete and reward the player again.
//
if mission_longwayround equal STAGE2 and planet_number equal 233 then
setMissionMusic: none
setMissionImage: loyalistflag.png
setGuiToMissionScreen
addMissionText: long_way_round_Qubeen_briefing
awardCredits: 2000
setMissionImage: none
set: mission_longwayround MISSION_COMPLETE
clearMissionDescription
endif
endif

// If the player is on the second step of the mission and jumps in system ZZZ
// to complete the mission, ambush them with a couple of rebel ships!
//
if mission_longwayround equal STAGE2 and
planet_number equal 233 and
status_string equal STATUS_EXITING_WITCHSPACE then
addShips: rebel 2
endif

// Continually harass the player while they're in system ZZZ trying to finish
// the mission.
//
if mission_longwayround equal STAGE2 and
status_string equal STATUS_IN_FLIGHT and
planet_number equal 233 and
scriptTimer_number lessthan 60 then
checkForShips: rebel
if shipsFound_number lessthan 5 and d100_number lessthan 50 then
addShips: rebel 1
endif
endif
endif
</pre>

[[Category:Oolite]]

Script.oos

2006-04-05T06:40:22Z

Dajt: /* Structure */

'''script.oos''' Used by [[OXP]]'s to check [[conditions]] and perform scripted [[methods|actions]] accordingly.

The "oos" file format allows scripts to be written using a more BASIC-like syntax than the plist file format permits. Scripts in "oos" format
have all the same features available as the plist scripts, except only one script per file can be defined.

If both script.plist and script.oos files exist in an OXP's Config directory, script.oos is loaded in preference to script.plist.

== Structure ==

A script.oos file consists of the script name on the first non-comment, non-blank line, followed by one or more "if/then/else/endif" clauses.

Blank lines, leading and trailing whitespace, and lines starting with "//" are ignored.

The body of an "if/then" or "else" consists of one or more [[methods|actions]], one per line. Nested "if/then/else/endif" clauses may also be included in the actions.

A trivial script is:

<pre>
testscript
if dockedAtMainStation_bool = YES then
debugMessage: Player is docked at the main station.
else
debugMessage: Player is not docked at the main station.
endif
</pre>

An example of a nested if statement:
<pre>
testscript
if dockedAtMainStation_bool = YES then
debugMessage: Player is docked at the main station, now checking mission variable.
if mission_started undefined then
set: mission_started YES
// you would probably put up a mission page here
else
// the mission has already been started, do some stuff here
endif
endif
</pre>
=== Specifying "if" conditions ===

An "if" statement must be followed by one or more conditions. If multiple conditions are required they must be separated by the keyword "and". There is no option for an "or".

Where multiple conditions are specified they must all be true for the actions following "then" to be executed.

If any of the conditions of an "if" are false and an "else" clause is present, the actions given in the "else" clause are executed.

The form of the conditions is the same as for [[script.plist|conditions]], except that <, >, and = are used in place of the words lessthan, greaterthan, and equal.

<pre>
if X op Y [ and X op Y ] then
actions
else
actions
endif
</pre>

Where:
* X is one of mission_var, local_var, function_string, function_number, function_bool
* op is one of <, =, >, undefined, oneof
* Y is one of function_string, function_number, function_bool, or a set of one or more words

If op is "<" or ">" then Y should only be a single value and both X and Y are converted to numbers and compared.

If op is "=" then a string comparison is performed between X and Y. This is the only valid value for op when X is a function_bool and in this case Y must be one of "YES" or "NO".

If op is "undefined" then X must be a mission_var or local_var and Y is ignored. The condition is true if the mission or local variable has not yet been defined, or false if it has.

If op is "oneof" then Y is considered to be a list of values separated by commas and the condition is true if X is equal to any one of them.

Each condition is terminated by the word "and" or "then" and each condition can be on a separate line, for example:
<pre>
if mission_x = A and
mission_y = B then
// some actions here
endif
</pre>

=== Actions ===

If all the conditions in an "if" statement are met then the actions bounded by the "then" and the "else" or "endif" statement are executed. If any of the conditions in an "if" statement are not met and there is an "else" clause then the actions between the "else" and "endif" statement are executed.

Each action takes one line, and if finished by the end-of-line character(s).

The first word on an action line specifies the action to be performed. Some actions do not require any parameters, so the action line is a single word - "debugOn" for example. If the action requires any parameters, they are specified after a ":". There are examples of this above - "set" and "debugMessage".

Any word in the set of parameters surrounded by square brakets is assumed to be either a variable or the name of a function. If the word '''''starts''''' with mission_, local_, or commander_ it is assumed to be a variable and the variable's value replaces the variable name and the square brackets before the action is executed. If the word '''''ends''''' with _string, _number, or _bool it is assumed to be a function and the function's return value replaces the function name and the square brackets before the action is executed.

Some examples of actions with replacements:

// set the script local variable local_x to a number between 1 and 100
set: local_x [d100_number]

// then set the script local variable local_y to a number between 1 and 100
set: local_y [d100_number]

// and add local_x to it - notice local_y isn't in brackets because the first word has
// to be the name of the variable to be acted upon, not it's value
add: local_y [local_x]

// print a message to the log
debugMessage: Commander [commander_name] has [local_x] widgets and [local_y] twigs

Here is the longway.oxp script converted to oos format, with comments added:
<pre>
// Giles Williams' LongWay mission converted to oos format
//
long_way_round

// This is a pretty fast way to ensure no unnecessary processing is performed.
// This single condition can avoid all the other conditions getting evaluated
// if the player isn't in galaxy 0
//
if galaxy_number equal 0 then

// As above, this one condition can save evaluating the three enclosed conditions
// while the player is in space.
//
if dockedAtMainStation_bool equal YES then

// If the player docks at the main station at XXX then start the
// mission. Doesn't seem to be a way to refuse to do the mission.
//
if mission_longwayround undefined and planet_number equal 3 then
setMissionMusic: none
setGuiToMissionScreen
addMissionText: long_way_round_Biarge_briefing
set: mission_longwayround STAGE1
setMissionDescription: em1_short_desc1
endif

// If the player docks at the main station of YYY and they're doing
// the longway mission then reward them for partially completing it and
// send them on the next step.
//
if mission_longwayround equal STAGE1 and plaent_number equal 248 then
setMissionMusic: none
setGuiToMissionScreen
addMissionText: long_way_round_Soladies_briefing
awardCredits: 500
set: mission_longwayround STAGE2
setMissionDescription: em1_short_desc2
endif

// If the player docks at the main station of ZZZ and they're on the
// 2nd step of the mission, mark it complete and reward the player again.
//
if mission_longwayround equal STAGE2 and planet_number equal 233 then
setMissionMusic: none
setMissionImage: loyalistflag.png
setGuiToMissionScreen
addMissionText: long_way_round_Qubeen_briefing
awardCredits: 2000
setMissionImage: none
set: mission_longwayround MISSION_COMPLETE
clearMissionDescription
endif
endif

// If the player is on the second step of the mission and jumps in system ZZZ
// to complete the mission, ambush them with a couple of rebel ships!
//
if mission_longwayround equal STAGE2 and
planet_number equal 233 and
status_string equal STATUS_EXITING_WITCHSPACE then
addShips: rebel 2
endif

// Continually harass the player while they're in system ZZZ trying to finish
// the mission.
//
if mission_longwayround equal STAGE2 and
status_string equal STATUS_IN_FLIGHT and
planet_number equal 233 and
scriptTimer_number lessthan 60 then
checkForShips: rebel
if shipsFound_number lessthan 5 and d100_number lessthan 50 then
addShips: rebel 1
endif
endif
endif
</pre>

[[Category:Oolite]]

Script.oos

2006-04-05T06:29:14Z

Dajt: /* Structure */

'''script.oos''' Used by [[OXP]]'s to check [[conditions]] and perform scripted [[methods|actions]] accordingly.

The "oos" file format allows scripts to be written using a more BASIC-like syntax than the plist file format permits. Scripts in "oos" format
have all the same features available as the plist scripts, except only one script per file can be defined.

If both script.plist and script.oos files exist in an OXP's Config directory, script.oos is loaded in preference to script.plist.

== Structure ==

A script.oos file consists of the script name on the first non-comment, non-blank line, followed by one or more "if/then/else/endif" clauses.

Blank lines, leading and trailing whitespace, and lines starting with "//" are ignored.

The body of an "if/then" or "else" consists of one or more [[methods|actions]], one per line. Nested "if/then/else/endif" clauses may also be included in the actions.

A trivial script is:

<pre>
testscript
if dockedAtMainStation_bool = YES then
debugMessage: Player is docked at the main station.
else
debugMessage: Player is not docked at the main station.
endif
</pre>

An example of a nested if statement:
<pre>
testscript
if dockedAtMainStation_bool = YES then
debugMessage: Player is docked at the main station, now checking mission variable.
if mission_started undefined then
set: mission_started YES
// you would probably put up a mission page here
else
// the mission has already been started, do some stuff here
endif
endif
</pre>
=== Specifying "if" conditions ===

An "if" statement must be followed by one or more conditions. If multiple conditions are required they must be separated by the keyword "and". There is no option for an "or".

Where multiple conditions are specified they must all be true for the actions following "then" to be executed.

If any of the conditions of an "if" are false and an "else" clause is present, the actions given in the "else" clause are executed.

The form of the conditions is the same as for [[script.plist|conditions]], except that <, >, and = are used in place of the words lessthan, greaterthan, and equal.

<pre>
if X op Y [ and X op Y ] then
actions
else
actions
endif
</pre>

Where:
* X is one of mission_var, local_var, function_string, function_number, function_bool
* op is one of <, =, >, undefined, oneof
* Y is one of function_string, function_number, function_bool, or a set of one or more words

If op is "<" or ">" then Y should only be a single value and both X and Y are converted to numbers and compared.

If op is "=" then a string comparison is performed between X and Y. This is the only valid value for op when X is a function_bool and in this case Y must be one of "YES" or "NO".

If op is "undefined" then X must be a mission_var or local_var and Y is ignored. The condition is true if the mission or local variable has not yet been defined, or false if it has.

If op is "oneof" then Y is considered to be a list of values separated by commas and the condition is true if X is equal to any one of them.

Each condition is terminated by the word "and" or "then" and each condition can be on a separate line, for example:
<pre>
if mission_x = A and
mission_y = B then
// some actions here
endif
</pre>

=== Actions ===

If all the conditions in an "if" statement are met then the actions bounded by the "then" and the "else" or "endif" statement are executed. If any of the conditions in an "if" statement are not met and there is an "else" clause then the actions between the "else" and "endif" statement are executed.

Each action takes one line, and if finished by the end-of-line character(s).

The first word on an action line specifies the action to be performed. Some actions do not require any parameters, so the action line is a single word - "debugOn" for example. If the action requires any parameters, they are specified after a ":". There are examples of this above - "set" and "debugMessage".

Any word in the set of parameters surrounded by square brakets is assumed to be either a variable or the name of a function. If the word '''''starts''''' with mission_, local_, or commander_ it is assumed to be a variable and the variable's value replaces the variable name and the square brackets before the action is executed. If the word '''''ends''''' with _string, _number, or _bool it is assumed to be a function and the function's return value replaces the function name and the square brackets before the action is executed.

Here is the longway.oxp script converted to oos format, with comments added:
<pre>
// Giles Williams' LongWay mission converted to oos format
//
long_way_round

// This is a pretty fast way to ensure no unnecessary processing is performed.
// This single condition can avoid all the other conditions getting evaluated
// if the player isn't in galaxy 0
//
if galaxy_number equal 0 then

// As above, this one condition can save evaluating the three enclosed conditions
// while the player is in space.
//
if dockedAtMainStation_bool equal YES then

// If the player docks at the main station at XXX then start the
// mission. Doesn't seem to be a way to refuse to do the mission.
//
if mission_longwayround undefined and planet_number equal 3 then
setMissionMusic: none
setGuiToMissionScreen
addMissionText: long_way_round_Biarge_briefing
set: mission_longwayround STAGE1
setMissionDescription: em1_short_desc1
endif

// If the player docks at the main station of YYY and they're doing
// the longway mission then reward them for partially completing it and
// send them on the next step.
//
if mission_longwayround equal STAGE1 and plaent_number equal 248 then
setMissionMusic: none
setGuiToMissionScreen
addMissionText: long_way_round_Soladies_briefing
awardCredits: 500
set: mission_longwayround STAGE2
setMissionDescription: em1_short_desc2
endif

// If the player docks at the main station of ZZZ and they're on the
// 2nd step of the mission, mark it complete and reward the player again.
//
if mission_longwayround equal STAGE2 and planet_number equal 233 then
setMissionMusic: none
setMissionImage: loyalistflag.png
setGuiToMissionScreen
addMissionText: long_way_round_Qubeen_briefing
awardCredits: 2000
setMissionImage: none
set: mission_longwayround MISSION_COMPLETE
clearMissionDescription
endif
endif

// If the player is on the second step of the mission and jumps in system ZZZ
// to complete the mission, ambush them with a couple of rebel ships!
//
if mission_longwayround equal STAGE2 and
planet_number equal 233 and
status_string equal STATUS_EXITING_WITCHSPACE then
addShips: rebel 2
endif

// Continually harass the player while they're in system ZZZ trying to finish
// the mission.
//
if mission_longwayround equal STAGE2 and
status_string equal STATUS_IN_FLIGHT and
planet_number equal 233 and
scriptTimer_number lessthan 60 then
checkForShips: rebel
if shipsFound_number lessthan 5 and d100_number lessthan 50 then
addShips: rebel 1
endif
endif
endif
</pre>

[[Category:Oolite]]

Script.oos

2006-04-05T06:18:49Z

Dajt: /* Structure */

Script.oos

2006-04-05T06:06:39Z

Dajt: /* Structure */

Script.oos

2006-04-05T06:05:40Z

Dajt: /* Specifying "if" conditions */

Script.oos

2006-04-05T05:37:48Z

Dajt: /* Specifying "if" conditions */

Script.oos

2006-04-05T05:29:04Z

Dajt: /* Specifying "if" conditions */

Script.oos

2006-04-05T02:18:30Z

Dajt: /* Specifying "if" conditions */

Script.oos

2006-04-05T02:16:58Z

Dajt:

OXP howto

2006-04-04T23:34:41Z

Dajt: /* Config */

[[Image:oolite-oxp-icon.png|100px|right|OXP icon]]
An '''Oolite Expansion Pack''' can cause many big changes or additions to Oolite's gameplay, or it may represent just a small, subtle alteration. By appearances, there is no way to tell what is inside, as it's merely a folder with the added extention '''.oxp'''. Inside, it will at least contain a folder named ''Config'', and possibly other folders such as ''AIs'', ''Models'', ''Textures'', ''Sounds'', etc. It is down to the goal of the OXP, which ways to combine elements to the OXP's contents.

=== AIs ===

The folder named AIs would contain any AI.plist additions the OXP might use.

* [[OXP howto AI|Making Oolite AI]]

=== Config===

This folder contains Property Lists such as:

* ''[[shipdata.plist]]'' that introduces any new entity (ships, stations, objects etc.) to Oolite.
* ''[[misc plists|shipyard.plist]]'' that introduces new ships available for player purchase.
* ''[[script.plist]]'' or ''[[script.oos]]'' that plots conditional ''script actions''. script.oos will be loaded in preference to script.plist if both exist.
* ''[[planetinfo.plist]]'' that plots system specific changes from the default. may also contain ''script actions''.
* ''[[commodities.plist]]'' that contains information for each commodity in a market.
* ''[[misc plists|descriptions.plist]]'' that adds vocabulary to Oolite texts.
* ''[[hud.plist]]'' that allows for changes or a radically new ''Head-Up Display''.
* ''[[missiontext.plist]]'', ''[[misc plists|demoships.plist]]'', ''[[speech_pronunciation_guide.plist]]'' are some of the other custom methods.

All plist files except for those introducing new AI, belong in Config.

In its simplest form, an OXP could contain only a Config with an altering ''script.plist'' or ''planetinfo.plist''. An OXP that adds a new ship needs a ''shipdata.plist'' entry, and unless it is based entirely on existing Oolite data, would include a model and texture.

* [[OXP howto plist|Making Oolite plists]]

=== Models===

Oolite models need to be in the '''.dat''' format. There are utilities available that convert models made in Wings 3D (.obj) and Meshwork (.mesh) into this. A .dat file can be opened in a plain text editor to view the object's assigned texture names and see that they correspond with the actual file names in the Textures folder. The .dat file must be named exactly as it is referenced in the shipdata ''model'' entry.

* [[OXP howto model|Making Oolite models]]

=== Textures===

Oolite's textures are in the '''.png''' format, usually at a standard 512x512 size, and must be named exactly as they are named in the .dat file.

* [[OXP howto texture|Making Oolite textures]]

== External links ==

*[http://oolite.aegidian.org/cyoship/ Oolite Tutorial-Meshwork Shipbuilding]
*[http://oolite.aegidian.org/cyoship2/ Oolite Tutorial-Wings 3D Shipbuilding]

[[Category:Oolite]]

Methods

2006-03-27T05:29:05Z

Dajt: /* Changing the universe */

'''Methods'''

Methods are the actions that are performed when conditions (defined in a script) are met, or when a particular set of actions (like ''[[Shipdata.plist#death_actions|death_actions]]'' or ''[[Shipdata.plist#script_actions|script_actions]]'') are called for, or when an AI calls for a script action to be performed.

All methods are stored in plists as strings (in XML this means between a <string> tag and a </string> closing tag). If they take any parameters then these follow a colon and a space (''': ''') after the 'command' part of the method.

For example: if the ship containing this ''death_actions'' entry is destroyed - the player gets a message and the sun goes Nova two seconds later!

<key>death_actions</key>
<array>
<string>commsMessage: Oh dear [commander_name]!</string>
<string>setSunNovaIn: 2.0</string>
</array>

== The Mission Screen ==

'''setGuiToMissionScreen'''
// opens the mission screen

'''addMissionText: <[[missiontext.plist]] key> '''
// adds text to the mission screen from an entry in [[missiontext.plist]]
// with the given key

'''showShipModel: <role>'''
// shows a rotating model of a ship with the role given
// role refers to a value in one of [[shipdata.plist]]'s entries'
// ''roles'' key value pair

'''setMissionMusic: <filename>'''
// plays the music file given
// if it exists within any OXP's ''Music'' folder

'''setMissionImage: <filename>'''
// displays the picture file given
// if it exists within any OXP's ''Images'' folder

'''setMissionChoices: <[[missiontext.plist]] key>'''
// sets the array of choices presented at the bottom of the mission page to those described in the
// entry in missiontext.plist that corresponds to the key given

'''resetMissionChoice'''
// makes missionChoice ''UNDEFINED''

'''setMissionDescription: <[[missiontext.plist]] key>'''
// sets the short description given on the player's manifest screen

'''clearMissionDescription'''
// clears the short description

'''resetScriptTimer'''
// resets a timer for scripting purposes '''deprecated - do not use''

== Looking for, and adding ships ==

'''checkForShips: <role>'''
// returns the number of ships found in the current system that match the role
// this number can be queried with [[Methods#Results_from_other_methods|'''shipsFound_number''']]

'''addShips: <role> <number>'''
// causes a number of ships matching the given role to appear near the withpoint

'''addSystemShips: <role> <number> <position>'''
// causes a number of ships matching the given role to appear near a point
// on a line from the witchpoint to the planet's station. <position> should be a floating point
// number where 0.0 represents the witchpoint and 1.0 represents the station

'''addShipsAt: <role> <number> <coordinate scheme> <x> <y> <z>'''
// causes a number of ships matching the given role to appear ''near'' a point
// defined by the <coordinate scheme> and the floating point coordinates x,y and z
// <coordinate scheme> consists of a three letter code:
//
// The first letter indicates the feature that is the origin of the coordinate system.
// w => witchpoint
// s => sun
// p => planet
//
// The next letter indicates the feature on the 'z' axis of the coordinate system.
// w => witchpoint
// s => sun
// p => planet
//
// Then the 'y' axis of the system is normal to the plane formed by the planet, sun and witchpoint.
// And the 'x' axis of the system is normal to the y and z axes.
// So:
// ps: z axis = (planet -> sun) y axis = normal to (planet - sun - witchpoint) x axis = normal to y and z axes
// pw: z axis = (planet -> witchpoint) y axis = normal to (planet - witchpoint - sun) x axis = normal to y and z axes
// sp: z axis = (sun -> planet) y axis = normal to (sun - planet - witchpoint) x axis = normal to y and z axes
// sw: z axis = (sun -> witchpoint) y axis = normal to (sun - witchpoint - planet) x axis = normal to y and z axes
// wp: z axis = (witchpoint -> planet) y axis = normal to (witchpoint - planet - sun) x axis = normal to y and z axes
// ws: z axis = (witchpoint -> sun) y axis = normal to (witchpoint - sun - planet) x axis = normal to y and z axes
//
// The third letter denotes the units used:
// m: meters
// p: planetary radii
// s: solar radii
// u: distance between first two features indicated (eg. spu means that u = distance from sun to the planet)
//
// in witchspace (== no sun) coordinates are absolute irrespective of the system used

'''addShipsAtPrecisely: <role> <number> <coordinate scheme> <x> <y> <z>'''
// This adds the ships as close as possible to the specified point

'''addShipsWithinRadius: <role> <number> <coordinate-system> <x> <y> <z> <radius in metres>'''
// Example:
// "addShipsWithinRadius: asteroid 48 wpm 0 0 15000 5000"
// would add a 5km-wide asteroid field with 48 asteroids at a position roughly 15000m towards
// the planet from the witchpoint.

'''spawn: <role> <number>'''
// adds a number of ships matching <role> near the ship
// that's the target of this script (as [[Shipdata.plist#script_actions|script_actions]] or [[Shipdata.plist#death_actions|death_actions]])

'''spawnShip: <[[shipdata.plist]] key>'''
// adds a ship with the unique [[shipdata.plist]] key given
// the position and facing of the ship are determined by a ''spawn'' dictionary in the
// ship's shipdata.plist entry with ''position'' and ''facing_position'' as strings describing
// coordinates according to one of the schemes above

== Changing the universe ==

'''setSunNovaIn: <seconds>'''
// Sets the sun to go nova after the given time in seconds

'''sendAllShipsAway'''
// Makes all the ships in the system hyperspace away

'''setPlanetinfo: <key>=<value>'''
// sets an override to the [[planetinfo.plist]] entry for the current system
// the value for the given key is set to match the value
// (see [[planetinfo.plist]])
//
// eg '''setPlanetinfo: description=a very dull planet'''
// (Note the '=' is required and no variable expansion is performed on <value>)

'''addPlanet: <[[planetinfo.plist]] key>'''
// adds a planet to the universe from data in [[planetinfo.plist]].

'''addMoon: <[[planetinfo.plist]] key>'''
// adds a moon to the universe from data in [[planetinfo.plist]].
// (Moons do not get an atmosphere or clouds like planets).

== Mission Variables ==

'''set: [[mission_variable]] <value>'''
// sets the [[mission_variable]] to the value given
// the value can be a particular string or numeric value,
// or a queriable state

'''reset: [[mission_variable]] <value>'''
// sets the [[mission_variable]] to be ''UNDEFINED''

'''increment: [[mission_variable]]'''
// increases the mission variable's value by 1.0

'''decrement: [[mission_variable]]'''
// decreases the mission variable's value by 1.0

'''add: [[mission_variable]] <value>'''
// adds the value given to the [[mission_variable]]
// the value can be a number or a queriable state
// like ''shipsFound_number''

'''subtract: [[mission_variable]] <value>'''
// subtracts the value given from the [[mission_variable]]
// the value can be a number or a queriable state
// like ''shipsFound_number''

== Player rewards and penalties==
These methods work on the player, not any other ship.

'''awardCredits: <number>'''
// awards number of tenths of credits.

'''awardShipKills: <number>'''
// Adds to the number of kills accredited to the player

'''setLegalStatus: <number>'''
// Sets the bounty on the player's head.

'''setFuelLeak: <amount>'''
// removes this amount from the fuel tank every second
// until the tanks drain and self-seal

'''awardFuel: <amount>'''
// The amount can be positive or negative, expressed in LY of range
// the fuel level is adjusted to a maximum of 7.0LY and minimum of 0.0.

=== Equipment ===

'''awardEquipment: <equipment key>'''
// if the player doesn't have the equipment already
// and their ship can be equipped witth it then this fits the
// player's ship with the equipment given
// valid keys can be found in [[equipment.plist]] (they all begin '''EQ_'''):-
// EQ_FUEL
// EQ_MISSILE
// EQ_CARGO_BAY
// EQ_ECM
// EQ_FUEL_SCOOPS
// EQ_ESCAPE_POD
// EQ_ENERGY_BOMB
// EQ_ENERGY_UNIT
// EQ_NAVAL_ENERGY_UNIT
// EQ_DOCK_COMP
// EQ_GAL_DRIVE
// EQ_CLOAKING_DEVICE
// EQ_PASSENGER_BERTH
// EQ_HARDENED_MISSILE
// EQ_FUEL_INJECTION
// EQ_SCANNER_SHOW_MISSILE_TARGET
// EQ_MULTI_TARGET
// EQ_ADVANCED_COMPASS
// EQ_QC_MINE
// EQ_SHIELD_BOOSTER
// EQ_NAVAL_SHIELD_BOOSTER
// EQ_WEAPON_TWIN_PLASMA_CANNON
// EQ_MILITARY_JAMMER
// EQ_MILITARY_SCANNER_FILTER

'''removeEquipment: <equipment key>'''
// removes the indicated equipment from the player's ship

'''testForEquipment: <equipment key>'''
// tests whether the player ship has a piece of equipment installed
// returns the result in [[Methods#Results_from_other_methods|'''foundEquipment_bool''']]

=== Cargo ===

'''awardCargo: <amount> <[[Commodities|Commodity]] name>'''
// awards a quantity of the cargo named
// the cargo name must match the name in [[commodities.plist]] exactly

'''removeAllCargo'''
// removes all cargo from the hold with no compensation to the player
// any special cargo is also removed (see below) restoring use of the cargo bay
// Gold, Platinum, and Gemstones are unaffected (they're in the cabin safe).

'''useSpecialCargo: <description of cargo>'''
// fills the cargo bay withthe cargo described effectively
// disabling the use of the cargo bay until the cargo is removed

=== Special ===

'''ejectItem: <[[shipdata.plist]] key>'''
// Creates a ship or other entity from [[shipdata.plist]] and ejects from
// the ship's aft hatch

'''launchFromStation'''
// forces the player ship to launch

== Communications ==

'''commsMessage: ''message'' '''
// sends the player a message
// if the message contains elements enclosed in square brackets ''[like_this]''
// that corresponds to a [[mission_variable]] or keys in [[descriptions.plist]]
// or to special expansions like [commander_name] then these are expanded
// and substituted into the original message

== Querying states ==

=== Player status ===

// '''mission_string'''
// returns the key for the current mission

// '''status_string'''
// returns one of:
// ''STATUS_AUTOPILOT_ENGAGED''
// ''STATUS_DEAD''
// ''STATUS_DEMO''
// ''STATUS_DOCKING''
// ''STATUS_DOCKED''
// ''STATUS_EFFECT''
// ''STATUS_ENTERING_WITCHSPACE''
// ''STATUS_ESCAPE_SEQUENCE''
// ''STATUS_EXITING_WITCHSPACE''
// ''STATUS_EXPERIMENTAL''
// ''STATUS_IN_FLIGHT''
// ''STATUS_IN_HOLD''
// ''STATUS_INACTIVE''
// ''STATUS_LAUNCHING''
// ''STATUS_TEST''
// ''STATUS_WITCHSPACE_COUNTDOWN''
// ''UNDEFINED''

// '''gui_screen_string'''
// returns one of:
// ''GUI_SCREEN_EQUIP_SHIP''
// ''GUI_SCREEN_INTRO1''
// ''GUI_SCREEN_INTRO2''
// ''GUI_SCREEN_INVENTORY''
// ''GUI_SCREEN_LONG_RANGE_CHART''
// ''GUI_SCREEN_MAIN''
// ''GUI_SCREEN_MARKET''
// ''GUI_SCREEN_MISSION''
// ''GUI_SCREEN_OPTIONS''
// ''GUI_SCREEN_SHORT_RANGE_CHART''
// ''GUI_SCREEN_STATUS''
// ''GUI_SCREEN_SYSTEM_DATA''
// ''UNDEFINED''

// '''galaxy_number'''
// returns a value between 0 and 7

// '''planet_number'''
// returns a value between 0 and 255

// '''score_number'''
// returns the number of the player's current ship kills

// '''credits_number'''
// returns the player's credits x10

// '''legalStatus_number'''
// returns the bounty on the players head

// '''fuel_level_number'''
// returns the fuel level in LY

// '''dockedAtMainStation_bool'''
// returns ''YES'' if docked at a systems main station, ''NO'' otherwise

// '''dockedStationName_string'''
// returns ''NONE'' if the player isn't docked, the name of the station (from [[shipdata.plist]]) if it is, ''UNKNOWN'' otherwise

=== Results from other methods ===

// '''shipsFound_number'''
// returns the number of ships found by ''checkForShips:''

// '''foundEquipment_bool'''
// returns the result of the last ''testForEquipment''
// returns ''YES'' if the equipment was found, ''NO'' otherwise

// '''missionChoice_string'''
// returns the result of the player's selection from a list of missionChoices
// returns ''UNDEFINED'' or the key for the chosen option

=== Random numbers ===

// '''d100_number'''
// returns a random value from 0 to 99

// '''pseudoFixedD100_number'''
// returns a random number from 0 to 99 that will
// remain fixed as long as the player remains in this system

=== Time ===

// '''clock_number'''
// returns the game time in seconds
// '''clock_secs_number'''
// returns the game time in seconds
// '''clock_mins_number'''
// returns the game time in minutes
// '''clock_hours_number'''
// returns the game time in hours
// '''clock_days_number'''
// returns the game time in days

=== System states ===

// '''sunWillGoNova_bool'''
// returns whether the sun is going to go nova, either ''YES'' or ''NO''

// '''sunGoneNova_bool'''
// returns whether the sun has gone nova, either ''YES'' or ''NO''

// '''systemGovernment_string'''
// returns one of:-
// ''Anarchy''
// ''Feudal''
// ''Multi-Government''
// ''Dictatorship''
// ''Communist''
// ''Confederacy''
// ''Democracy''
// ''Corporate State''

// '''systemGovernment_number'''
// returns a value from 0 to 7

// '''systemEconomy_number'''
// returns a value from 0 to 7

// '''systemTechLevel_number'''
// returns a value from 0 to 14

// '''systemPopulation_number'''
// returns a value representing the system's population

// '''systemProductivity_number'''
// returns a value representing the system's productivity

// '''scriptTimer_number'''
// returns the script timer's current value in seconds '''(deprecated - do not use)'''

== Debugging scripts ==

'''debugOn'''
// sends script debugging messages to the console.

'''debugOff'''
// cancels script debugging messages

'''debugMessage: <message>'''
// sends the given message to the console. The message is written to the console regardless
// of whether debugOn has been performed or not. For GNUstep versions of Oolite, the console
// is a file called stderr.txt located in the game's installation directory. Mission variables
// and queriable states may be included in the message, eg:
//
// ''debugMessage: current galaxy is galaxy_number''

== AI ==

Note that although most of these methods affect the player, some can also be utilised by an AI.
*[[OXP howto AI]].

[[Category:Oolite]]