Elite Wiki - User contributions [en]

Shipdata.plist

2023-09-20T12:31:38Z

Alnivel: /* escape_pod_model */ Added escape_pod_role and note about using a "[shipkey]" role

{{QuoteText|Text=The shipdata.plist would be more accurately called objectdata nowadays - a "ship" in Oolite might be a ship, a station, a rock, basically any solid object smaller than a planet (or moon)|Source=([http://www.aegidian.org/bb/viewtopic.php?p=275475#p275475 Cim])}}

= Format =
Shipdata.plist is in [[Property list]] format.
The shipdata document is a dictionary of ships. Example:

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

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

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

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

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

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

Example:
"accuracy" = 8.3;

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

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

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

Example:
"aft_weapon_type" = "WEAPON_BEAM_LASER";

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

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

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

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

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

Example:
"auto_weapons" = yes;

See [http://aegidian.org/bb/viewtopic.php?p=235800#p235800 here] for more detail

== beacon ==
A special feature for beacons and navigation aids.
The string can be anything - the first letter was what was displayed in the advanced space compass before Oolite v.1.79. It is still the only display for the older [[HUD]]'s.

Example:
"beacon" = "X";

Characters that are known to be used as identifiers for '''stations and other fixed objects''' are found on the page for the [[Advanced_Space_Compass#List_of_Navigational_Buoys|Advanced Space Compass]]. Most letters have been used multiple times in various OXPs.

Since v.1.79 the HUD also displays a longer label; before that several HUD OXPs were available to do something similar (see [[Advanced Space Compass]]).

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

There are several devices which detect things from great distance: the Vanilla game's [[Advanced Space Compass]], [[The Galactic Almanac OXZ]], [[Telescope]] and the [[Long Range Scanner]]. The last is a cheat OXP useful for programmers. See the [http://www.aegidian.org/bb/viewtopic.php?p=281279#p281279 HIMSN thread] for details of making things invisible to them.

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

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

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

Example:
"bounty" = 50;

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

Example:
"cargo_carried" = "Gold";

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

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

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

Example:
"cargo_type" = "CARGO_RANDOM";

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

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

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

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

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

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

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

Example:
"cloak_automatic" = no;

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

Example:
"cloak_passive" = yes;

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

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

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

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

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

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

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

Example:
"counts_as_kill" = no;

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

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

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

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

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

Four decimal places are probably enough accuracy for these values.

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

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

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

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

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

Example:
"debris_role" = "my_boulder_foo";

See the discussion here: [http://www.aegidian.org/bb/viewtopic.php?f=4&t=10061 (RELEASE) Icesteroids V2] (2011-12) - about role circularity and about the vanilla game code creating alloys whenever anything big explodes!

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

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

Example:
"density" = 1.5;

• See Eric Walch's comment on vanilla-game Coriolis stations [http://aegidian.org/bb/viewtopic.php?p=118196#p118196 here] (2010)

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

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

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

Example:
"energy_recharge_rate" = "3.5";

See [http://aegidian.org/bb/viewtopic.php?f=4&t=12152 Energy rates and recharge] for more detail (2012)

== escape_pod_model ==
With this entry ships can have custom escape pods. Defaults to "escape-capsule".

'''Since v1.65:''' You have to specify the '''role''' of your custom escape pod (not its entry-name).

'''Since v1.77:''' Deprecated in favour of <code>escape_pod_role</code>.

Example:
"escape_pod_model" = "custom_pod_role";

'''Note:''' Each shipdata entry has an implicit unique role in the form of a shipdata key enclosed in square brackets - e.g. "[entry-name]". It might be useful if you want to use a specific escape pod that has no unique role.

== escape_pod_role ==
With this entry ships can have custom escape pods. It's almost the same as <code>escape_pod_model</code>, but has a less ambiguous name. Added in v1.77.

The game first tries to spawn a pod using <code>escape_pod_role</code>, but if the property isn't set or a spawn fails, the game uses <code>escape_pod_model</code>. If the latter fails too, the game tries the "escape-capsule" role.

Example:
"escape_pod_model" = "custom_pod_role";

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

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

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

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

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

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

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

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

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

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

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

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

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

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

x y z width height length

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

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

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

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

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

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

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

Determines the colour of the exhausts.

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

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

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

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

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

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

Example:
"extra_cargo" = 25;

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

Example:
"forward_weapon_type" = "WEAPON_BEAM_LASER";

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

Example:
"frangible" = no;

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

Example:
"fragment_chance" = no;

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

Example:
"fuel" = 70;

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

Example:
"has_cloaking_device" = 0.5;

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

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

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

Example:
"has_energy_bomb" = yes;

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

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

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

Example:
"has_fuel_injection" = 0.99;

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

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

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

Example:
"has_scoop" = no;

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

Example:
"has_scoop_message" = no;

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

Example:
"has_shield_booster" = 0.80;

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

Example:
"has_shield_enhancer" = 0.45;

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

Example:
"heat_insulation" = "2.0";

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

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

== hud ==
Used for a playership, to assign another HUD than the default one. Note that small ships get the second default - the hud-small.plist

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

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

Examples:
"hyperspace_motor" = no;

hyperspace_motor=NO;

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

Examples:
"hyperspace_motor_spin_time" = "15";

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

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

"injector_burn_rate" = 0.25;

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

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

"injector_speed_factor" = 7;

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

Example:
"is_external_dependency" = yes;

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

Example:
"is_submunition" = yes;

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

Example:
"is_template" = yes;

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

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

Example:
"laser_color" = "cyanColor"

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

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

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

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

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

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

Example:
"likely_cargo" = "2";

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

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

Example:
"max_cargo" = "5";

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

Example:
"max_energy" = "300";

See [http://aegidian.org/bb/viewtopic.php?f=4&t=12152 Energy rates and recharge] for more detail (2012). Divide by 64 to get the rough number of energy banks.

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

Example:
"max_flight_pitch" = "2.2";

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

Example:
"max_flight_roll" = "4.2";

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

Example:
"max_flight_speed" = "320";

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

Example:
"max_flight_yaw" = "2.2";

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

Example:
"max_missiles" = "1";

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

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

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

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

Example:
"missile_load_time" = "2.1";

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

Example:
"missiles" = "0";

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

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

Example:
"missile_role" = "EQ_THARGON";

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

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

== model_scale_factor ==
1.81 or later only.

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

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

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

Example:
"model_scale_factor" = 2.0;

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

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

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

Example:
"no_boulders" = yes;

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

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

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

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

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

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

Example:
"port_weapon_type" = "WEAPON_BEAM_LASER";

== reaction_time ==
Sets the reaction time of the pilot of this ship. The default is 1.5 seconds.

Example:
"reaction_time" = 1.0; // this pilot is superhuman! or a cat

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

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

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

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

or an exclusive role, simply:

"roles" = "uniquely_named_role";

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

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

Example:
"roles" = "Gold";

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

* [http://aegidian.org/bb/viewtopic.php?p=98050#p98050 1 1/2 pages of discussion of station population percentages] (2010)

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

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

An explaining example taken from the Oolite Bulletin board.

The rotational velocity key is rotation per second. For instance, if you want to rotate once per 20 seconds around the Z axis:

a = 360 ° / 20 = 18 °

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

sin a ˜ 0.30902

cos a ˜ 0.95106

Q = (0.95106, 0, 0, 0.30902)

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

In practical terms, one can therefore use
"rotational_velocity"="3 0 0 1"
To alter the speed of rotation increase number 3, for slower rotations, decrease for higher speed. For opposite rotational direction, change 1 to -1.[http://www.aegidian.org/bb/viewtopic.php?f=4&t=6899&p=93038&hilit=rotational+velocity+key#p93038 (ref: Arhuman BB 1/11-09)]

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

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

Example:
"scan_class" = "CLASS_ROCK";

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

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

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

"scan_description" = "Unclaimed rock";

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

Example:
"scanner_display_color1" = "greenColor";

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

Example:
"scanner_display_color2" = "redColor";

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

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

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

Example:
"scanner_hostile_display_color1" = "greenColor";

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

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

Example:
"scanner_hostile_display_color2" = "redColor";

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

Example:
"scanner_range" = "25600";

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Example:
"smooth" = yes;

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

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

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

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

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

Example:
"starboard_weapon_type" = "WEAPON_BEAM_LASER";

== subentities ==
An array of ''subentity definitions''. A ''subentity'' is an object attached to your ship. There are several types of subentity:
* ''Static subentities'', the default type, are simply extra models. They are defined as separate shipdata.plist entries, so technically they’re ships, but they don’t have a mind of their own. If the main ship is [[#frangible|frangible]], static subentities can take damage and blow up separately from the main ship. They can also be individually exploded or removed by scripts.
* ''Docks'' are recognized when setting up a station or carrier, and used to determine the station’s docking port parameters. After set-up, they work just like normal static subentities. The string "dock" in lowercase must be part of the old style name in order to get recognised as the dock subEntity.
* ''Ball turrets'' turn to track the ship’s current target, and shoot plasma balls if the target is within range (6000 metres). A ball turret’s field of fire is a 157 ° cone centred on its original facing. Currently, ball turrets make no effort not to shoot their own ship, so it is up to the designer to ensure this field of fire is clear. Like a static subentity, a ball turret is based on a shipdata.plist entry so its appearance can be customized. Oolite provides a built-in shipdata entry for ball turrets called, imaginatively, '''ballturret'''.
: For discussion on the effective range (before the reduction from the original 7500 to 7200) see [http://www.aegidian.org/bb/viewtopic.php?p=198854#p198854 here].
:Note that the [[Vortex]] turrets can be switched off. This involved special scripting (basically removing and restoring the turrets by script). Needs a little fancy footwork when docked though or else if you dock with removed sub-entities (even deliberately removed ones) you'll get a maintenance overhaul offered which will put them back if purchased.
* ''Flashers'' are blobs which glow with a pulsating light. From Oolite 1.74 onwards, constant light will also be an option. Note that while flashers appear luminous – they are unaffected by shadows – they do not cast light on other objects.
* Random number of Subentities (''eg'' Cargo pods): see [http://www.aegidian.org/bb/viewtopic.php?f=4&t=18743 Can the number of entities a ship be randomized?] (2017)

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

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

{| class="wikitable" border="1" cellpadding="3" cellspacing="0" style="width:100%"
|+ Subentity definition properties for ball turrets
! Name !! Type !! Description
|-
| '''fire_rate''' || number || Interval between shots in seconds, for '''ball_turret''' subentities. Default: 0.5; minimum: 0.25.
|-
| '''weapon_range''' || number || Range for '''ball_turret''' subentities. Default: 6000; maximum 7200.
|-
| '''weapon_energy''' || number || Weapon energy for '''ball_turret''' subentities. Default: 25; maximum 100.
|}
See [http://aegidian.org/bb/viewtopic.php?f=4&t=12085 New range of turrets] for more information on turret subentities (2012 discussion about modelling, quaternions, ''etc'').

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

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

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

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

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

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

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

'''initially_on''' is false.

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

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

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

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

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

=== Links ===
*[http://www.aegidian.org/bb/viewtopic.php?f=3&t=19091 How are subentity scripts supposed to work ?] (2017)
*[http://aegidian.org/bb/viewtopic.php?f=4&t=11716 Ball turrets] (2012)
*[http://aegidian.org/bb/viewtopic.php?f=4&t=7222 Docking bay problems] (2009) - covers a range of issues
*Some OXP's with subentities:
:Thargoids: [[Stellar Serpents OXP]] (2010), [[Animated Ships]]/Butterflies (2011), [[Aquatics]] (2011: Hammerhead bulk carrier & the Aqualina stations), [[WildShips OXP]] (2012-14: moving elevators inside station struts)
:[[Z GrOovy HPC pack]] (2014 - bought equipment is visible on ship!); [[Scrub]] (2022 - rotating rings)

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

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

"sun_glare_filter" = 0.3;

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

Example:
"track_contacts" = yes;

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

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

Example:
"throw_sparks" = yes;

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

Example:
"thrust" = "25"

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

Example:
"unpiloted" = yes;

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

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

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

<b>Missiles.</b> Changes the damage inflicted by the missile. Any value accepted.

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

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

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

Example:
"weapon_energy" = "17";

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

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

1 - Forward<br />
2 - Aft<br />
4 - Port<br />
8 - Starboard<br />

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Example:
allegiance = "neutral";

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

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

Example:
allows_auto_docking = "no";

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

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

Example:
allows_fast_docking = "yes";

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

Example:
defense_ship" = "my_defender";

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

Example:
"defense_ship_role" = " carrier_defenders";

== equipment_price_factor ==
Equipment price mask for dockables.

Example:
"equipment_price_factor" = "4.5";

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

Example:
"equivalent_tech_level" = 1;

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

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

Example:
"has_npc_traffic" = yes;

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

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

Example:
"has_patrol_ships" = yes;

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

Example:
"has_shipyard" = "0.75";

or

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

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

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

Example:
interstellar_undocking = "yes";

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

Example:
"is_carrier" = yes;

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

Example:
"market" = "none";

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

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

"market_broadcast" = no;

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

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

"market_capacity" = 31;

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

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

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

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

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

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

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

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

market_monitored = yes;

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

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

market_script = "myoxp_marketchanges.js";

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

Example:
"max_defense_ships" = "10";

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

Example:
"max_police " = "10";

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

Example:
"max_scavengers" = "10";

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

Example:
"port_dimensions" = "65x30x500";

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

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

Example:
"port_radius" = "500";

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

Example:
"requires_docking_clearance" = yes;

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

Example:
"rotating" = yes;

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

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

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

Example:
"station_roll" = "-1.5"

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

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

Example:
"tunnel_corners" = 6;

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

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

Example:
"tunnel_start_angle" = 0;

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

Example:
"tunnel_aspect_ratio" = 1;

----
= Links =
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=3355 Orientation Issues] (Asteroid turns 180°, and want it to face planet, 2007)
*[http://aegidian.org/bb/viewtopic.php?f=4&t=20959 Empty System] (Removing stations and rock hermits from a system, 2021)
*[http://www.aegidian.org/bb/viewtopic.php?f=6&t=4729 Changing compass values of ships (from white to red)] (Hiding ships on the scanner, 2008)

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

Misc plists

2023-09-20T11:05:10Z

Alnivel: /* world-scripts.plist */ Fixed one more "worldScripts", added quotes

----
=crosshairs.[[plist]]=

== Structure ==

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

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

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

----
=descriptions.[[plist]]=

== Structure ==

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

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

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

== Use ==

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

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

You have to pick up [parcelnumbers] parcels.

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

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

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

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

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

----
=demoships.[[plist]]=

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

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

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

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

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

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

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

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

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

----
=info.[[plist]]=
This does not actually seem to do anything other than give the human being reading it some information! [[Galactic Navy OXP]] has one, as do ''inter alia'' [[User:Mandoman|Mandoman]]'s many oxps.

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

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

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

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

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

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

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

----
=OXPMessages.[[plist]]=

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

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

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

----
=world-scripts.[[plist]]=

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

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

==Content==
To know what to put into such a world script, see [[Oolite_JavaScript_Reference:_World_script_event_handlers|the list of world script event handlers]].

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

==Note==
There are two ways of storing a JS worldscript:

1) Old: You can name it "script.js" and put it into the Config folder. That's what cim did in his [[Galactic Misjump OXP]]. It's a leftover of "legacy" plist scripting, where the script had to be named "script.plist" and reside in the Config folder. This way was especially useful in the time when we had Oolite 1.65 as official release, and the growing number of test releases. In those times you could have both a "script.plist" and a "script.js" alongside each other in the Confic folder. Oolite 1.65 would use the plist script, and the later versions would ignore the plist and use the JS script instead. This functionality is not particularly useful anymore, but it still exists.<br>
2) New: You can name it whatever you want (but perhaps not "script.js") and put it into the Script folder. Then you have to create another plist in the Config folder named "world-scripts.plist" and write the name of your script into that plist. This method has the advantage that you can have more than one worldscript in an OXP, which is of course not possible with the first method, because there can only be one file named "script.js" in a Config folder. [http://www.aegidian.org/bb/viewtopic.php?p=170774#p170774 Commander McLane (2012)]

----

=whitelist.[[plist]]=

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

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

This plist cannot be extended or overriden by OXPs.

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

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

[[Category:Oolite scripting]]

----
=See also=
* [[OXP howto]]

Oolite JavaScript Reference: World script event handlers

2023-09-20T10:55:33Z

Alnivel: Replaced worldScript.plist by world-scripts.plist, added links

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

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

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

World scripts are always active.

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

=== Game State ===

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

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

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

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

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

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

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

The <code>playerWillSaveGame</code> handler is called whenever the player saves a game. The transferred message is one of the following strings: <code>"STANDARD_SAVE"</code>, <code>"AUTO_SAVE"</code> or <code>"QUICK_SAVE"</code>.

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

Using this event is useful for storing temporary variables in <code>[[Oolite_JavaScript_Reference:_Global#missionVariables|missionVariables]]</code>, just before the game gets saved. <code>missionVariables</code> are slow in use compared to normal JS variables, therefore their use should be minimised for efficient code. The main benefit of using <code>missionVariables</code> is that they are saved in a saved game. See also [[Mission variable]].

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

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

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

Note that from Oolite 1.79 onwards the player is in the main station while this handler runs but may be moved to another station soon after.

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

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

=== Docking ===

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

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

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

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

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

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

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

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

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

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

The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect. The handler's argument is the station which launched the ship.

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

At this moment <code>ship.dockedStation == null</code>, <code>ship.docked == false</code>, <code>ship.status == "STATUS_IN_FLIGHT"</code>.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Witchspace Jumps ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Note:''' If the <code>cause</code> is <code>"carried"</code> the <code>destination</code> parameter is <code>undefined</code>. This behaviour is presumably a bug.

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

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

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

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

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

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

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

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

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

shipWillEnterWitchspace (world event)<br>
playerWillEnterWitchspace (NPC ship event)<br>
playerEnteredNewGalaxy (world event)<br>
shipWillExitWitchspace (world event)<br>
shipExitedWitchspace (world event)<br>

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

*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18392 Order of JS events when galactic jumping] (2016)

=== Enter/Exit Aegis ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Combat ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== <code>shipTakingDamage</code> ====

Not yet documented - seen in [[Auto eject OXP]].

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Equipment and Cargo ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<code>shipyard</code> is a dictionary object containing details about the ship being purchased, with information similar to the following:
{
short_description: "Python: Plus Galactic Hyperdrive. Extra Energy Unit. Docking Computers. E.C.M. System. Forward weapon upgraded to military laser. Price 215 000 ₢.",
shipdata_key: "python-player",
id: "675b6b-c60a74",
price: 215000,
ship: {
...''[[shipdata.plist]]'' details of ship...
},
personality: 9807,
extras: ["EQ_GAL_DRIVE", "EQ_FUEL_SCOOPS", "EQ_ENERGY_UNIT", "EQ_FUEL_INJECTION", "EQ_DOCK_COMP", "EQ_ECM"]
}

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

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

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

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

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

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

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

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

=== Other ===

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

The <code>chartHighlightModeChanged</code> handler is called whenever the highlight mode of the galactic chart is changed either manually (from player input) or programmatically (by setting the mode with <code>[[Oolite JavaScript Reference: PlayerShip#chartHighlightMode|player.ship.chartHightlightMode]]</code>). The "newMode" parameter will be one of the following:
* <code>"OOLRC_MODE_SUNCOLOR"</code>
* <code>"OOLRC_MODE_ECONOMY"</code>
* <code>"OOLRC_MODE_GOVERNMENT"</code>
* <code>"OOLRC_MODE_TECHLEVEL"</code>

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

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

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

COMPASS_MODE_BASIC
COMPASS_MODE_PLANET
COMPASS_MODE_STATION
COMPASS_MODE_SUN
COMPASS_MODE_TARGET
COMPASS_MODE_BEACONS

script example

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

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

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

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

==== <code>escapePodSequenceOver</code> ====

The <code>escapePodSequenceOver</code> handler is called at the end of the escape pod sequence, after the <code>shipLaunchedEscapePod</code> event and just prior to the <code>shipWillDockWithStation</code> and <code>shipDockedWithStation</code> events.

Use this handler if you need to override the destination for the escape pod with [[Oolite_JavaScript_Reference:_Player#setEscapePodDestination|<code>player.setEscapePodDestination()</code>]].

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

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

The <code>guiScreenChanged</code> handler is called when the <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> changes. The ''from'' parameter is the screen it is leaving and ''to'' is the screen initially being switched to. Note that the screen can have changed again in the meantime by the action of other oxps. Therefore, it is generally better to test the global <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> to see which page is really on display instead of using the ''to'' parameter. (world script only)

This handler will only fire when switched to/from any of the following:

1.76: <code>"GUI_SCREEN_MAIN"</code>, <code>"GUI_SCREEN_STATUS"</code>(F5), <code>"GUI_SCREEN_MANIFEST"</code>(F5F5), <code>"GUI_SCREEN_SYSTEM_DATA"</code>(F7), <code>"GUI_SCREEN_OPTIONS"</code>, <code>"GUI_SCREEN_EQUIP_SHIP"</code>(F3), <code>"GUI_SCREEN_SHIPYARD"</code>(F3F3), <code>"GUI_SCREEN_SHORT_RANGE_CHART"</code>(F6), <code>"GUI_SCREEN_LONG_RANGE_CHART"</code>(F6F6), <code>"GUI_SCREEN_MARKET"</code>(F8), <code>"GUI_SCREEN_CONTRACTS"</code>, <code>"GUI_SCREEN_REPORT"</code>

1.77: adds <code>"GUI_SCREEN_INTERFACES"</code>(F4) and removes <code>"GUI_SCREEN_CONTRACTS"</code>

1.81: adds <code>"GUI_SCREEN_MARKETINFO"</code>(F8F8)

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

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

The <code>guiScreenWillChange</code> handler is called when the <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> is about to change. On these screens, a script could change the content of the page to be displayed. (world script only)

This handler will only fire when switching to/from any of the following:

<code>"GUI_SCREEN_EQUIP_SHIP"</code>(F3), <code>"GUI_SCREEN_MANIFEST"</code>(F5F5), <code>"GUI_SCREEN_MARKET"</code>(F8), <code>"GUI_SCREEN_SHIPYARD"</code>(F3F3), <code>"GUI_SCREEN_SYSTEM_DATA"</code>(F7)

1.77: adds <code>"GUI_SCREEN_INTERFACES"</code>(F4), <code>"GUI_SCREEN_STATUS"</code>(F5)

1.81: adds <code>"GUI_SCREEN_MARKETINFO"</code>(F8F8)

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

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

The <code>infoSystemChanged</code> handler is called when the system displayed in F7 is changed, e.g. by moving the small blue cursor along the planned route in the chart.

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

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

The <code>infoSystemWChange</code> handler is called just before the system displayed in F7 is updated, e.g. by moving the small blue cursor along the planned route in the chart.

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

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

The <code>mfdKeyChanged</code> handler is called whenever the player changes the content of an MFD slot. The <code>activeMFD</code> parameter identifies which MFD slot is being changed, and the <code>mfdKey</code> specifies the key code now in use in this slot.

this.mfdKeyChanged = function(activeMFD : integer, mfdKey : string)
{
// Your code here
}

'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#setMultiFunctionDisplay|PlayerShip.setMultiFunctionDisplay()]]</code>

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

The <code>missionChoiceWasReset</code> handler is called when the mission choice is set to <code>null</code> via script (either using the legacy script method resetMissionChice or using <code>mission.runScreen ({choices: null})</code> in javascript)

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

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

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

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

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

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

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

This handler works a bit different from other handlers. It fires for every installed OXP/OXZ until one creates a mission screen during this handler, and then it stops. When the mission screen ends and there is no callback function that creates a new mission screen, the <code>missionScreenOpportunity</code> is sent again to all installed OXPs/OXZs starting with the one that created the last mission screen. All this means is that when this handler fires, it is safe to show a mission screen and no further tests are needed.

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

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

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

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

The <code>selectedMFDChanged</code> handler is send whenever the player selects a new MFD slot (normally using the default keypress ";"). The <code>activeMFD</code> paramater is the index of the MFD which is now active.

this.selectedMFDChanged = function(activeMFD : integer)
{
// Your code here
}

==== <code>shipCollided</code> ====

The <code>shipCollided</code> handler is send after a collision with otherShip.

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

==== <code>shipSpawned</code> ====

The <code>shipSpawned</code> handler is called after an NPC ship has been added to the system. After a witchspace jump it means that first all ships are added to the system, then all the relevant shipSpawned events are triggered.<br>
This handler for the worldScript is new since Oolite 1.74. After the event is sent to the shipScript, it is now also send to the worldScript with the added entity as argument.

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

==== <code>shipLaunchedEscapePod</code> ====

The <code>shipLaunchedEscapePod</code> handler is called when the player bails out. This will be followed by the <code>escapePodSequenceOver</code> event, and then a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds.

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

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

The <code>systemInformationChanged</code> handler is called when system information is modified. It is passed the galaxy and system ID which were changed, and the key and new value in the SystemInfo object.

To avoid problems with recursion, attempting to change the value of any system information property from within this handler will fail and log an error. Also note that changes which take place while Oolite is not running (from OXP planetinfo.plist files) will not cause this handler to be called when the game is reloaded.

this.systemInformationChanged = function(galaxy,system,key,newValue)
{
// Your code here
}

==== <code>viewDirectionChanged</code> ====

The <code>viewDirectionChanged</code> handler is called when the player view changes, with a string to indicate which view the player is facing. Amongst its possible values are "VIEW_FORWARD", "VIEW_AFT", "VIEW_PORT", "VIEW_STARBOARD",
"VIEW_CUSTOM",
"VIEW_GUI_DISPLAY".

this.viewDirectionChanged = function(viewString)
{
if (viewString == "VIEW_PORT")
{
// Your code here
}
}

=== System population ===

In Oolite 1.79 and later, functions are called to populate and repopulate the system. These functions do not have fixed names, as they depend on the system, but otherwise act like normal worldscript functions. [[Oolite System Populator|The populator page]] has more documentation on these functions.

=== Defunct ===

==== <code>equipmentDestroyed</code> ====
''Handler no longer exists in current stable version 1.80''

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

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

==== <code>tickle</code> (removed in 1.77) ====

The <code>tickle</code> handler is called periodically-ish, whenever the old [[property list|plist]] scripts are updated. <code>tickle()</code> is deprecated. In new code, use appropriate event handlers or [[Oolite JavaScript Reference: Timer|timers]] instead.

=== Missing Events ===

All the initially planned events have been implemented in 1.74.

If there are other events you would like to be able to respond to, please write a request [http://www.aegidian.org/bb/viewtopic.php?t=3296 on the forum].

'''See also:''' [[Oolite JavaScript Reference: Ship script event handlers|ship script event handlers]]

[[Category:Oolite JavaScript Reference]]

OXP howto

2023-09-20T10:46:53Z

Alnivel: /* Config */ Replaced worldScripts.plist by world-scripts.plist

:''Shortcut: EW:OXP and EW:HOWDS redirect here''</br>
[[Image:oolite-oxp-icon.png|100px|right|OXP icon]]
==Overview==
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 first appearances, there is no way to tell what is inside, as it's merely a folder with the added extension '''.oxp'''.
Oolite Version 1.79 onwards supports also compressed files in ZIP format with extension '''.oxz'''.

To learn starting with a non-compressed version have a look at [[OXP_tutorial]].

{{QuoteText|Text=It's worth saying I think that compared with a lot of game addon architectures, the OXP architecture as designed by Giles is already very good at avoiding conflicts compared with a lot of other games
- you can save your game, add, remove and upgrade lots of OXPs, load your game, and have it work
- you can do this repeatedly, while incrementally upgrading the core game, for years
- as a player you basically never have to care about load order; as an OXP developer, rarely

It's also worth noting that a lot of types of OXP conflicts are inevitable due to resource conflicts - a planet can only have one diffuse map, a ship can only have one AI - or due to conceptual conflicts - OXP A removes all stations from a system; OXP B expects the player to dock there.|Source=([http://aegidian.org/bb/viewtopic.php?p=241733#p241733 Cim (3rd Lead Developer)])}}

=== Oolite TR version ===
The Oolite Developer Release/Test Release version is specially developed for testing out OXPs. It comes with a [[Debug OXP]]/Debug Console allowing one to spawn ships/station on demand, award oneself a test ship, detect the mass of another ship ''etc''.

It is downloaded from the main Oolite website - currently http://www.oolite.space/download/

== OXZ ==
The new OXZ distribution format is strongly recommended. It makes version control and distribution just so much easier.

To make an OXZ file, use a ZIP program to compress the contents of the OXP folder, so that the [[manifest.plist]] file is in the root of the ZIP file, and the folders (AI, Config, etc) are folders in the ZIP file. Then, rename the ZIP file so that its extension is '''.oxz'''. To inspect an OXZ file, open it with your ZIP program.

Here is a sample: [[Media:X.0.1.oxz]] - just rename all "X" within to the title of your idea and put your name into the author fields.

You can use [http://www.ghisler.com/download.htm Total Commander] or [http://en.wikipedia.org/wiki/Krusader Krusader] to edit files within '''.oxz''' directly, without unpacking.

For more details read [http://aegidian.org/bb/viewtopic.php?f=4&t=16688 The All-in-One Guide to OXZ Packaging and Distribution].

=== Creating an .oxz on an AppleMac ===
When you compress the files/folders on the AppleMac to create the .oxz ''do not'' select them with your mouse! This way lies misery!

Rather, ensure the relevant files/folders are inside one overall folder. Then, use '''command-a''' to select all the ''contents'' of this overall folder and then select '''compress''' from the file menu on the finder's menu bar. Finally, rename your newly-created .zip file as an .oxz

==Structure==
Inside the '''.oxp''' folder, or the '''.oxz''' file, it will at least contain a folder (Config, AIs, Models, Textures, etc...) that holds scripts, plists or other things like textures or models. It is down to the goal of the [[OXP]], which ways to combine elements to the OXP's contents. To get a feeling for it, simply take a look in other oxps. (If they are in .oxz format, any normal unzip program can inspect their contents - many will even let you edit the contents without having to unzip and rezip the file)

The structure for OXPs:
AddOns (folder)
-.oxp (folder) - Holds requires.plist, manifest.plist and the other folders
--> AIs (folder) - Holds AI plists
--> Config (folder) - Holds all other plists
--> Images (folder) - Holds background images
--> Models (folder) - Holds the .dat files
--> Music (folder) - Surprise - holds music files
--> Scenarios (folder) - Holds new game scenarios (v1.79)
--> Scripts (folder) - Holds scripts (worldScripts and shipScripts)
--> Shaders (folder) - Holds Vertex and Fragment shaders (v1.69)
--> Sounds (folder) - Holds sound files
--> Textures (folder) - Holds models textures
--> [[info.plist]] (file)
--> [[manifest.plist]] (file)

If the OXP is in the uncompressed OXP folder format, the .oxp folder must contain a [[requires.plist]] file. If it is in the compressed OXZ single-file format, it must contain a [[manifest.plist]] file.

===AIs===
The folder named AIs contains any AI.plist additions the OXP might use.

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

In Oolite 1.79 AIs may be written in Javascript using .js files in this folder. A helper library is provided to make writing complex JS AIs simpler.

* [[Oolite PriorityAI Documentation]]
* [[Oolite PriorityAI Tutorial]]

===Config===
All plist files except for those introducing new AIs, ''[[requires.plist]]'', ''[[manifest.plist]]'' or ''[[info.plist]]'', 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]]
<br>
This folder contains [[Property lists]] such as:

* ''[[characters.plist]]'' that adds non-player characters to Oolite.
* ''[[commodities.plist]]'' that contains information for each commodity in a market in 1.80 or earlier
* ''[[crosshairs.plist]]'' that contains the look for your weapons (v1.73).
* ''[[customsounds.plist]]'' that contains references to ingame used sounds.
* ''[[descriptions.plist]]'' that adds vocabulary to Oolite texts.
* ''[[effectdata.plist]]'' defines custom visual effects (v1.77).
* ''[[equipment.plist]]'' lists upgrades available from the Shipyard.
* ''[[explosions.plist]]'' customises things blowing up (v1.81)
* ''[[global-settings.plist]]'' sets a few miscellaneous universal settings (v1.81)
* ''[[gui-settings.plist]]'' settings for reformatting the GUI screens (v1.81)
* ''[[hud.plist]]'' and ''[[hud.plist|hud-small.plist]]'' that allows for changes or a radically new ''Head-Up Display''.
* ''[[illegal_goods.plist]]'' that contains a list of banned/forbidden items in 1.80 or earlier. GalCop has an eye on that.
* ''[[Oolite_Keyboard_Controls|keyconfig.plist]]'' that allows for changes of the keymapping.
* ''[[missiontext.plist]]'' contains texts for the mission screens.
* ''[[OXPMessages.plist]]'' adds warnings to testversions of an oxp.
* ''[[pirate-victim-roles.plist]]'' that defines which roles should act as traders. (deprecated in v1.79)
* ''[[planetinfo.plist]]'' that plots system specific changes from the default. May also contain ''script actions''.
* ''[[role-categories.plist]]'' for specifying groups of roles with similar properties (v1.79)
* ''[[scenarios.plist]]'' lists the starting scenarios in the Scenarios folder (v1.79).
* ''[[screenbackgrounds.plist]]'' that contains references to background images (v1.74).
* ''[[Scripting Oolite with JavaScript|script.js]]'' is the successor of [[script.plist]] in JavaScript. It will be loaded in preference to script.plist if both exist and offers more flexibility and improved possibilities.
* ''[[shipdata.plist]]'' that introduces any new entity (ships, stations, objects etc.) to Oolite.
* ''[[shipdata-overrides.plist]]'' that selectively can replace shipentries in other shipdata.plists
* ''[[shiplibrary.plist]]'' that gives information for the ship description library viewable from the startup screen (v1.79)
* ''[[shipyard.plist]]'' that introduces new ships available for player purchase.
* ''[[shipyard-overrides.plist]]'' that selectively can replace shipentries in other shipyard.plists
* ''[[speech_pronunciation_guide.plist]]'' is another of the other custom methods.
* ''[[trade-goods.plist]]'' defines trade goods in 1.81 and later
* ''[[world-scripts.plist]]'' that contains a list of scripts (if more than one worldScript should be used).

Deprecated:
* ''[[demoships.plist]]'' that selects demoships to show on startup (replaced - approximately - by shiplibrary.plist in 1.79 and later)
* ''[[script.plist]]'' to handle conditional ''script actions''. (deprecated)
* ''[[script.oos]]'' was briefly introduced during 1.70 development but is now deprecated in favour of JS.)

=== Models===
Oolite models need to be in an Oolite specific format using the the '''.dat''' file extension. 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 - case sensitive!!!

* [[OXP howto model|Making Oolite models]] - tutorials for Wings3D & Blender, notes on sub-entities, links ''etc''.
* [http://aegidian.org/bb/viewtopic.php?f=4&t=12165 Model Converter utilities] (2012-17)
* Video: [http://aegidian.org/bb/viewtopic.php?f=4&t=16123 From scratch to Mamba in under an hour] ([[Dertien]], 2013)

===Scripts===
Scripts are in text format. In this folder you can put both js scripts as well as legacy scripts. New OXPs should only use Javascript here.
* [[Scripting_Oolite_with_JavaScript|Scripting Oolite with Javascript]]
* [[Oolite_JavaScript_object_model|Scripting reference]]

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

* [[Smivs'_texture_tutorial|Smivs' guide to making Oolite textures]]

* [[Texturing tips and tricks by Theta Seven]]

Viewing a specific texture and / or model in Oolite.
"I made one. How do I proof it?"

* [[Viewing a Texture or Model]]

==OXP Verifier==

Oolite has what amounts to a spell checker for shipdata.plist and some other plists, called the OXP verifier. It does not work with OXZ's. The verifier detects unknown keys or wrong use of keys ''etc''. It can currently only be invoked from the command line.

On Windows or Linux:
Code:
'''oolite.app/oolite --verify-oxp <path to OXP> '''

On Mac OS X:
Code:
'''Oolite.app/Contents/MacOS/Oolite --verify-oxp <path to OXP>'''

Most Mac users will not be familiar with using the command line. Look inside your application folder for a '''utilities folder'''. Inside that you will find a program called [https://en.wikipedia.org/wiki/Terminal_(macOS) Terminal]. <br>
Run it to open a terminal window. Now drop the oolite application on that window. That will generate the path to oolite on the command line. Delete the trailing space and paste the following text - including the trailing space- behind it: "/Contents/MacOS/Oolite --verify-oxp ". Now drop the oxp you want to verify on the window. That will again create the path to the oxp behind the last entry. <br>
When you select the window and hit the <return> key, the verification will start. It should now open the Console program, showing the results. <br>
'''Console''' is a log viewer developed by Apple Inc. and included with macOS, also in the utilities folder. It allows users to search through all of the system's logged messages, and can alert the user when certain types of messages are logged. The Console is generally used for troubleshooting when there is a problem with the computer. MacOS itself, as well as any applications that are used, send a constant stream of messages to the system in the form of log files. The console allows you to read the system logs, help find certain ones, monitor them, and filter their contents. See [[Debug OXP]] for more information.

There is a lengthy file - '''OXP verifier design.txt''' tucked inside your Oolite installation with more information about it

Note that it is possible to [http://www.aegidian.org/bb/viewtopic.php?f=2&t=21443 obtain graphical output] from Graphviz for OXP Verifier.

=== BB thread ===
*[http://www.aegidian.org/bb/viewtopic.php?f=8&t=13400 plist Editor Pro for Windows] (2013 - full of relevant Red Herrings)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=21359 OXP Develoopment and Plist files] (2023 - quick introduction)

=== Correcting with plutil (Apple Macintosh Terminal utility) ===
Since a very small mistake is enough to stop a .plist from being accepted, it's important to be exact about every letter and sign. The Mac Terminal utility has a very practical tool for catching parser errors. After opening Terminal, simply type plutil, add one space, and drag and drop the plist in question onto the Terminal window. This will cause the 'address' of the plist to be shown. Hit return, and Terminal will reveal whether or not the plist is OK. If it's not, you might be given a clue to what is wrong, and the line number of the error - or just a general note that "Unexpected character { at line 1"!

==Unique names==
On loading the oxps, Oolite will add all files in the AIs, Models, Sound and Scripts folders in one big folder for its own use. That means that all files need unique names or one file will overwrite another with the same name. Files in Textures are not pre-loaded, but when looking for a specific texture Oolite looks in all Texture folders until it finds a texture file with a matching name. If another oxp contains a texture with identical name, Oolite could use that texture.

For the Config folder something similar happens. Here the plists all have the same name, but the content of all oxp plists is loaded per type in one big plist. e.g. all individual shipData.plist go in one big shipData.plist file. And within a single plist, all keys must be unique. When two plists use the same key, the later loading key will overwrite the former.

Generally it is a good habit to precede your chosen filenames and keys with the name of the oxp, or another unique prefix, to make sure the names stay unique and no other oxp will use the same names.

==Scripting with JavaScript==
Older OXPs (from [[User:Aegidian|Aegidian]]'s day were written in Legacy Script: see [[Methods]]. Modern OXPs are written in JavaScript. Specifically oolite.jsVersion 185, an Oolite specific variant of '''ECMAv5'''. It is the same Spidermonkey version that Firefox 4 shipped with many years ago, but it is a special build for Oolite. This is the version that we have almost always had and it has not changed between versions of the game. [http://aegidian.org/bb/viewtopic.php?p=256623#p256623 It is unlikely to change] in the future.

JavaScript is the preferred scripting interface for worldScripts and shipScripts. The legacy scripting interface (see [[script.plist]]) still works, but is not supported. See [[Scripting Oolite with JavaScript]] for more information.

Note that most of the [[Legacy Scripting]] still works perfectly well (XML & OpenStep)!

==Hidden settings==
There are several [[Hidden_Settings_in_Oolite]] that make life for an oxp creator easier. One of them is the setting '''always-flush-cache'''. It makes every startup a bit slower, but it prevents Oolite working with cached data instead of your newly changed file. For someone that only does occasional oxp changes it will be enough to flush the cache by holding the shift key when starting Oolite but if you are writing oxps, this is the way to prevent frustrations.

==Cookbook==
* How to add dials to a HUD: http://aegidian.org/bb/viewtopic.php?p=290352#p290352

== See Also ==
*'''Context''': [http://www.aegidian.org/bb/viewtopic.php?p=275434#p275434 What can OXP's ''not'' change?] (2021)
*It is often helpful to dip one's toes (claws?) in the water by experimenting with tweaking oxp's first: see [[How to tweak OXZ's]]
*[[:Category:Oolite scripting]]
*[[Javascript Operators]]
*[[:Category:Oolite JavaScript Reference‎]]
*[[:Category:Oolite Development]]
*[[User:Montana05|Montana05]] recommends https://www.w3schools.com/js/js_array_sort.asp for better knowledge of the js on Oolite.
*[http://aegidian.org/bb/viewtopic.php?f=4&t=12149 OXP Development Best Practices] (2012-7)
*Some older oxp's are written in [[Legacy Scripting]]
*[https://github.com/OoliteProject/oolite/find/master Github] vanilla game code repository - the resources section at the bottom of the page contains possibly useful parts of vanilla game coding, with occasional annotations.
=== Tools ===
*[[List of software]] that is helpful for creating OXPs (eg. editorial packages for javascript or 3D model creators)
*[[List of Planets used in OXPs]] for planets already used by other OXPs. Helps authors avoid overlapping with or breaking other OXPs.
*[[OXP_howto_Game_Balance|OXP howto Game Balance]] to avoid conflicts from accidental gameplay changes.
*[[Long Range Scanner]] is an OXP which allows you to jump around the star system to objects you have placed there - or to jump around within the galaxy. A "cheat" for players, but a useful tool for some OXP designers.

*[http://aegidian.org/bb/viewtopic.php?f=4&t=13422 What Tools Are Good For Windows OXP Programming?] (2013)

==== Tutorials for Tools ====
*[https://web.archive.org/web/20050317033938/http://oolite.aegidian.org/cyoship/ Oolite Tutorial - Meshwork Shipbuilding (OSX only)] via WayBack Machine
*[https://web.archive.org/web/20060621211940/http://oolite.aegidian.org/cyoship2/ Oolite Tutorial - Wings 3D Shipbuilding (Cross-platform)] via WayBack Machine

=== OXP tutorials ===
Oolite changes affecting different varieties of OXPs happened with v.1.76 (2011), v.1.80 (2014) & v1.82 (2015).
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20937 MasterClass: How to OXP (updating SoThisTC)] by [[User:Spara|Spara]] who teaches computing in Helsinki! (2021)
*[https://archive.org/details/GettingStartedWithOoliteOXZDevelopment Getting started with OXZ Development] ''An .odt for Open Office'': By Bugbear (2012). 2 example OXPs: a pirate-ridden solar systems warning tool & Witchspace Blockades [http://www.aegidian.org/bb/viewtopic.php?f=4&t=17731 BB Thread (2015)]
*[[OXP_tutorial|OXP Tutorial]] creating a new spaceship - and then tweaking it in different ways (2007-13)
*[[OXP howto dockable stations|Creating a dockable station]] (2009-10)
*[[User:Shipbuilder|Shipbuilder]] wrote a Shaders tutorial with resource packs (2013)

*[http://aegidian.org/bb/viewtopic.php?f=4&t=18837 OXP Performance] BB thread (mostly 2017-8): improving your OXP (speed, ''etc'')

*[https://aegidian.org/bb/viewtopic.php?f=4&t=18284 The bare minimum for a game-recognizable ship OXP] (thread: 2016)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=14135 How to make a simple OXP?] (thread: 2013) 3 OXPs - pop-up message at docking, set only Pythons for sale at Lave shipyard, create a new ship.

*[[Escape Pod Locator OXP]] has notes on programming on the bottom of the page regarding beacon transmission & location

=== Helpful OXPs for your OXP===
There are a number of OXPs which have been specifically written to allow your OXP to use them:
*[[Library OXP|Library]]: a collection of useful snippets and helpers. Its main purpose is to simplify or unify some common tasks used by OXPers.
:*It can add dynamic maps, music & animation.
:*It adds a Personal Assistant Device for the player with details of people met, medals awarded, Guild rankings, ''etc''.
:*It allows in-game configuration of an oxp by the player.
:*Add-on modules allows inspection of models and materials for creation of ship & station oxps.
*[[GalCop Missions]] introduces many new pieces of equipment with wide varieties of use (Cargo Stoppers, Ejection Dampers, Range Finders, Solar Radiation Disrupter Missiles, Seismic Resonance Scanners, Patient Transport Modules ''etc''). It can also help with managing missions.
*[[Diplomancy]] can be used to make states of war impact personally on the player
*[[System Data Config]] helps re-organise the F7 screen to squeeze more information onto it

==== While docked/stations ====
*[[HD Backgrounds]] can provide a High Definition screenshot of a station lobby or other such for interaction with the player
*[[BGS]] can help organise a customised docking or launching sequence (see the [[Riredi OXP]] or the [[Kiota Stations]]).
*[[GNN]] can broadcast your news alerts (see how [[Diplomancy]] uses it for war & peace declarations). GNN also contains '''PhraseGen''' which can be used for randomizing text descriptions.
*[[Station Validator]] will remember that a station has been destroyed and stop Oolite automatically replacing it on the next visit to the system
*[[Station Dock Control]] can help interraction with other ships docked at the station
*[[Bulletin Board System]] can help manage interractions at the station
*[[Email System OXP]] can also help manage interractions at the station
*[[Ship Storage Helper]] allows storage of the player's ship whilst doing other things (such as flying another ship!)
*[[Equipment Storage OXP]] allows storage of equipment/goods whilst doing other things
*[[Ship's Library]] allows reading documents with illustrations while docked (see the included Ship's Manual)
*[[Station Options]] allows complex configurations of equipment, but could potentially also be used for managing dialogue with NPCs
*[[Life in the Frontier]] was being expanded to cover more stations (Dodo/Ico/Rock Hermits and potentially OXP stations), but is currently mothballed.

==== In-flight ====
*[[MFD - Broadcast Comms]] can be used for in-flight interaction with NPC's
*[[Bigships]] can be used to help with the AI for massive space ships which cannot dock at orbital stations
*[[Montanas Resource Pack 01]] contains a number of resources for use (treasures, containers, escape/survival equipment)
*[[Star System Lane Indicator]] - the older version contains a very graphical dynamic display (does not function properly, but boy! does it look good!)
*[[SOTL Exploration]] contains exploration equipment and a non-automatic hyperspace jump
*[[SOTL Altmap]] contains different politics, markets and NPCs with Torus Drives.
*[[Resistance Commander]] & [[EscortDeck]] contain mechanisms for "managing" allied ships.

==== Planet Surfaces ====
*[[Planetfall OXP]] allows landing on the planet (used by [[Feudal States]] for access to the Royal Court, and by [[Astronaut]] for space-jumping)
*[[Lave is Earth 8k]] contains night-time city lighting

=== Packaging and distribution ===
*[http://aegidian.org/bb/viewtopic.php?f=4&t=16688 The All-in-One Guide to OXZ Packaging and Distribution].
::And see [http://aegidian.org/bb/viewtopic.php?p=279034#p279034 this post] for AppleMac issues with the above.
*[[OXP Distribution]] The All-in-One Guide to OXP Packaging and Distribution (and [[OXP_standards]] for advice on which ways of doing things are supported and which are not).

*[[Gameplay_and_Balance_Indicator|Gameplay Balance Indicator]] and [[OXP_Levelindicators|Difficulty Indicator]]. Add these to your wiki page to show effects on Game Balance and the Difficulty Level of your OXP/OXZ. The '''first''' indicates the impact on play (equipment making the game easier/more difficult), the '''second''' indicates the suggested [[Elite Rating]] needed to attempt the mission/defeat the ship ''etc''.

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

Illegal goods.plist

2023-09-20T10:44:53Z

Alnivel: Tweaked to redirect to the section directly

#REDIRECT [[Misc_plists#illegal_goods.plist]]

Misc plists

2023-09-20T10:41:10Z

Alnivel: /* world-scripts.plist */ Replaced worldScripts.plist by world-scripts.plist, tweaked text

----
=crosshairs.[[plist]]=

== Structure ==

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

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

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

----
=descriptions.[[plist]]=

== Structure ==

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

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

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

== Use ==

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

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

You have to pick up [parcelnumbers] parcels.

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

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

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

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

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

----
=demoships.[[plist]]=

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

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

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

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

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

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

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

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

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

----
=info.[[plist]]=
This does not actually seem to do anything other than give the human being reading it some information! [[Galactic Navy OXP]] has one, as do ''inter alia'' [[User:Mandoman|Mandoman]]'s many oxps.

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

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

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

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

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

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

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

----
=OXPMessages.[[plist]]=

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

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

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

----
=world-scripts.[[plist]]=

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

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

==Content==
To know what to put into such a world script, see [[Oolite_JavaScript_Reference:_World_script_event_handlers|the list of world script event handlers]].

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

==Note==
There are two ways of storing a JS worldscript:

1) Old: You can name it "script.js" and put it into the Config folder. That's what cim did in his [[Galactic Misjump OXP]]. It's a leftover of "legacy" plist scripting, where the script had to be named "script.plist" and reside in the Config folder. This way was especially useful in the time when we had Oolite 1.65 as official release, and the growing number of test releases. In those times you could have both a "script.plist" and a "script.js" alongside each other in the Confic folder. Oolite 1.65 would use the plist script, and the later versions would ignore the plist and use the JS script instead. This functionality is not particularly useful anymore, but it still exists.<br>
2) New: You can name it whatever you want (but perhaps not "script.js") and put it into the Script folder. Then you have to create another plist in the Config folder named "world-scripts.plist" and write the name of your script into that plist. This method has the advantage that you can have more than one worldscript in an OXP, which is of course not possible with the first method, because there can only be one file named "script.js" in a Config folder. [http://www.aegidian.org/bb/viewtopic.php?p=170774#p170774 Commander McLane (2012)]

----

=whitelist.[[plist]]=

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

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

This plist cannot be extended or overriden by OXPs.

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

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

[[Category:Oolite scripting]]

----
=See also=
* [[OXP howto]]

Pirate-victim-roles.plist

2023-09-20T10:24:46Z

Alnivel: Tweaked to redirect to the section directly

#REDIRECT [[Misc_plists#pirate-victim-roles.plist]]

Crosshairs.plist

2023-09-20T10:24:06Z

Alnivel: Tweaked to redirect to the section directly

#REDIRECT [[Misc_plists#crosshairs.plist]]

Demoships.plist

2023-09-20T10:23:04Z

Alnivel: Tweaked to redirect to the section directly

#REDIRECT [[Misc_plists#demoships.plist]]

WorldScripts.plist

2023-09-20T10:22:12Z

Alnivel: Tweaked to redirect to the section directly

#REDIRECT [[Misc_plists#world-scripts.plist]]

OXPMessages.plist

2023-09-20T10:19:36Z

Alnivel: Tweaked to redirect to the section directly

#REDIRECT [[Misc_plists#OXPMessages.plist]]

Planetinfo.plist

2023-06-21T19:58:24Z

Alnivel: /* Government */ Fixed typo

'''planetinfo.[[plist]]''' in 'AddOns/Config' contains a dictionary for each of systems for which you wish to set custom data. A list of all galaxies and planets can be found [[Oolite planet list|here]]. Each of the properties mentioned below can be set (but, notably, not the location of the main planet, which is hard coded into the system seed value):

=== Added for Oolite v.1.91 ===
*air_density / or the Javascript planet entity airDensity - see below (pretty picture!)

=== Added for Oolite v.1.89 ===
This needs editing by somebody who understands it! Snatched from the Progress thread
*[http://aegidian.org/bb/viewtopic.php?p=270737#p270737 air_color] now produces the right color for the sky. Not only that, it is now used as the atmosphere scatter color when the planet is viewed from space. Non-blue atmospheres are finally possible!
*[http://aegidian.org/bb/viewtopic.php?p=270771#p270771 air_color_mix_ratio]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 terminator_threshold_vector shipdata key]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 JSPlanet terminatorThresholdVector property]
*[http://aegidian.org/bb/viewtopic.php?p=269833#p269833 MULTIPLIER_LIGHTSRCRADIANCE and MULITPLIER_EXPOSURE]: Planet, ships and atmosphere shaders can now define lightsource radiance and scene exposure multipliers
*Also stuff about city lights
*And probably other stuff I missed!

=Where Settings Apply=

==Universal Settings==

Some options can be applied to the entire universe, such as ambient lighting levels, eg.
"universal" =
{
...
}
Universal options can be over-ridden by specifying the same option for a specific system or location in interstellar space. Obviously, not all options make sense to apply to the whole universe.

==Interstellar Space==

Conditions for interstellar space in general can be set with the “interstellar space” key.

==Specific Systems==

Each system is keyed by a string consisting of the galaxy number (0..7) followed by a space and then the planet number (0..255), eg.
"0 7" =
{
...
}
specifies system 7, in galaxy 0, ''Lave''.

==Specific Interstellar Spaces==

You can also specify a position in interstellar space, eg.
"interstellar: 0 7 129" =
{
...
}
specifies the space in galaxy 0 between systems 7 and 129, ''Lave'' and ''Zaonce''.

In 1.81 the property "link_color" when set on a specific interstellar space changes the colour of the link between the two systems in the advanced navigation array (assuming no route is in place above it).

Note that
"interstellar: 0 7 129" = // jumping from Lave towards Zaonce
{
...
}
and
"interstellar: 0 129 7" = // jumping from Zaonce towards Lave
{
...
}
are distinct locations and if they both need the same properties this must be explicitly set for both. When setting link_color, the lower system ID must be placed first, because of how the chart is drawn.

==Layers==

Settings other than "universal" in Oolite 1.81 or later have a 'layer' property from 0 to 3. The default value for planetinfo.plist files is 1. If multiple OXPs specify a setting for a particular property, the order they will be checked in is:
* Layer 3 settings
* Layer 2 settings (default for Javascript changes to data)
* Layer 1 settings (default for planetinfo.plist)
* Universal settings
* Layer 0 settings (value for core game settings)

This allows OXPs to safely override each other's changes if necessary, and for OXPs which really need a specific setting in a particular system to set it at layer 3

Example
"layer" = 2;

==Terraforming Example==

For the planet Lave, you would use the key '0 7' (planet 7 in galaxy 0) Then you set the values. The following example sets Lave's sea to blue, land to green, and land to sea ratio to 75%.

Code:
{
"0 7" =
{
"percent_land" = "75";
"land_color" = "0.5 1.0 0.5";
"sea_color" = "0.3 0.7 1.0";
}
}

Then you can override any of the settings listed above, for example to change Zaatxe's (Galaxy 0 Planet 8) inhabitants into blue frogs you'd enter

Code:
"0 8" =
{
"inhabitants" = "Blue Frogs";
}

You can use any or all of the keys in each of the entries. It's probably best to only use the key's you want to change. So, another example, to change the sky_blur_xxx settings for Zaonce (Galaxy 0 Planet 129) to big, heavily clustered, but pale blurs - you'd enter

Code:
"0 129" =
{
"sky_blur_cluster_chance" = "0.9";
"sky_blur_alpha" = "0.1";
"sky_blur_scale" = "32.0";
}

=About the Inhabitants=

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

An integer that determines how much information about the system is unknown.

Example:
"concealment" = "300";
The following values are recognised:
* 0: default, all information visible
* 100 or more: F7 screen shows no information, economy/government/TL/star colour not visible on chart
* 200 or more: system name is not shown
* 300 or more: system vanishes entirely from chart, will not be used in route plotting, cannot be targeted by player (NPCs can still jump to it, though)

==Government==

An integer between 0 and 7 indicating the government type of the system.

Example:
"government" = "7";

Possible values:
: 0: Anarchy
: 1: Feudal
: 2: Multi-Governmental
: 3: Dictatorship
: 4: Communist
: 5: Confederacy
: 6: Democracy
: 7: Corporate State

==Economy==
An integer between 0 and 7 indicating the economy type of the system.

Example:
"economy" = "5";

Possible values:
: 0: Rich Industrial
: 1: Average Industrial
: 2: Poor Industrial
: 3: Mainly Industrial
: 4: Mainly Agricultural
: 5: Rich Agricultural
: 6: Average Agricultural
: 7: Poor Agricultural

==Tech Level==

An integer between 0 and 14 indicating the sophistication of the planets technology. The tech level displayed on the system data screens in game is one higher than this number (range 1 to 15).

Example:
"techlevel" = "13";

==Population==

An integer between 0 and 67 indicating the number of inhabitants of a planet in hundreds of millions

Example:
"population" = "23";

==Productivity==

An integer indicating the productivity of a planet.

Example:
"productivity" = "1000";

==Name==

The name of the planet.

Example:
"name" = "The planet's name";

==Inhabitant==

The name for one of the inhabitants of the main planet.

Example:
"inhabitant" = "Green Platypus";

==Inhabitants==

The name of the inhabitants of the main planet.

Example:
"inhabitants" = "Green Platypi";

==Description==

A short description of the planet.

Example:
"description" = "Really, anything you want to say about the place!";

==Government Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the government.

Example:
"government_description" = "Dictatorship (Monarchy)";

==Economy Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the economy.

Example:
"economy_description" = "Mainly Industrial (Machine Tools)";

==Population Description==
{{oolite-prop-added|1.77}}

Overrides the default text used to describe the population.

Example:
"population_description" = "13 Billion";

==Random Seed==
{{oolite-prop-added|1.81}}

A seed for a random number generator used in Oolite 1.81 to generate system properties impractical to store in this file (e.g. the positions of each star on the background starfield)

For historical reasons, this is a string of 6 integers between 0 and 255, for example:
random_seed = "74 90 72 2 83 183";

=System population=
These properties are only used in Oolite 1.79 or later.

==Populator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|populate the system]]

Example:
"populator" = "systemWillPopulate";

==Repopulator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|repopulate the system]]

Example:
"repopulator" = "systemWillRepopulate";

=Properties of the Planet=

Most of these properties are ignored if a planet texture is set.

Note that the available planet texture generator properties changed in places between Oolite 1.77 and Oolite 1.80

==Air Color==
A colour specifier determining the color of the planet's sky, as well as the atmosphere scatter color.

Example:
"air_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Air Color Mix Ratio==
{{oolite-prop-added|1.89}}

The amount of air color that be mixed in the overall atmosphere color. A number from 0.0 to 1.0 (default 0.5).

Example:
"air_color_mix_ratio" = "0.0..1.0";

==Atmosphere Rotational Velocity==

Sets how fast the atmosphere is rotating. (A random value between 0.0 to 0.03 is the default).

Example:
"atmosphere_rotational_velocity" = "0.1";

==Cloud Alpha==
{{oolite-prop-added|1.77}}

The transparency level of the cloud layer, relative to the standard transparency. 1.0 is the default. Texture packs which include clouds on the planetary texture may wish to reduce this.

Example:
"cloud_alpha" = "0.2";

==Has Atmosphere==
{{oolite-prop-added|1.81}}

This boolean property is used for the main planet only. If it is unset or true, the main planet has an atmosphere, as is always the case in 1.80 and before. If it is set to be false, then the planet will not have an atmosphere.

Example:
"has_atmosphere" = 0;

This has no effect on secondary planets - their atmosphere is determined by whether addition uses <code>addPlanet</code> or <code>addMoon</code>.

[[File:AtmDensityExample.png|thumb|320px|right|Atmosphere Density examples: Stranger's ''FPO Lave'' in four increasing atmosphere densities: 0.2, 0.5, 0.75 and 1.0. Every other parameter in the planet definition is the same in all pictures.]]
== Air Density ==
{{oolite-prop-added|1.91}}

A number clamped in range from 0.0 to 1.0 describing the density of the planet's atmosphere. All planets in the core use 0.75 as default.

Example:
"air_density" = "0.0..1.0";

==Illumination Color==
{{oolite-prop-added|1.91}}

A colour specifier determining the colour of the planet's illumination such as cities light. Illumination is inserted as a grayscale map in the alpha channel of the planet's diffuse texture. You can specify this key even if no illumination map is defined, but it won't have any effect - without an illumination map the dark side of the planet remains dark in all cases.

Example:
"illumination_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Land Color==

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Percent Cloud==
The percentage of the planet's atmosphere occupied by clouds.

Example:
"percent_cloud" = "0..100";

Note that with a low cloud_alpha setting not all of the clouds defined here may actually be visible

==Percent Ice==
The percentage of the planet occupied by the polar ice caps. Oolite 1.81 or later.

Example:
"percent_ice" = "0..100";

==Percent Land==
The percentage of the planet occupied by land.

Example:
"percent_land" = "0..100";

==Planet Distance==
{{oolite-prop-added|1.81}}

The distance from the centre of the planet to the witchpoint. Only used for the system main planet - secondary planets are positioned separately.

Example:
"planet_distance" = "410000";

The main planet is always positioned on the z-axis.

==Planet Distance Multiplier==
{{oolite-prop-added|1.81}}

Multiplies the distance from the centre of the main planet to the witchpoint.

Example:
"planet_distance_multiplier" = "1.5";

==Planet Name==
{{oolite-prop-added|1.79}}

The planet's name. For the main planet, this defaults to being the same as the system name - the property is mainly intended for secondary planets.

Example
"planet_name" = "Earth";

==Polar Land Color==
{{oolite-prop-added|1.81}}

Sets the land colour in polar regions.

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Polar Sea Color==
{{oolite-prop-added|1.81}}

Sets the sea colour in polar regions.

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Radius==
An integer between 3000 and 7000 indicating the radius of the main planet. On the F7 screen, this is measured in kilometres. The radius in game is 1/100th of this.

Example:
"radius" = "5500";

==Rotational Velocity==
A number describing the rotational velocity of the planet in radians per second. Overrides rotation_speed if both are set.

Example:
"rotational_velocity" = 0.0015;

==Rotation Speed==
A number describing the rotational velocity of the planet in radians per second. Unlike rotational_velocity, this is affected by rotation_speed_factor.

Example:
"rotation_speed" = 0.0015;

==Rotation Speed Factor==
The rotational speed of all planets whose rotational speed was set by rotation_speed and not by rotational_velocity will be multiplied by this number.

Example:
"rotation_speed_factor" = 1.0;

(Intended more for the universal section as a "personal taste" option than for individual planets)

==Sea Color==

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Terminator Threshold Vector==
{{oolite-prop-added|1.89}}

This property gives control over the color of the planet's terminator. The way the property works is not entirely straightforward, so see [http://aegidian.org/bb/viewtopic.php?p=271058#p271058 this post on BB] for more information.

Example:
"terminator_threshold_vector" = "0.0..1.0 0.0..1.0 0.0..1.0";
By default the terminator vector is "0.105 0.18 0.28" - which results in a reddish orange colour.

==Texture==
The replacement texture to be used by a system's main planet.<br>

For textures you can use lat-long maps (twice as wide as high) with a special elongation at the poles or cube maps. Other maps also will be wraped around planets but give always distortions.<br>
Since Oolite 1.74 you can also use cube maps for planets. Cube maps are 6 times higher as wide and will be recognised automatic by Oolite, based on its dimensions. Cube maps are the preferred method because lat-long give some distortion and have the poles improperly placed in Oolites implementation. See also [[Planettool]] for conversion from lat-long into cube maps.

From Oolite 1.89 onwards, illumination mapping on custom planets is supported. The illumination map goes in the diffuse map's alpha channel. Low alpha values translate to high illumination. This allows for effects like city lights on a planet's dark side.

Example:
"texture" = "newPlanetTexture.png";
;N.B.
The illumination mapping feature is disabled by setting ''Graphics Detail: Shaders Enabled'' or lower in the game setting menu. ''Enabled'' at ''Graphics Detail: Extra Detail''.

==Texture HSB Color==
This changes the overall hue of the replacement texture.

Example:
"texture_hsb_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Texture NormSpec==
{{oolite-prop-added|1.89}}

The external texture that will be used as a normal and specular map for the given planet. Colorspace should be linear, with the normal map in the r,g and b and the specular map in the a channel. The texture can be of either equirectangular or cubemap formats. This feature is available at the Extra Detail setting only. To set:
"texture_normspec" = "planetNormalAndSpecularMap.png";

=Properties of the Sky=

==Ambient Level==

Sets how much ambient light (shed by stars and nebulae) illuminates the dark side of objects like planets and ships. Values should typically be between 0.0 and 1.0 (1.0 is the default) but can be higher for a flat lit, cartoon-like effect.

Example:
"ambient_level" = "0.0";

==Nebula Count Multiplier==
This is used for defining the number of nebulas. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"nebula_count_multiplier" = "1.5";

==Sky Blur Alpha==
Default 0.1

Example:
"sky_blur_alpha" = "0.0 .. 1.0";

==Sky Blur Cluster Chance==
This is used for creating nebulae (typically 0.80)

Example:
"sky_blur_cluster_chance" = "0.85";

==Sky Blur Scale==
Default 10. Larger numbers generate bigger nebula, but slow down the game considerable on slower machines.

Example:
"sky_blur_scale" = "0.0 .. 128.0 or more";

==Sky N Blurs==
This is used for defining the number of nebulas (typical is 80, maximum is 1280). This key is multiplied by a "nebula_count_multiplier" definition in Oolite 1.81 or later.

Example:
"sky_n_blurs" = "800";

==Sky N Stars==
This is used for defining the number of stars (typical = 600, maximum in 1.76 or earlier is 4800). This key is multiplied by a "star_count_multiplier" definition in Oolite 1.81 or later. In reduced detail mode, this number will be capped to 2400.

Example:
"sky_n_stars" = "1200";

==Sky and Nebula RGB Colors==

These are rgb values (from 0.0 to 1.0) for the two colours between which the colour of the stars (and nebulaesque blurs) vary, ordered r1 g1 b1 r2 g2 b2 where (r1 g1 b1) defines the first colour and (r2 g2 b2) the second.<br>
(Default values are "0.75 0.8 1.0 1.0 0.85 0.6")

Example:
"sky_rgb_colors" = "0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0";

Alternatively, two [[Materials in Oolite#Colour specifiers|colour specifiers]] may be used:
"sky_color_1" = "redColor";
"sky_color_2" =
{
"hue" = "60";
"brightness" = "0.8";
}

"nebula_color_1" = "greenColor";
"nebula_color_2" = "blueColor";

==Star Count Multiplier==
This is used for defining the number of stars. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"star_count_multiplier" = "0.5";

=Properties of the Station=

==Market==
The market to be used in this system as the default market. It points to a key in commodities.plist

Example:
"market" = "rockhermit";
Will use the rockhermit market as default for for all stations in the system. When no market is defined a key in commodities.plist is used that matches the role of the main station. Than that is not defined, the default market is used in this system.

In 1.81 and later, this is replaced by market_script

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

A Javascript file used to load a [[Oolite Market Scripts|market script]] for global system price and quantity modifications.

"market_script" = "myoxp_newsystemmarket.js";

==Station==
The type of station orbiting the main planet.

Example:
"station" = "coriolis..dodec..special";

==Station Roll==
The speed at which the station rotates (as with all rotational velocities this is in radians per second) and affects all rotating stations in a system. For a specific station you can use the key [[Shipdata.plist#station_roll | station_roll]] in shipdata.plist.

Example:
"station_roll" = "0.5";

==Station Vector==
The direction of the main station from the main planet

Example:
"station_vector" = "-0.717 -0.668 0.201";

==Stations Require Docking Clearance==

Specifies if a player has to explicit ask docking permission. See also [[Oolite_Docking_Clearance_Protocol_%28v1.72_or_later%29|Oolite Docking Clearance]]

=Properties of the Sun=
;N.B.
The corona effect, modified by the first three properties mentioned below, is disabled by setting ''Reduced Detail:On'' in the game setting menu. ''Enabled'' by default (''Reduced Detail:Off'').

==Corona Flare==

Sets the overall size of the corona in proportion to its sun. (See note above.)

A number from 0.0 (invisibly small) to 1.0 (huge)

Example:
"corona_flare" = "0.075";

==Corona Hues==

Specifies whether the corona should have visible bands of colours within the corona. (See note above.)

A number from 0.0 (monochromatic) to 1.0 (vivid alternating colours).

Example:
"corona_hues" = "0.6";

==Corona Shimmer==

Specifies how quickly the corona colours change. (See note above.)

A number from 0.0 (very slow) to 1.0 (very fast).

Example:
"corona_shimmer" = "0.4";

==Sun Color==

Sets the colour of a system's sun.

Can be any [[Materials in Oolite#Colour specifiers|colour specifier]] or [[Materials in Oolite#Named colours|named colour]]. The specified colour is blended with 50% white so it will never be a saturated colour. Dark colours will be brightened by this blending.

Example:
"sun_color" = "blueColor";

==Sun Distance==
{{oolite-prop-added|1.81}}

Sets the distance between the sun and the main planet in metres.

Example:
"sun_distance" = 924122;

Ignored if sun_distance_modifier is set.

==Sun Distance Multiplier==
{{oolite-prop-added|1.81}}

Multiplies the distance between the sun and the main planet by this factor.

Example:
"sun_distance_multiplier" = 2;

Ignored if sun_distance_modifier is set.

==Sun Distance Modifier==

Sets the approximate distance between a system sun and its main planet. The standard distance is 20 planetary radii. Setting it much lower (10, or even less) will cause delays when generating systems, as Oolite compensates for possible collisions between the sun and other system objects.

Example:
"sun_distance_modifier" = "15.0";

In Oolite 1.81 or later, sun_distance_multiplier is more useful.

== Sun Gone Nova ==

Sets a nova sun in the system.

Example:
"sun_gone_nova" = "YES";

==Sun Name==

Stores the name of a system's sun. This is only implemented in Oolite from version 1.79 onwards, though was used by OXPs before then.

Example:
"sun_name" = "Alpha Centauri";

==Sun Radius==

Sets the radius of a system's sun. A number between 1000 and 1000000.

Example:
"sun_radius" = "100000";

==Sun Vector==
The direction of the sun from the main planet

Example:
"sun_vector" = "-0.717 -0.668 0.201";

=Hyperspace Travel=

In Oolite 1.81 and later these properties have been moved into [[global-settings.plist]]

==Galactic Hyperspace Behaviour==

The key galactic_hyperspace_behaviour controls where the player will arrive after a G.H. has been executed. There are three possible types of G.H. behavior and are as follows:

1) Oolite standard. This is what we have up to this moment. Executing a G.H. jump will poisition the player in the next galaxy, to the closest non-isolated system with regards to their current galaxy coordinates. So, for example, if you jump from coordinates (100, 50) in galaxy 1 you will arrive in galaxy 2 at the same coordinates, unless these coordinates refer to an unreachable system, in which case the arrival point will be adjusted by the engine to maybe something like (102, 51). This is set as default behavior. It is set by assigning the string BEHAVIOUR_STANDARD to the galactic_hyperspace_behaviour key.

2) All systems reachable. Same as above, only this time we do not check for arrival at an isolated system. Using this method, systems like Oresrati in G8, the lower left hand cluster of systems in G7, the two islands of isolated systems in G6 etc. are now possible arrival points. If you land there, you may not be able to exit again, depending on the tech levels of the systems you get to. Mission scripters may want to use this. This behaviour is set by assigning the string BEHAVIOUR_ALL_SYSTEMS_REACHABLE to galactic_hyperspace_behaviour key in planetinfo.plist.

3) Fixed coordinates arrival point. This will make Oolite simulate some older 8-bit versions, that were putting the player in the same fixed point every time a galactic jump was performed, but there is also good potential for scripting (see below). This is set by assigning the string BEHAVIOUR_FIXED_COORDINATES to the galactic_hyperspace_behaviour key.

==Galactic Hyperspace Fixed Coords==

If the fixed coordinates method is chosen, then the engine will look in planetinfo.plist for a key named galactic_hyperspace_fixed_coords, from which it will read the actual coordinates that will be used as the arrival point in the next galaxy. If none is found, then coordinates (96,96) will be used.

==Hyperspace Tunnel Color==

One or two colours can be set, using RGBA format, to over-ride the appearance of the hyperspace tunnel effect.
Example:

hyperspace_tunnel_color_1 = (1.0, 0.0, 0.0, 0.5);
hyperspace_tunnel_color_2 = (0.0, 0.0, 1.0, 0.25);



=Additional Planets=

Finally you can also define your own custom planets and moons:
"LavesPurpleMoon" =
{
...
}


To add them to the system, use JS methods <code>[[Oolite_JavaScript_Reference:_System#addPlanet|system.addPlanet]]</code> and <code>[[Oolite_JavaScript_Reference:_System#addPlanet|system.addMoon]]</code>. For the example above, the <code>planetInfoKey</code> will be <code>"LavesPurpleMoon"</code>.

==Position==
Position of the planet in space. The first parameter is 3-character code of the coordinate system, other three is x, y and z components of position vector.
"position" = "pwm 0 -50000 0";

You can omit the coordinate system parameter, then the absolute coordinate system will be used:
"position" = "0 -50000 0";

See [[Oolite coordinate systems]] for more info about it.

==Orientation==
Orientation of the planet in space (seems not to be working correct).

Example:
"orientation" = "0.0 1.0 0.0 0.0";

==Other keys==

You can use other keys from the [[#Properties_of_the_Planet| Properties of the Planet]] section for your planets and moons.

Here are some of the keys you may want to use:
* "radius": Radius of the planet in km. e.g. a value of 500 is drawn with a radius of 5000 meters but in player dialogues this value is presented as 500 km.
* "rotational_velocity": Rotation of the planet in rotations per second.
* "texture": The name of the texture file that is used to wrap around the surface.
* "seed": Seed value used to create the planet's surface features. If no seed is defined it uses the same seed as the main planet, and will create a copy of it.

= Links =
*[[Random number generator]] - originally used for creating planet descriptions
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=3860 seed = "1 2 3 4 5 6";]: Psuedo-random number generation & planet descriptions (2007)
*[http://aegidian.org/bb/viewtopic.php?f=4&t=3808 position = "x y z" in planetinfo.plist] (2007)
*Submersible's [https://www.youtube.com/user/submersibletoaster YouTube videos] of planet textures (2012)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=5044 Question: How to add custom planet descriptions] (2008)
*[http://aegidian.org/bb/viewtopic.php?p=217053#p217053 Tweaking your skies] (Tricky, 2014)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20959 Empty system] Removing the stations (and presumably inhabitants) from a system (2021)

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

Planetinfo.plist

2023-06-21T19:53:58Z

Alnivel: Added the missing planet_distance_multiplier

'''planetinfo.[[plist]]''' in 'AddOns/Config' contains a dictionary for each of systems for which you wish to set custom data. A list of all galaxies and planets can be found [[Oolite planet list|here]]. Each of the properties mentioned below can be set (but, notably, not the location of the main planet, which is hard coded into the system seed value):

=== Added for Oolite v.1.91 ===
*air_density / or the Javascript planet entity airDensity - see below (pretty picture!)

=== Added for Oolite v.1.89 ===
This needs editing by somebody who understands it! Snatched from the Progress thread
*[http://aegidian.org/bb/viewtopic.php?p=270737#p270737 air_color] now produces the right color for the sky. Not only that, it is now used as the atmosphere scatter color when the planet is viewed from space. Non-blue atmospheres are finally possible!
*[http://aegidian.org/bb/viewtopic.php?p=270771#p270771 air_color_mix_ratio]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 terminator_threshold_vector shipdata key]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 JSPlanet terminatorThresholdVector property]
*[http://aegidian.org/bb/viewtopic.php?p=269833#p269833 MULTIPLIER_LIGHTSRCRADIANCE and MULITPLIER_EXPOSURE]: Planet, ships and atmosphere shaders can now define lightsource radiance and scene exposure multipliers
*Also stuff about city lights
*And probably other stuff I missed!

=Where Settings Apply=

==Universal Settings==

Some options can be applied to the entire universe, such as ambient lighting levels, eg.
"universal" =
{
...
}
Universal options can be over-ridden by specifying the same option for a specific system or location in interstellar space. Obviously, not all options make sense to apply to the whole universe.

==Interstellar Space==

Conditions for interstellar space in general can be set with the “interstellar space” key.

==Specific Systems==

Each system is keyed by a string consisting of the galaxy number (0..7) followed by a space and then the planet number (0..255), eg.
"0 7" =
{
...
}
specifies system 7, in galaxy 0, ''Lave''.

==Specific Interstellar Spaces==

You can also specify a position in interstellar space, eg.
"interstellar: 0 7 129" =
{
...
}
specifies the space in galaxy 0 between systems 7 and 129, ''Lave'' and ''Zaonce''.

In 1.81 the property "link_color" when set on a specific interstellar space changes the colour of the link between the two systems in the advanced navigation array (assuming no route is in place above it).

Note that
"interstellar: 0 7 129" = // jumping from Lave towards Zaonce
{
...
}
and
"interstellar: 0 129 7" = // jumping from Zaonce towards Lave
{
...
}
are distinct locations and if they both need the same properties this must be explicitly set for both. When setting link_color, the lower system ID must be placed first, because of how the chart is drawn.

==Layers==

Settings other than "universal" in Oolite 1.81 or later have a 'layer' property from 0 to 3. The default value for planetinfo.plist files is 1. If multiple OXPs specify a setting for a particular property, the order they will be checked in is:
* Layer 3 settings
* Layer 2 settings (default for Javascript changes to data)
* Layer 1 settings (default for planetinfo.plist)
* Universal settings
* Layer 0 settings (value for core game settings)

This allows OXPs to safely override each other's changes if necessary, and for OXPs which really need a specific setting in a particular system to set it at layer 3

Example
"layer" = 2;

==Terraforming Example==

For the planet Lave, you would use the key '0 7' (planet 7 in galaxy 0) Then you set the values. The following example sets Lave's sea to blue, land to green, and land to sea ratio to 75%.

Code:
{
"0 7" =
{
"percent_land" = "75";
"land_color" = "0.5 1.0 0.5";
"sea_color" = "0.3 0.7 1.0";
}
}

Then you can override any of the settings listed above, for example to change Zaatxe's (Galaxy 0 Planet 8) inhabitants into blue frogs you'd enter

Code:
"0 8" =
{
"inhabitants" = "Blue Frogs";
}

You can use any or all of the keys in each of the entries. It's probably best to only use the key's you want to change. So, another example, to change the sky_blur_xxx settings for Zaonce (Galaxy 0 Planet 129) to big, heavily clustered, but pale blurs - you'd enter

Code:
"0 129" =
{
"sky_blur_cluster_chance" = "0.9";
"sky_blur_alpha" = "0.1";
"sky_blur_scale" = "32.0";
}

=About the Inhabitants=

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

An integer that determines how much information about the system is unknown.

Example:
"concealment" = "300";
The following values are recognised:
* 0: default, all information visible
* 100 or more: F7 screen shows no information, economy/government/TL/star colour not visible on chart
* 200 or more: system name is not shown
* 300 or more: system vanishes entirely from chart, will not be used in route plotting, cannot be targeted by player (NPCs can still jump to it, though)

==Government==

An integer between 0 and 7 indicating the government type of the system.

Example:
"goverment" = "7";

Possible values:
: 0: Anarchy
: 1: Feudal
: 2: Multi-Governmental
: 3: Dictatorship
: 4: Communist
: 5: Confederacy
: 6: Democracy
: 7: Corporate State

==Economy==
An integer between 0 and 7 indicating the economy type of the system.

Example:
"economy" = "5";

Possible values:
: 0: Rich Industrial
: 1: Average Industrial
: 2: Poor Industrial
: 3: Mainly Industrial
: 4: Mainly Agricultural
: 5: Rich Agricultural
: 6: Average Agricultural
: 7: Poor Agricultural

==Tech Level==

An integer between 0 and 14 indicating the sophistication of the planets technology. The tech level displayed on the system data screens in game is one higher than this number (range 1 to 15).

Example:
"techlevel" = "13";

==Population==

An integer between 0 and 67 indicating the number of inhabitants of a planet in hundreds of millions

Example:
"population" = "23";

==Productivity==

An integer indicating the productivity of a planet.

Example:
"productivity" = "1000";

==Name==

The name of the planet.

Example:
"name" = "The planet's name";

==Inhabitant==

The name for one of the inhabitants of the main planet.

Example:
"inhabitant" = "Green Platypus";

==Inhabitants==

The name of the inhabitants of the main planet.

Example:
"inhabitants" = "Green Platypi";

==Description==

A short description of the planet.

Example:
"description" = "Really, anything you want to say about the place!";

==Government Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the government.

Example:
"government_description" = "Dictatorship (Monarchy)";

==Economy Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the economy.

Example:
"economy_description" = "Mainly Industrial (Machine Tools)";

==Population Description==
{{oolite-prop-added|1.77}}

Overrides the default text used to describe the population.

Example:
"population_description" = "13 Billion";

==Random Seed==
{{oolite-prop-added|1.81}}

A seed for a random number generator used in Oolite 1.81 to generate system properties impractical to store in this file (e.g. the positions of each star on the background starfield)

For historical reasons, this is a string of 6 integers between 0 and 255, for example:
random_seed = "74 90 72 2 83 183";

=System population=
These properties are only used in Oolite 1.79 or later.

==Populator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|populate the system]]

Example:
"populator" = "systemWillPopulate";

==Repopulator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|repopulate the system]]

Example:
"repopulator" = "systemWillRepopulate";

=Properties of the Planet=

Most of these properties are ignored if a planet texture is set.

Note that the available planet texture generator properties changed in places between Oolite 1.77 and Oolite 1.80

==Air Color==
A colour specifier determining the color of the planet's sky, as well as the atmosphere scatter color.

Example:
"air_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Air Color Mix Ratio==
{{oolite-prop-added|1.89}}

The amount of air color that be mixed in the overall atmosphere color. A number from 0.0 to 1.0 (default 0.5).

Example:
"air_color_mix_ratio" = "0.0..1.0";

==Atmosphere Rotational Velocity==

Sets how fast the atmosphere is rotating. (A random value between 0.0 to 0.03 is the default).

Example:
"atmosphere_rotational_velocity" = "0.1";

==Cloud Alpha==
{{oolite-prop-added|1.77}}

The transparency level of the cloud layer, relative to the standard transparency. 1.0 is the default. Texture packs which include clouds on the planetary texture may wish to reduce this.

Example:
"cloud_alpha" = "0.2";

==Has Atmosphere==
{{oolite-prop-added|1.81}}

This boolean property is used for the main planet only. If it is unset or true, the main planet has an atmosphere, as is always the case in 1.80 and before. If it is set to be false, then the planet will not have an atmosphere.

Example:
"has_atmosphere" = 0;

This has no effect on secondary planets - their atmosphere is determined by whether addition uses <code>addPlanet</code> or <code>addMoon</code>.

[[File:AtmDensityExample.png|thumb|320px|right|Atmosphere Density examples: Stranger's ''FPO Lave'' in four increasing atmosphere densities: 0.2, 0.5, 0.75 and 1.0. Every other parameter in the planet definition is the same in all pictures.]]
== Air Density ==
{{oolite-prop-added|1.91}}

A number clamped in range from 0.0 to 1.0 describing the density of the planet's atmosphere. All planets in the core use 0.75 as default.

Example:
"air_density" = "0.0..1.0";

==Illumination Color==
{{oolite-prop-added|1.91}}

A colour specifier determining the colour of the planet's illumination such as cities light. Illumination is inserted as a grayscale map in the alpha channel of the planet's diffuse texture. You can specify this key even if no illumination map is defined, but it won't have any effect - without an illumination map the dark side of the planet remains dark in all cases.

Example:
"illumination_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Land Color==

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Percent Cloud==
The percentage of the planet's atmosphere occupied by clouds.

Example:
"percent_cloud" = "0..100";

Note that with a low cloud_alpha setting not all of the clouds defined here may actually be visible

==Percent Ice==
The percentage of the planet occupied by the polar ice caps. Oolite 1.81 or later.

Example:
"percent_ice" = "0..100";

==Percent Land==
The percentage of the planet occupied by land.

Example:
"percent_land" = "0..100";

==Planet Distance==
{{oolite-prop-added|1.81}}

The distance from the centre of the planet to the witchpoint. Only used for the system main planet - secondary planets are positioned separately.

Example:
"planet_distance" = "410000";

The main planet is always positioned on the z-axis.

==Planet Distance Multiplier==
{{oolite-prop-added|1.81}}

Multiplies the distance from the centre of the main planet to the witchpoint.

Example:
"planet_distance_multiplier" = "1.5";

==Planet Name==
{{oolite-prop-added|1.79}}

The planet's name. For the main planet, this defaults to being the same as the system name - the property is mainly intended for secondary planets.

Example
"planet_name" = "Earth";

==Polar Land Color==
{{oolite-prop-added|1.81}}

Sets the land colour in polar regions.

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Polar Sea Color==
{{oolite-prop-added|1.81}}

Sets the sea colour in polar regions.

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Radius==
An integer between 3000 and 7000 indicating the radius of the main planet. On the F7 screen, this is measured in kilometres. The radius in game is 1/100th of this.

Example:
"radius" = "5500";

==Rotational Velocity==
A number describing the rotational velocity of the planet in radians per second. Overrides rotation_speed if both are set.

Example:
"rotational_velocity" = 0.0015;

==Rotation Speed==
A number describing the rotational velocity of the planet in radians per second. Unlike rotational_velocity, this is affected by rotation_speed_factor.

Example:
"rotation_speed" = 0.0015;

==Rotation Speed Factor==
The rotational speed of all planets whose rotational speed was set by rotation_speed and not by rotational_velocity will be multiplied by this number.

Example:
"rotation_speed_factor" = 1.0;

(Intended more for the universal section as a "personal taste" option than for individual planets)

==Sea Color==

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Terminator Threshold Vector==
{{oolite-prop-added|1.89}}

This property gives control over the color of the planet's terminator. The way the property works is not entirely straightforward, so see [http://aegidian.org/bb/viewtopic.php?p=271058#p271058 this post on BB] for more information.

Example:
"terminator_threshold_vector" = "0.0..1.0 0.0..1.0 0.0..1.0";
By default the terminator vector is "0.105 0.18 0.28" - which results in a reddish orange colour.

==Texture==
The replacement texture to be used by a system's main planet.<br>

For textures you can use lat-long maps (twice as wide as high) with a special elongation at the poles or cube maps. Other maps also will be wraped around planets but give always distortions.<br>
Since Oolite 1.74 you can also use cube maps for planets. Cube maps are 6 times higher as wide and will be recognised automatic by Oolite, based on its dimensions. Cube maps are the preferred method because lat-long give some distortion and have the poles improperly placed in Oolites implementation. See also [[Planettool]] for conversion from lat-long into cube maps.

From Oolite 1.89 onwards, illumination mapping on custom planets is supported. The illumination map goes in the diffuse map's alpha channel. Low alpha values translate to high illumination. This allows for effects like city lights on a planet's dark side.

Example:
"texture" = "newPlanetTexture.png";
;N.B.
The illumination mapping feature is disabled by setting ''Graphics Detail: Shaders Enabled'' or lower in the game setting menu. ''Enabled'' at ''Graphics Detail: Extra Detail''.

==Texture HSB Color==
This changes the overall hue of the replacement texture.

Example:
"texture_hsb_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Texture NormSpec==
{{oolite-prop-added|1.89}}

The external texture that will be used as a normal and specular map for the given planet. Colorspace should be linear, with the normal map in the r,g and b and the specular map in the a channel. The texture can be of either equirectangular or cubemap formats. This feature is available at the Extra Detail setting only. To set:
"texture_normspec" = "planetNormalAndSpecularMap.png";

=Properties of the Sky=

==Ambient Level==

Sets how much ambient light (shed by stars and nebulae) illuminates the dark side of objects like planets and ships. Values should typically be between 0.0 and 1.0 (1.0 is the default) but can be higher for a flat lit, cartoon-like effect.

Example:
"ambient_level" = "0.0";

==Nebula Count Multiplier==
This is used for defining the number of nebulas. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"nebula_count_multiplier" = "1.5";

==Sky Blur Alpha==
Default 0.1

Example:
"sky_blur_alpha" = "0.0 .. 1.0";

==Sky Blur Cluster Chance==
This is used for creating nebulae (typically 0.80)

Example:
"sky_blur_cluster_chance" = "0.85";

==Sky Blur Scale==
Default 10. Larger numbers generate bigger nebula, but slow down the game considerable on slower machines.

Example:
"sky_blur_scale" = "0.0 .. 128.0 or more";

==Sky N Blurs==
This is used for defining the number of nebulas (typical is 80, maximum is 1280). This key is multiplied by a "nebula_count_multiplier" definition in Oolite 1.81 or later.

Example:
"sky_n_blurs" = "800";

==Sky N Stars==
This is used for defining the number of stars (typical = 600, maximum in 1.76 or earlier is 4800). This key is multiplied by a "star_count_multiplier" definition in Oolite 1.81 or later. In reduced detail mode, this number will be capped to 2400.

Example:
"sky_n_stars" = "1200";

==Sky and Nebula RGB Colors==

These are rgb values (from 0.0 to 1.0) for the two colours between which the colour of the stars (and nebulaesque blurs) vary, ordered r1 g1 b1 r2 g2 b2 where (r1 g1 b1) defines the first colour and (r2 g2 b2) the second.<br>
(Default values are "0.75 0.8 1.0 1.0 0.85 0.6")

Example:
"sky_rgb_colors" = "0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0";

Alternatively, two [[Materials in Oolite#Colour specifiers|colour specifiers]] may be used:
"sky_color_1" = "redColor";
"sky_color_2" =
{
"hue" = "60";
"brightness" = "0.8";
}

"nebula_color_1" = "greenColor";
"nebula_color_2" = "blueColor";

==Star Count Multiplier==
This is used for defining the number of stars. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"star_count_multiplier" = "0.5";

=Properties of the Station=

==Market==
The market to be used in this system as the default market. It points to a key in commodities.plist

Example:
"market" = "rockhermit";
Will use the rockhermit market as default for for all stations in the system. When no market is defined a key in commodities.plist is used that matches the role of the main station. Than that is not defined, the default market is used in this system.

In 1.81 and later, this is replaced by market_script

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

A Javascript file used to load a [[Oolite Market Scripts|market script]] for global system price and quantity modifications.

"market_script" = "myoxp_newsystemmarket.js";

==Station==
The type of station orbiting the main planet.

Example:
"station" = "coriolis..dodec..special";

==Station Roll==
The speed at which the station rotates (as with all rotational velocities this is in radians per second) and affects all rotating stations in a system. For a specific station you can use the key [[Shipdata.plist#station_roll | station_roll]] in shipdata.plist.

Example:
"station_roll" = "0.5";

==Station Vector==
The direction of the main station from the main planet

Example:
"station_vector" = "-0.717 -0.668 0.201";

==Stations Require Docking Clearance==

Specifies if a player has to explicit ask docking permission. See also [[Oolite_Docking_Clearance_Protocol_%28v1.72_or_later%29|Oolite Docking Clearance]]

=Properties of the Sun=
;N.B.
The corona effect, modified by the first three properties mentioned below, is disabled by setting ''Reduced Detail:On'' in the game setting menu. ''Enabled'' by default (''Reduced Detail:Off'').

==Corona Flare==

Sets the overall size of the corona in proportion to its sun. (See note above.)

A number from 0.0 (invisibly small) to 1.0 (huge)

Example:
"corona_flare" = "0.075";

==Corona Hues==

Specifies whether the corona should have visible bands of colours within the corona. (See note above.)

A number from 0.0 (monochromatic) to 1.0 (vivid alternating colours).

Example:
"corona_hues" = "0.6";

==Corona Shimmer==

Specifies how quickly the corona colours change. (See note above.)

A number from 0.0 (very slow) to 1.0 (very fast).

Example:
"corona_shimmer" = "0.4";

==Sun Color==

Sets the colour of a system's sun.

Can be any [[Materials in Oolite#Colour specifiers|colour specifier]] or [[Materials in Oolite#Named colours|named colour]]. The specified colour is blended with 50% white so it will never be a saturated colour. Dark colours will be brightened by this blending.

Example:
"sun_color" = "blueColor";

==Sun Distance==
{{oolite-prop-added|1.81}}

Sets the distance between the sun and the main planet in metres.

Example:
"sun_distance" = 924122;

Ignored if sun_distance_modifier is set.

==Sun Distance Multiplier==
{{oolite-prop-added|1.81}}

Multiplies the distance between the sun and the main planet by this factor.

Example:
"sun_distance_multiplier" = 2;

Ignored if sun_distance_modifier is set.

==Sun Distance Modifier==

Sets the approximate distance between a system sun and its main planet. The standard distance is 20 planetary radii. Setting it much lower (10, or even less) will cause delays when generating systems, as Oolite compensates for possible collisions between the sun and other system objects.

Example:
"sun_distance_modifier" = "15.0";

In Oolite 1.81 or later, sun_distance_multiplier is more useful.

== Sun Gone Nova ==

Sets a nova sun in the system.

Example:
"sun_gone_nova" = "YES";

==Sun Name==

Stores the name of a system's sun. This is only implemented in Oolite from version 1.79 onwards, though was used by OXPs before then.

Example:
"sun_name" = "Alpha Centauri";

==Sun Radius==

Sets the radius of a system's sun. A number between 1000 and 1000000.

Example:
"sun_radius" = "100000";

==Sun Vector==
The direction of the sun from the main planet

Example:
"sun_vector" = "-0.717 -0.668 0.201";

=Hyperspace Travel=

In Oolite 1.81 and later these properties have been moved into [[global-settings.plist]]

==Galactic Hyperspace Behaviour==

The key galactic_hyperspace_behaviour controls where the player will arrive after a G.H. has been executed. There are three possible types of G.H. behavior and are as follows:

1) Oolite standard. This is what we have up to this moment. Executing a G.H. jump will poisition the player in the next galaxy, to the closest non-isolated system with regards to their current galaxy coordinates. So, for example, if you jump from coordinates (100, 50) in galaxy 1 you will arrive in galaxy 2 at the same coordinates, unless these coordinates refer to an unreachable system, in which case the arrival point will be adjusted by the engine to maybe something like (102, 51). This is set as default behavior. It is set by assigning the string BEHAVIOUR_STANDARD to the galactic_hyperspace_behaviour key.

2) All systems reachable. Same as above, only this time we do not check for arrival at an isolated system. Using this method, systems like Oresrati in G8, the lower left hand cluster of systems in G7, the two islands of isolated systems in G6 etc. are now possible arrival points. If you land there, you may not be able to exit again, depending on the tech levels of the systems you get to. Mission scripters may want to use this. This behaviour is set by assigning the string BEHAVIOUR_ALL_SYSTEMS_REACHABLE to galactic_hyperspace_behaviour key in planetinfo.plist.

3) Fixed coordinates arrival point. This will make Oolite simulate some older 8-bit versions, that were putting the player in the same fixed point every time a galactic jump was performed, but there is also good potential for scripting (see below). This is set by assigning the string BEHAVIOUR_FIXED_COORDINATES to the galactic_hyperspace_behaviour key.

==Galactic Hyperspace Fixed Coords==

If the fixed coordinates method is chosen, then the engine will look in planetinfo.plist for a key named galactic_hyperspace_fixed_coords, from which it will read the actual coordinates that will be used as the arrival point in the next galaxy. If none is found, then coordinates (96,96) will be used.

==Hyperspace Tunnel Color==

One or two colours can be set, using RGBA format, to over-ride the appearance of the hyperspace tunnel effect.
Example:

hyperspace_tunnel_color_1 = (1.0, 0.0, 0.0, 0.5);
hyperspace_tunnel_color_2 = (0.0, 0.0, 1.0, 0.25);



=Additional Planets=

Finally you can also define your own custom planets and moons:
"LavesPurpleMoon" =
{
...
}


To add them to the system, use JS methods <code>[[Oolite_JavaScript_Reference:_System#addPlanet|system.addPlanet]]</code> and <code>[[Oolite_JavaScript_Reference:_System#addPlanet|system.addMoon]]</code>. For the example above, the <code>planetInfoKey</code> will be <code>"LavesPurpleMoon"</code>.

==Position==
Position of the planet in space. The first parameter is 3-character code of the coordinate system, other three is x, y and z components of position vector.
"position" = "pwm 0 -50000 0";

You can omit the coordinate system parameter, then the absolute coordinate system will be used:
"position" = "0 -50000 0";

See [[Oolite coordinate systems]] for more info about it.

==Orientation==
Orientation of the planet in space (seems not to be working correct).

Example:
"orientation" = "0.0 1.0 0.0 0.0";

==Other keys==

You can use other keys from the [[#Properties_of_the_Planet| Properties of the Planet]] section for your planets and moons.

Here are some of the keys you may want to use:
* "radius": Radius of the planet in km. e.g. a value of 500 is drawn with a radius of 5000 meters but in player dialogues this value is presented as 500 km.
* "rotational_velocity": Rotation of the planet in rotations per second.
* "texture": The name of the texture file that is used to wrap around the surface.
* "seed": Seed value used to create the planet's surface features. If no seed is defined it uses the same seed as the main planet, and will create a copy of it.

= Links =
*[[Random number generator]] - originally used for creating planet descriptions
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=3860 seed = "1 2 3 4 5 6";]: Psuedo-random number generation & planet descriptions (2007)
*[http://aegidian.org/bb/viewtopic.php?f=4&t=3808 position = "x y z" in planetinfo.plist] (2007)
*Submersible's [https://www.youtube.com/user/submersibletoaster YouTube videos] of planet textures (2012)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=5044 Question: How to add custom planet descriptions] (2008)
*[http://aegidian.org/bb/viewtopic.php?p=217053#p217053 Tweaking your skies] (Tricky, 2014)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20959 Empty system] Removing the stations (and presumably inhabitants) from a system (2021)

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

Oolite JavaScript Reference: World script event handlers

2023-06-21T16:57:40Z

Alnivel: /* shipWillEnterWitchspace */ Added missing possible value for the "cause" parameter

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

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

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

World scripts are always active.

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

=== Game State ===

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

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

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

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

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

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

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

The <code>playerWillSaveGame</code> handler is called whenever the player saves a game. The transferred message is one of the following strings: <code>"STANDARD_SAVE"</code>, <code>"AUTO_SAVE"</code> or <code>"QUICK_SAVE"</code>.

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

Using this event is useful for storing temporary variables in <code>[[Oolite_JavaScript_Reference:_Global#missionVariables|missionVariables]]</code>, just before the game gets saved. <code>missionVariables</code> are slow in use compared to normal JS variables, therefore their use should be minimised for efficient code. The main benefit of using <code>missionVariables</code> is that they are saved in a saved game. See also [[Mission variable]].

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

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

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

Note that from Oolite 1.79 onwards the player is in the main station while this handler runs but may be moved to another station soon after.

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

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

=== Docking ===

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

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

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

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

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

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

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

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

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

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

The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect. The handler's argument is the station which launched the ship.

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

At this moment <code>ship.dockedStation == null</code>, <code>ship.docked == false</code>, <code>ship.status == "STATUS_IN_FLIGHT"</code>.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Witchspace Jumps ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Note:''' If the <code>cause</code> is <code>"carried"</code> the <code>destination</code> parameter is <code>undefined</code>. This behaviour is presumably a bug.

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

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

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

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

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

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

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

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

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

shipWillEnterWitchspace (world event)<br>
playerWillEnterWitchspace (NPC ship event)<br>
playerEnteredNewGalaxy (world event)<br>
shipWillExitWitchspace (world event)<br>
shipExitedWitchspace (world event)<br>

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

*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18392 Order of JS events when galactic jumping] (2016)

=== Enter/Exit Aegis ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Combat ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Equipment and Cargo ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

this.playerWillBuyNewShip = function(dataKey, shipyard, price, tradeIn)
{
// Your code here
}

<code>dataKey</code> is the shipdata.plist <code>dataKey</code> for the ship being purchased.

<code>shipyard</code> is a dictionary object containing details about the ship being purchased, with information similar to the following:
{
short_description: "Python: Plus Galactic Hyperdrive. Extra Energy Unit. Docking Computers. E.C.M. System. Forward weapon upgraded to military laser. Price 215 000 ₢.",
shipdata_key: "python-player",
id: "675b6b-c60a74",
price: 215000,
ship: {
...''[[shipdata.plist]]'' details of ship...
},
personality: 9807,
extras: ["EQ_GAL_DRIVE", "EQ_FUEL_SCOOPS", "EQ_ENERGY_UNIT", "EQ_FUEL_INJECTION", "EQ_DOCK_COMP", "EQ_ECM"]
}

<code>price</code> is the amount being paid the for ship.

<code>tradeIn</code> is the trade in value of the current ship.

'''See also:''' <code>[[#playerBoughtNewShip|playerBoughtNewShip]]</code>

==== <code>playerWillReplaceShip</code> ====
{{Oolite-method-added|1.89}}

The <code>playerWillReplaceShip</code> handler is called just before a ship is replaced using [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip()</code>]]. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerWillReplaceShip = function(dataKey)
{
// Your code here
}

<code>dataKey</code> is the shipdata.plist <code>dataKey</code> for the ship being purchased.

'''See also:''' <code>[[#playerReplacedShip|playerReplacedShip]]</code>

=== Other ===

==== <code>chartHightlightModeChanged</code> ====
{{oolite-method-added|1.87}}

The <code>chartHighlightModeChanged</code> handler is called whenever the highlight mode of the galactic chart is changed either manually (from player input) or programmatically (by setting the mode with <code>[[Oolite JavaScript Reference: PlayerShip#chartHighlightMode|player.ship.chartHightlightMode]]</code>). The "newMode" parameter will be one of the following:
* <code>"OOLRC_MODE_SUNCOLOR"</code>
* <code>"OOLRC_MODE_ECONOMY"</code>
* <code>"OOLRC_MODE_GOVERNMENT"</code>
* <code>"OOLRC_MODE_TECHLEVEL"</code>

this.chartHightlightModeChanged = function(newMode)
{
// Your code here
}

==== <code>compassTargetChanged</code> ====

The <code>compassTargetChanged</code> handler is called when a new target is selected. Mode can be any of the following:

COMPASS_MODE_BASIC
COMPASS_MODE_PLANET
COMPASS_MODE_STATION
COMPASS_MODE_SUN
COMPASS_MODE_TARGET
COMPASS_MODE_BEACONS

script example

this.compassTargetChanged = function(whom, mode)
{
log(' Now targeting ' + whom);
// Your code here
}

==== <code>dayChanged</code> ====
{{oolite-method-added|1.77}}

The <code>dayChanged</code> handler is called each time a new day starts. At very low frame rates while the clock is updating, it is possible for this handler to be called twice in the same frame. Therefore, clock.days will not be correct for one of the calls. Use the day number (newday parameter) passed to the handler instead.

this.dayChanged = function(newday)
{
// Your code here
}

==== <code>escapePodSequenceOver</code> ====

The <code>escapePodSequenceOver</code> handler is called at the end of the escape pod sequence, after the <code>shipLaunchedEscapePod</code> event and just prior to the <code>shipWillDockWithStation</code> and <code>shipDockedWithStation</code> events.

Use this handler if you need to override the destination for the escape pod with [[Oolite_JavaScript_Reference:_Player#setEscapePodDestination|<code>player.setEscapePodDestination()</code>]].

this.escapePodSequenceOver = function()
{
// Your code here
}

==== <code>guiScreenChanged</code> ====

The <code>guiScreenChanged</code> handler is called when the <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> changes. The ''from'' parameter is the screen it is leaving and ''to'' is the screen initially being switched to. Note that the screen can have changed again in the meantime by the action of other oxps. Therefore, it is generally better to test the global <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> to see which page is really on display instead of using the ''to'' parameter. (world script only)

This handler will only fire when switched to/from any of the following:

1.76: <code>"GUI_SCREEN_MAIN"</code>, <code>"GUI_SCREEN_STATUS"</code>(F5), <code>"GUI_SCREEN_MANIFEST"</code>(F5F5), <code>"GUI_SCREEN_SYSTEM_DATA"</code>(F7), <code>"GUI_SCREEN_OPTIONS"</code>, <code>"GUI_SCREEN_EQUIP_SHIP"</code>(F3), <code>"GUI_SCREEN_SHIPYARD"</code>(F3F3), <code>"GUI_SCREEN_SHORT_RANGE_CHART"</code>(F6), <code>"GUI_SCREEN_LONG_RANGE_CHART"</code>(F6F6), <code>"GUI_SCREEN_MARKET"</code>(F8), <code>"GUI_SCREEN_CONTRACTS"</code>, <code>"GUI_SCREEN_REPORT"</code>

1.77: adds <code>"GUI_SCREEN_INTERFACES"</code>(F4) and removes <code>"GUI_SCREEN_CONTRACTS"</code>

1.81: adds <code>"GUI_SCREEN_MARKETINFO"</code>(F8F8)

this.guiScreenChanged = function(to, from)
{
// Your code here
}

==== <code>guiScreenWillChange</code> ====

The <code>guiScreenWillChange</code> handler is called when the <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> is about to change. On these screens, a script could change the content of the page to be displayed. (world script only)

This handler will only fire when switching to/from any of the following:

<code>"GUI_SCREEN_EQUIP_SHIP"</code>(F3), <code>"GUI_SCREEN_MANIFEST"</code>(F5F5), <code>"GUI_SCREEN_MARKET"</code>(F8), <code>"GUI_SCREEN_SHIPYARD"</code>(F3F3), <code>"GUI_SCREEN_SYSTEM_DATA"</code>(F7)

1.77: adds <code>"GUI_SCREEN_INTERFACES"</code>(F4), <code>"GUI_SCREEN_STATUS"</code>(F5)

1.81: adds <code>"GUI_SCREEN_MARKETINFO"</code>(F8F8)

this.guiScreenWillChange = function(to, from)
{
// Your code here
}

==== <code>infoSystemChanged</code> ====
{{oolite-method-added|1.83}}

The <code>infoSystemChanged</code> handler is called when the system displayed in F7 is changed, e.g. by moving the small blue cursor along the planned route in the chart.

this.infoSystemChanged = function(to, from)
{
// Your code here
}

==== <code>infoSystemWillChange</code> ====
{{oolite-method-added|1.85}}

The <code>infoSystemWChange</code> handler is called just before the system displayed in F7 is updated, e.g. by moving the small blue cursor along the planned route in the chart.

this.infoSystemWillChange = function(to, from)
{
// Your code here
}

==== <code>mfdKeyChanged</code> ====
{{oolite-method-added|1.85}}

The <code>mfdKeyChanged</code> handler is called whenever the player changes the content of an MFD slot. The <code>activeMFD</code> parameter identifies which MFD slot is being changed, and the <code>mfdKey</code> specifies the key code now in use in this slot.

this.mfdKeyChanged = function(activeMFD : integer, mfdKey : string)
{
// Your code here
}

'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#setMultiFunctionDisplay|PlayerShip.setMultiFunctionDisplay()]]</code>

==== <code>missionChoiceWasReset</code> ====

The <code>missionChoiceWasReset</code> handler is called when the mission choice is set to <code>null</code> via script (either using the legacy script method resetMissionChice or using <code>mission.runScreen ({choices: null})</code> in javascript)

this.missionChoiceWasReset= function()
{
// Your code here
}

==== <code>missionScreenEnded</code> ====

The <code>missionScreenEnded</code> handler is called when a mission screen ends. Note that another script may have put up a new mission screen in the meantime. (world script only)

this.missionScreenEnded = function()
{
// Your code here
}

==== <code>missionScreenOpportunity</code> ====

The <code>missionScreenOpportunity</code> handler is called if there are no mission/report screens active and the player's ship is docked. It gets fired at game startup, upon docking and after an arrival report or previous mission screen has ended. (world script only)

this.missionScreenOpportunity= function()
{
// Your code here
}

This handler works a bit different from other handlers. It fires for every installed OXP/OXZ until one creates a mission screen during this handler, and then it stops. When the mission screen ends and there is no callback function that creates a new mission screen, the <code>missionScreenOpportunity</code> is sent again to all installed OXPs/OXZs starting with the one that created the last mission screen. All this means is that when this handler fires, it is safe to show a mission screen and no further tests are needed.

==== <code>reportScreenEnded</code> ====

The <code>reportScreenEnded</code> handler is called when the last arrival-report screen ends. This is a screen that should not be written by a missionscreen. The code should wait until this eventhandler fires. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

this.reportScreenEnded = function()
{
// Your code here
}

==== <code>selectedMFDChanged</code> ====
{{oolite-method-added|1.85}}

The <code>selectedMFDChanged</code> handler is send whenever the player selects a new MFD slot (normally using the default keypress ";"). The <code>activeMFD</code> paramater is the index of the MFD which is now active.

this.selectedMFDChanged = function(activeMFD : integer)
{
// Your code here
}

==== <code>shipCollided</code> ====

The <code>shipCollided</code> handler is send after a collision with otherShip.

this.shipCollided = function(otherShip)
{
// Your code here
}

==== <code>shipSpawned</code> ====

The <code>shipSpawned</code> handler is called after an NPC ship has been added to the system. After a witchspace jump it means that first all ships are added to the system, then all the relevant shipSpawned events are triggered.<br>
This handler for the worldScript is new since Oolite 1.74. After the event is sent to the shipScript, it is now also send to the worldScript with the added entity as argument.

this.shipSpawned = function(ship)
{
// Your code here
}

==== <code>shipLaunchedEscapePod</code> ====

The <code>shipLaunchedEscapePod</code> handler is called when the player bails out. This will be followed by the <code>escapePodSequenceOver</code> event, and then a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds.

this.shipLaunchedEscapePod = function(escapepod)
{
// Your code here
}

==== <code>systemInformationChanged</code> ====
{{oolite-method-added|1.79}}

The <code>systemInformationChanged</code> handler is called when system information is modified. It is passed the galaxy and system ID which were changed, and the key and new value in the SystemInfo object.

To avoid problems with recursion, attempting to change the value of any system information property from within this handler will fail and log an error. Also note that changes which take place while Oolite is not running (from OXP planetinfo.plist files) will not cause this handler to be called when the game is reloaded.

this.systemInformationChanged = function(galaxy,system,key,newValue)
{
// Your code here
}

==== <code>viewDirectionChanged</code> ====

The <code>viewDirectionChanged</code> handler is called when the player view changes, with a string to indicate which view the player is facing. Amongst its possible values are "VIEW_FORWARD", "VIEW_AFT", "VIEW_PORT", "VIEW_STARBOARD",
"VIEW_CUSTOM",
"VIEW_GUI_DISPLAY".

this.viewDirectionChanged = function(viewString)
{
if (viewString == "VIEW_PORT")
{
// Your code here
}
}

=== System population ===

In Oolite 1.79 and later, functions are called to populate and repopulate the system. These functions do not have fixed names, as they depend on the system, but otherwise act like normal worldscript functions. [[Oolite System Populator|The populator page]] has more documentation on these functions.

=== Defunct ===

==== <code>equipmentDestroyed</code> ====
''Handler no longer exists in current stable version 1.80''

The <code>equipmentDestroyed</code> handler is called when equipment gets destroyed completely beyond repair. (in strict mode, 1.77 or earlier only) (world script only)

this.equipmentDestroyed = function(equipment)
{
// Your code here
}

==== <code>tickle</code> (removed in 1.77) ====

The <code>tickle</code> handler is called periodically-ish, whenever the old [[property list|plist]] scripts are updated. <code>tickle()</code> is deprecated. In new code, use appropriate event handlers or [[Oolite JavaScript Reference: Timer|timers]] instead.

=== Missing Events ===

All the initially planned events have been implemented in 1.74.

If there are other events you would like to be able to respond to, please write a request [http://www.aegidian.org/bb/viewtopic.php?t=3296 on the forum].

'''See also:''' [[Oolite JavaScript Reference: Ship script event handlers|ship script event handlers]]

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: World script event handlers

2023-06-21T15:41:47Z

Alnivel: /* playerWillSaveGame */ Corrected the possible values of the parameter, formating

This page provides a list of event handlers which can be implemented inside world scripts [[Scripting Oolite with JavaScript|JavaScript scripts for Oolite]]. Additionally, ship script handlers called on the player's ship will cause an equivalent world script event.

Most event handlers can be used both in world scripts and in ship scripts. Generally speaking, handlers starting with "ship" can be used for both scripts and those starting with "player" are meant only for the player (= can only be used in a world script). Exceptions on this rule are mentioned with the individual handlers below.

World scripts can be either found inside Config\script.js, or be distinctly named .js files inside the Scripts directory - in the latter case, the worldScript.plist will list the active world scripts.

World scripts are always active.

The list of event handlers will change from version to version (usually additions of extra handlers). For this reason, any variables or functions you create as <code>this.variable</code> should have a name beginning with '_' or '$' - e.g. <code>this._variable</code> or <code>this.$variable</code> - to avoid potential conflicts with future event handlers (which will never start with '_' or '$').

=== Game State ===

==== <code>gamePaused</code> ====
{{oolite-method-added|1.81}}

This event is called when the game is paused. This is mainly useful for pausing sound playback which should not continue while the game is paused.

this.gamePaused = function()
{
// Your code here
}

==== <code>gameResumed</code> ====
{{oolite-method-added|1.81}}

This event is called when the game is resumed from pause. This is mainly useful for resuming sound playback paused in a <code>gamePaused</code> handler.

this.gameResumed = function()
{
// Your code here
}

==== <code>playerWillSaveGame</code> ====

The <code>playerWillSaveGame</code> handler is called whenever the player saves a game. The transferred message is one of the following strings: <code>"STANDARD_SAVE"</code>, <code>"AUTO_SAVE"</code> or <code>"QUICK_SAVE"</code>.

this.playerWillSaveGame = function(message)
{
// Your code here
}

Using this event is useful for storing temporary variables in <code>[[Oolite_JavaScript_Reference:_Global#missionVariables|missionVariables]]</code>, just before the game gets saved. <code>missionVariables</code> are slow in use compared to normal JS variables, therefore their use should be minimised for efficient code. The main benefit of using <code>missionVariables</code> is that they are saved in a saved game. See also [[Mission variable]].

==== <code>startUp</code> ====

The <code>startUp</code> handler is called after all OXPs have been loaded. This also means that it is called every time the player loads a game, begins a new game or presses space after dying. It can be used to do one-off initialisation such as copying mission variables into <code>this.*</code> properties for efficiency or setting up data arrays to be used by the script in other handlers. (world script only)

this.startUp = function()
{
// Your code here
}

Note that from Oolite 1.79 onwards the player is in the main station while this handler runs but may be moved to another station soon after.

==== <code>startUpComplete</code> ====
{{oolite-method-added|1.79}}

The <code>startUpComplete</code> handler is run at game startup after the initial population of the system has been complete, and after the player has been moved to the station recorded in their save game. The order of world events at game start is therefore:
* <code>startUp</code>
* <code>systemWillPopulate</code> (or an alternative handler specified by the system info)
* <code>startUpComplete</code>

=== Docking ===

==== <code>shipWillDockWithStation</code> ====

The <code>shipWillDockWithStation</code> handler is called at the beginning of the docking tunnel effect.

this.shipWillDockWithStation = function(station)
{
// Your code here
}
At this moment <code>ship.dockedStation == null</code>, <code>ship.docked == true</code>, <code>ship.status == "STATUS_DOCKING"</code>

==== <code>shipDockedWithStation</code> ====

The <code>shipDockedWithStation</code> handler is called at the end of the docking tunnel effect.

this.shipDockedWithStation = function(station)
{
// Your code here
}
At this moment <code>ship.dockedStation == station</code>, <code>ship.docked == true</code>, <code>ship.status == "STATUS_DOCKED"</code> and <code>guiScreen</code> is either <code>"GUI_SCREEN_STATUS"</code> or <code>"GUI_SCREEN_REPORT"</code>. However, any identical handler from an other oxp could have changed those values. Never count on it but double check when important.

==== <code>shipWillLaunchFromStation</code> ====

The <code>shipWillLaunchFromStation</code> handler is called at the beginning of the launch tunnel effect.

this.shipWillLaunchFromStation = function(station)
{
// Your code here
}
At this moment <code>ship.dockedStation == station</code>, <code>ship.docked == false</code>, <code>ship.status == "STATUS_LAUNCHING"</code>.

==== <code>shipLaunchedFromStation</code> ====

The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect. The handler's argument is the station which launched the ship.

this.shipLaunchedFromStation = function(stationLaunchedFrom)
{
// Your code here
}

At this moment <code>ship.dockedStation == null</code>, <code>ship.docked == false</code>, <code>ship.status == "STATUS_IN_FLIGHT"</code>.

==== <code>playerStartedAutoPilot</code> ====

The <code>playerStartedAutoPilot</code> handler is called when the player starts autopilot docking. It is not called for the instantaneous dock command. The handler is called with an argument containing the station entity that is the docking target.

this.playerStartedAutoPilot = function(stationForDocking)
{
// Your code here
}

==== <code>playerCancelledAutoPilot</code> ====

The <code>playerCancelledAutoPilot</code> handler is called when the player cancels autopilot docking.

this.playerCancelledAutoPilot = function()
{
// Your code here
}

==== <code>playerDockingClearanceCancelled</code> ====
{{oolite-method-added|1.85}}

The <code>playerDockingClearanceCancelled</code> handler is called when the player withdraws their request to dock at a station.

this.playerDockingClearanceCancelled = function()
{
// Your code here
}

==== <code>playerDockingClearanceExpired</code> ====
{{oolite-method-added|1.83}}

The <code>playerDockingClearanceExpired</code> handler is called when the player exceeds the two minute window without requesting an extension

this.playerDockingClearanceExpired = function()
{
// Your code here
}

==== <code>playerDockingClearanceGranted</code> ====
{{oolite-method-added|1.85}}

The <code>playerDockingClearanceGranted</code> handler is called when the player is given permission to dock at a station. If the player is given immediate clearance to dock, this event will be called immediately after the <code>playerRequestedDockingClearance</code> event. If, however, the station is unable to give immediate clearance, then there will be some delay between the request to dock and permission being granted. This event will be called when the station actually gives docking clearance.

this.playerDockingClearanceGranted = function()
{
// Your code here
}

==== <code>playerDockingRefused</code> ====

The <code>playerDockingRefused</code> handler is called when a station refuses to provide autopilot docking instructions.

this.playerDockingRefused = function()
{
// Your code here
}

==== <code>playerRequestedDockingClearance</code> ====

The <code>playerRequestedDockingClearance</code> handler is called when a station answers on a docking request of the player by targeting the station and pressing L (shift-l).

this.playerRequestedDockingClearance = function(message)
{
// Your code here
}

Message is a string and can take the values: "DOCKING_CLEARANCE_GRANTED", "DOCKING_CLEARANCE_DENIED_TRAFFIC_OUTBOUND", "DOCKING_CLEARANCE_DENIED_TRAFFIC_INBOUND", "DOCKING_CLEARANCE_DENIED_SHIP_FUGITIVE", "DOCKING_CLEARANCE_NOT_REQUIRED", "DOCKING_CLEARANCE_EXTENDED" or "DOCKING_CLEARANCE_CANCELLED".

==== <code>playerRescuedEscapePod</code> ====
{{oolite-method-added|1.81}}

The <code>playerRescuedEscapePod</code> handler is called when the player rescues an escape pod which does not have scripted content (all consequences of scripted content escape pods are assumed to be dealt with by the specified script instead). It has three parameters:
# the rescue fee, in decicredits
# the fee reason, which can be "insurance", "bounty" or "slave" (in the latter case, the fee will always be zero)
# a dictionary like those in the <code>ship.crew</code> property describing the pod occupant

this.playerRescuedEscapePod = function(fee, reason, occupant)
{
// Your code here
}

This method is called after the escape pod has been processed, but slightly before the arrival report screen giving the results of the processing is displayed to the player.

==== <code>playerCompletedContract</code> ====
{{oolite-method-added|1.81}}

The <code>playerCompletedContract</code> handler is called when a passenger, parcel or cargo contract ends, either successfully or by defaulting on it. It is not called when all contracts are cancelled on a galactic jump. It has four parameters:
# The type of contract, which can be "cargo", "parcel" or "passenger"
# The result of the contract, which can be "success", "late", "failed", or for cargo contracts only "short"
# The fee paid for the contract in decicredits
# The contract information dictionary
Note that the fee actually paid for the contract will often ''not'' match the originally agreed fee in the contract information dictionary, as penalties for late delivery or bonuses for good service are included in the fee parameter.

this.playerCompletedContract = function(type, result, fee, contract)
{
// Your code here
}

This method is called after the contract has been processed, but slightly before the arrival report screen giving the results of the processing is displayed to the player.

==== <code>playerEnteredContract</code> ====
{{oolite-method-added|1.81}}

The <code>playerEnteredContract</code> handler is called when a passenger, parcel or cargo contract starts, just after the items have been transferred to the player ship. It has two parameters:
# The type of contract, which can be "cargo", "parcel" or "passenger"
# The contract information dictionary

this.playerEnteredContract = function(type, contract)
{
// Your code here
}

=== Witchspace Jumps ===

==== <code>playerStartedJumpCountdown</code> ====

The <code>playerStartedJumpCountdown</code> handler is called when the user starts a witchspace or galactic witchspace jump countdown. The <code>type</code> parameter is a string specifying which type of jump is occuring; currently, the possible values are “standard” and “galactic”. Other values may be added in future. The <code>seconds</code> parameter is a number specifying the number of seconds the countdown is running for.

this.playerStartedJumpCountdown = function(type, seconds)
{
// Your code here
}

==== <code>playerCancelledJumpCountdown</code> ====

The <code>playerCancelledJumpCountdown</code> handler is called when the user cancels a witchspace or galactic witchspace jump countdown.

this.playerCancelledJumpCountdown = function()
{
// Your code here
}

==== <code>playerJumpFailed</code> ====

The <code>playerJumpFailed</code> handler is called at the end of a witchspace or galactic witchspace countdown, if the jump is not possible. The <code>reason</code> parameter is a string specifying why the jump failed. The current values are:
* '''"insufficient fuel"''' - the ship no longer has enough fuel to make the jump (e.g. injector use or fuel leak).
* '''"blocked"''' - a heavy ship is near the player (specifically <code>object mass</code> / <code>object distance</code><sup>2</sup> >= 10.0, and <code>object distance</code> <= scanner range).
* '''"malfunction"''' - the jump malfunctioned in a way that leaves the player ship in the current system.
* '''"malfunction"''' - the Galactic Hyperdrive is damaged or removed during a galactic jump countdown.

Also theoretically possible but unlikely in current Oolite:
* '''"too far"''' - the jump destination is outside the 7LY range (but wasn't when the countdown started).
* '''"no target"''' - the jump destination is the current location (but wasn't when the countdown started).

this.playerJumpFailed = function(reason)
{
// Your code here
}

==== <code>shipWillEnterWitchspace</code> ====

The <code>shipWillEnterWitchspace</code> handler is called immediately before a witchspace jump, while the player is still in the starting system. The <code>cause</code> parameter is a string specifying what sort of jump is occuring; currently, the possible values are “standard jump”, “galactic jump” and “wormhole”. Other values may be added in future.

// 1.80 or earlier
this.shipWillEnterWitchspace = function(cause)
{
// Your code here
}

In 1.81 or later the handler gains a second parameter, describing the jump destination. For standard and wormhole jumps, this will be the system ID of the destination system. For galactic jumps, this will be the galaxy ID of the destination galaxy. (As [[Oolite JavaScript Reference: PlayerShip#galacticHyperspaceBehaviour|player.ship.galacticHyperspaceBehaviour]] may be changed during <code>shipWillEnterWitchspace</code>, it is not possible to predict in advance of a galactic jump being made what the resulting system ID in the destination galaxy will be)

// 1.81 or later
this.shipWillEnterWitchspace = function(cause, destination)
{
// Your code here
}

==== <code>shipWillExitWitchspace</code> ====

The <code>shipWillExitWitchspace</code> handler is called as a witchspace jump concludes. When it is called, the player is (from a program perspective) in the destination system, but the tunnel effect has not yet been shown. Use this event to set up elements which need to be present in-system after the player exits witchspace.

this.shipWillExitWitchspace = function()
{
// Your code here
}

==== <code>shipExitedWitchspace</code> ====

The <code>shipExitedWitchspace</code> handler is called after a witchspace jump has concluded and the tunnel effect has been shown.

this.shipExitedWitchspace = function()
{
// Your code here
}

==== <code>playerEnteredNewGalaxy</code> ====

The <code>playerEnteredNewGalaxy</code> handler is called just before shipWillExitWitchspace.

the sequence of events for a player jumping to a different galaxy is as follows:

shipWillEnterWitchspace (world event)<br>
playerWillEnterWitchspace (NPC ship event)<br>
playerEnteredNewGalaxy (world event)<br>
shipWillExitWitchspace (world event)<br>
shipExitedWitchspace (world event)<br>

this.playerEnteredNewGalaxy = function(galaxyNumber)
{
// Your code here
}

*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18392 Order of JS events when galactic jumping] (2016)

=== Enter/Exit Aegis ===

==== <code>shipEnteredStationAegis</code> ====

The <code>shipEnteredStationAegis</code> handler is called when the player enters the aegis of the main-station (2x scanner range from main-station). Other stations than the main-station don't give aegis messages.

this.shipEnteredStationAegis = function(station)
{
// Your code here
}

==== <code>shipExitedStationAegis</code> ====

The <code>shipExitedStationAegis</code> handler is called when the player leaves the aegis of the main-station (2x scanner range from main-station).

this.shipExitedStationAegis = function(station)
{
// Your code here
}

==== <code>shipEnteredPlanetaryVicinity</code> ====

The <code>shipEnteredPlanetaryVicinity</code> handler is called when the player enters the planet aegis (3x planet radius).

this.shipEnteredPlanetaryVicinity = function(planet)
{
// Your code here
}

==== <code>shipExitedPlanetaryVicinity</code> ====

The <code>shipExitedPlanetaryVicinity</code> handler is called when the player leaves the planet aegis (3x planet radius).

this.shipExitedPlanetaryVicinity = function(planet)
{
// Your code here
}

==== <code>shipApproachingPlanetSurface</code> ====

The <code>shipApproachingPlanetSurface</code> handler is called when the player is very close to the planet (crosses a border ± 500 meter above the surface).

this.shipApproachingPlanetSurface = function(planet)
{
// Your code here
}

==== <code>shipLeavingPlanetSurface</code> ====

The <code>shipLeavingPlanetSurface</code> handler is called when the player leaves the planet (crosses a border ± 500 meter above the surface).

this.shipLeavingPlanetSurface = function(planet)
{
// Your code here
}

=== Combat ===

==== <code>alertConditionChanged</code> ====

The <code>alertConditionChanged</code> handler is called when the player’s alert status (<code>[[Oolite JavaScript Reference: Player#alertCondition|player.alertCondition]]</code>) changes. Only the player and stations have an alert condition. (world script and station scripts)

this.alertConditionChanged = function(newCondition, oldCondition)
{
// Your code here
}

==== <code>playerTargetedMissile</code> ====

The <code>playerTargetedMissile</code> handler is called when the player targets the nearest missile by pressing "T" (shift-t).

this.playerTargetedMissile = function(missile)
{
// Your code here
}

==== <code>shipAttackedOther</code> ====

The <code>shipAttackedOther</code> handler is called when the player hits another with a laser shot. <code>other</code> is the identity of the ship being hit.

this.shipAttackedOther = function(other)
{
// Your code here
}

==== <code>shipAttackedWithMissile</code> ====

The <code>shipAttackedWithMissile</code> handler is called when a missile is fired. <code>missile</code> contains the missile entity and <code>whom</code> the identity of the ship that launched the missile.

this.shipAttackedWithMissile = function(missile, whom)
{
// Your code here
}

==== <code>shipBeingAttacked</code> ====

The <code>shipBeingAttacked</code> handler is called when a laser shot hits. <code>whom</code> the identity of the ship that attacked.

this.shipBeingAttacked = function(whom)
{
// Your code here
}

==== <code>shipBeingAttackedByCloaked</code> ====

The <code>shipBeingAttackedByCloaked</code> handler is called when a laser shot from a cloaked ship hits. Guess what, there is no parameter because he is cloaked!

this.shipBeingAttackedByCloaked = function()
{
// Your code here
}

==== <code>shipKilledOther</code> ====
{{oolite-method-added|1.75}}

The <code>shipKilledOther</code> handler is called when a ship kills an other ship. <code>whom</code> the identity of the ship that was killed. <code>damageType</code> is the type of damage.

this.shipKilledOther = function(whom : ship, damageType : string)
{
// Your code here
}

==== <code>shipReleasedEquipment</code> ====

The <code>shipReleasedEquipment</code> handler is called when a ship launches a mine (a pylon-mounted equipment item whose key ends with "_MINE"). <code>mine</code> contains the launched mine entity.

this.shipReleasedEquipment = function(mine)
{
// Your code here
}

==== <code>shipTargetDestroyed</code> ====

The <code>shipTargetDestroyed</code> handler is called when the target gets destroyed by the player. <code>target</code> contains the destroyed target entity. This command is always preceded by the <code>shipTargetLost</code> handler.

this.shipTargetDestroyed = function(target)
{
// Your code here
}

==== <code>shipDied</code> ====

The <code>shipDied</code> handler is called when the ship or player dies. Expect a <code>reset()</code> shortly when it is the player ship.

this.shipDied = function(whom, why)
{
// Your code here
}
'''whom''' contains the entity that caused the kill. '''why''' is the cause written as string and is one of: "removed", "hit a planet", "energy damage", "scrape damage", "heat damage", "cascade weapon".<br>
("cascade weapon" is new in 1.74 and "removed" / "energy damage" were accidentally switched in 1.73)

==== <code>shipFiredMissile</code> ====

The <code>shipFiredMissile</code> handler is called when a missile is fired. <code>missile</code> contains the missile entity and <code>target</code> the identity of the target. The handler is send to the ship that launched the missile.

this.shipFiredMissile = function(missile, target)
{
// Your code here
}

==== <code>shipTargetLost</code> ====

The <code>shipTargetLost</code> handler is called when the target gets lost. <code>target</code> contains the lost target entity.

this.shipTargetLost = function(target)
{
// Your code here
}

==== <code>shipTargetCloaked</code> ====

The <code>shipTargetCloaked</code> handler is called when the target cloakes.

this.shipTargetCloaked = function()
{
// Your code here
}

==== <code>weaponsSystemsToggled</code> ====
{{oolite-method-added|1.85}}

The <code>weaponsSystemsToggled</code> handler is called whenever the player toggles their weapons systems on or off. The <code>state</code> parameter contains the new state of the weapons systems

this.weaponsSystemsToggled = function(state : boolean)
{
// Your code here
}

=== Equipment and Cargo ===

==== <code>equipmentAdded</code> ====
{{Oolite-method-added|1.81}}

The <code>equipmentAdded</code> handler is called whenever the player ship gains an item of equipment. This includes "gaining" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is damaged. This event will fire regardless of the reason for the equipment being added to the ship.

this.equipmentAdded = function(equipmentKey)
{
// Your code here
}

This is often more convenient than monitoring both <code>equipmentRepaired</code> and <code>playerBoughtEquipment</code>, and will also detect equipment addition by script.

==== <code>equipmentDamaged</code> ====

The <code>equipmentDamaged</code> handler is called when equipment gets damaged. (world script only)

this.equipmentDamaged = function(equipmentKey)
{
// Your code here
}

==== <code>equipmentRemoved</code> ====
{{Oolite-method-added|1.81}}

The <code>equipmentRemoved</code> handler is called whenever the player ship loses an item of equipment. This includes "losing" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is repaired. This event will fire regardless of the reason for the equipment being removed from the ship.

this.equipmentRemoved = function(equipmentKey)
{
// Your code here
}

==== <code>equipmentRepaired</code> ====
{{Oolite-method-added|1.77}}

The <code>equipmentRepaired</code> handler is called when equipment gets repaired. (world script only)

this.equipmentRepaired = function(equipmentKey)
{
// Your code here
}

==== <code>playerBoughtCargo</code> ====
{{Oolite-method-added|1.77}}

The <code>playerBoughtCargo</code> handler is called when cargo is bought at the market screen. <code>commodity</code> contains the non-localised name for the cargo. You can get the localised name using <code>expandDescription("[commodity-name "+commodity+"]");</code>. <code>price</code> is price per unit in tenths of a credit.

this.playerBoughtCargo = function(commodity, units, price)
{
// Your code here
}

==== <code>playerBoughtEquipment</code> ====

The <code>playerBoughtEquipment</code> handler is called when equipment is bought at the outfit screen.

this.playerBoughtEquipment = function(equipment, paid)
{
// Your code here
}

The 'paid' parameter is added from 1.89 onwards. This is the amount of credits the player paid for the equipment, including any refunds that might have been applied during the purchase (eg when purchasing a laser and installing it in a position where a laser is already fitted, the cost of the current laser will be refunded to the player during the purchase).

==== <code>playerBoughtNewShip</code> ====

The <code>playerBoughtNewShip</code> handler is called when a new ship is bought. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerBoughtNewShip = function(ship, price)
{
// Your code here
}

The 'price' parameter is added from 1.81 onwards. It is the cost of the ship (not counting any trade-in value of the player's old ship) in credits, or zero for changes using [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip()</code>]]

'''Note:''' In a future release of Oolite, <code>playerBoughtNewShip</code> will no longer be fired when the ship is replaced using [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip()</code>]]. Instead, the <code>[[#playerReplacedShip|playerReplacedShip]]</code> event should be used. At the moment, both events (<code>playerBoughtNewShip</code> and <code>playerReplacedShip</code>) will fire.

'''See also:''' <code>[[#playerWillBuyNewShip|playerWillBuyNewShip]]</code>

==== <code>playerChangedPrimedEquipment</code> ====
{{Oolite-method-added|1.85}}

The <code>playerChangedPrimedEquipment</code> handler is called whenever the player changes the currently primed equipment (either with shift-n or ctrl-shift-n). The equipment key of the newly primed equipment will be passed as an argument.

this.playerChangedPrimedEquipment = function(equipmentKey)
{
// Your code here
}

==== <code>playerReplacedShip</code> ====
{{Oolite-method-added|1.89}}

The <code>playerReplacedShip</code> handler is called when the player ship is replaced via the JS method [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip</code>]]. May be needed to re-evaluate the old equipment as replacing a ship does not trigger equipment removal.

this.playerReplacedShip = function(ship)
{
// Your code here
}

'''See also:''' <code>[[#playerWillReplaceShip|playerWillReplaceShip]]</code>

==== <code>playerSoldCargo</code> ====
{{Oolite-method-added|1.77}}

The <code>playerSoldCargo</code> handler is called when cargo is sold at the market screen. <code>commodity</code> contains the non-localised name for the cargo. You can get the localised name using <code>expandDescription("[commodity-name "+commodity+"]");</code>. <code>price</code> is price per unit in tenths of a credit.

this.playerSoldCargo = function(commodity, units, price)
{
// Your code here
}

==== <code>shipScoopedFuel</code> ====
{{Oolite-method-added|1.77}}

The <code>shipScoopedFuel</code> handler is called whenever the player's ship transfers 0.1LY of fuel from the scoops to the tank.

this.shipScoopedFuel = function()
{
// Your code here
}

==== <code>shipScoopedOther</code> ====

The <code>shipScoopedOther</code> handler is called when a ship scoops cargo. The scooped item is transferred as argument.<br>If the cargo is scripted cargo, but not otherwise, then the scooped cargo itself gets the handler <code>shipWasScooped</code> with the scooper as argument.

this.shipScoopedOther = function(whom)
{
// Your code here
}

==== <code>playerWillBuyNewShip</code> ====
{{Oolite-method-added|1.89}}

The <code>playerWillBuyNewShip</code> handler is called just before a new ship is bought. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerWillBuyNewShip = function(dataKey, shipyard, price, tradeIn)
{
// Your code here
}

<code>dataKey</code> is the shipdata.plist <code>dataKey</code> for the ship being purchased.

<code>shipyard</code> is a dictionary object containing details about the ship being purchased, with information similar to the following:
{
short_description: "Python: Plus Galactic Hyperdrive. Extra Energy Unit. Docking Computers. E.C.M. System. Forward weapon upgraded to military laser. Price 215 000 ₢.",
shipdata_key: "python-player",
id: "675b6b-c60a74",
price: 215000,
ship: {
...''[[shipdata.plist]]'' details of ship...
},
personality: 9807,
extras: ["EQ_GAL_DRIVE", "EQ_FUEL_SCOOPS", "EQ_ENERGY_UNIT", "EQ_FUEL_INJECTION", "EQ_DOCK_COMP", "EQ_ECM"]
}

<code>price</code> is the amount being paid the for ship.

<code>tradeIn</code> is the trade in value of the current ship.

'''See also:''' <code>[[#playerBoughtNewShip|playerBoughtNewShip]]</code>

==== <code>playerWillReplaceShip</code> ====
{{Oolite-method-added|1.89}}

The <code>playerWillReplaceShip</code> handler is called just before a ship is replaced using [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip()</code>]]. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerWillReplaceShip = function(dataKey)
{
// Your code here
}

<code>dataKey</code> is the shipdata.plist <code>dataKey</code> for the ship being purchased.

'''See also:''' <code>[[#playerReplacedShip|playerReplacedShip]]</code>

=== Other ===

==== <code>chartHightlightModeChanged</code> ====
{{oolite-method-added|1.87}}

The <code>chartHighlightModeChanged</code> handler is called whenever the highlight mode of the galactic chart is changed either manually (from player input) or programmatically (by setting the mode with <code>[[Oolite JavaScript Reference: PlayerShip#chartHighlightMode|player.ship.chartHightlightMode]]</code>). The "newMode" parameter will be one of the following:
* <code>"OOLRC_MODE_SUNCOLOR"</code>
* <code>"OOLRC_MODE_ECONOMY"</code>
* <code>"OOLRC_MODE_GOVERNMENT"</code>
* <code>"OOLRC_MODE_TECHLEVEL"</code>

this.chartHightlightModeChanged = function(newMode)
{
// Your code here
}

==== <code>compassTargetChanged</code> ====

The <code>compassTargetChanged</code> handler is called when a new target is selected. Mode can be any of the following:

COMPASS_MODE_BASIC
COMPASS_MODE_PLANET
COMPASS_MODE_STATION
COMPASS_MODE_SUN
COMPASS_MODE_TARGET
COMPASS_MODE_BEACONS

script example

this.compassTargetChanged = function(whom, mode)
{
log(' Now targeting ' + whom);
// Your code here
}

==== <code>dayChanged</code> ====
{{oolite-method-added|1.77}}

The <code>dayChanged</code> handler is called each time a new day starts. At very low frame rates while the clock is updating, it is possible for this handler to be called twice in the same frame. Therefore, clock.days will not be correct for one of the calls. Use the day number (newday parameter) passed to the handler instead.

this.dayChanged = function(newday)
{
// Your code here
}

==== <code>escapePodSequenceOver</code> ====

The <code>escapePodSequenceOver</code> handler is called at the end of the escape pod sequence, after the <code>shipLaunchedEscapePod</code> event and just prior to the <code>shipWillDockWithStation</code> and <code>shipDockedWithStation</code> events.

Use this handler if you need to override the destination for the escape pod with [[Oolite_JavaScript_Reference:_Player#setEscapePodDestination|<code>player.setEscapePodDestination()</code>]].

this.escapePodSequenceOver = function()
{
// Your code here
}

==== <code>guiScreenChanged</code> ====

The <code>guiScreenChanged</code> handler is called when the <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> changes. The ''from'' parameter is the screen it is leaving and ''to'' is the screen initially being switched to. Note that the screen can have changed again in the meantime by the action of other oxps. Therefore, it is generally better to test the global <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> to see which page is really on display instead of using the ''to'' parameter. (world script only)

This handler will only fire when switched to/from any of the following:

1.76: <code>"GUI_SCREEN_MAIN"</code>, <code>"GUI_SCREEN_STATUS"</code>(F5), <code>"GUI_SCREEN_MANIFEST"</code>(F5F5), <code>"GUI_SCREEN_SYSTEM_DATA"</code>(F7), <code>"GUI_SCREEN_OPTIONS"</code>, <code>"GUI_SCREEN_EQUIP_SHIP"</code>(F3), <code>"GUI_SCREEN_SHIPYARD"</code>(F3F3), <code>"GUI_SCREEN_SHORT_RANGE_CHART"</code>(F6), <code>"GUI_SCREEN_LONG_RANGE_CHART"</code>(F6F6), <code>"GUI_SCREEN_MARKET"</code>(F8), <code>"GUI_SCREEN_CONTRACTS"</code>, <code>"GUI_SCREEN_REPORT"</code>

1.77: adds <code>"GUI_SCREEN_INTERFACES"</code>(F4) and removes <code>"GUI_SCREEN_CONTRACTS"</code>

1.81: adds <code>"GUI_SCREEN_MARKETINFO"</code>(F8F8)

this.guiScreenChanged = function(to, from)
{
// Your code here
}

==== <code>guiScreenWillChange</code> ====

The <code>guiScreenWillChange</code> handler is called when the <code>[[Oolite JavaScript Reference: Global#guiScreen|guiScreen]]</code> is about to change. On these screens, a script could change the content of the page to be displayed. (world script only)

This handler will only fire when switching to/from any of the following:

<code>"GUI_SCREEN_EQUIP_SHIP"</code>(F3), <code>"GUI_SCREEN_MANIFEST"</code>(F5F5), <code>"GUI_SCREEN_MARKET"</code>(F8), <code>"GUI_SCREEN_SHIPYARD"</code>(F3F3), <code>"GUI_SCREEN_SYSTEM_DATA"</code>(F7)

1.77: adds <code>"GUI_SCREEN_INTERFACES"</code>(F4), <code>"GUI_SCREEN_STATUS"</code>(F5)

1.81: adds <code>"GUI_SCREEN_MARKETINFO"</code>(F8F8)

this.guiScreenWillChange = function(to, from)
{
// Your code here
}

==== <code>infoSystemChanged</code> ====
{{oolite-method-added|1.83}}

The <code>infoSystemChanged</code> handler is called when the system displayed in F7 is changed, e.g. by moving the small blue cursor along the planned route in the chart.

this.infoSystemChanged = function(to, from)
{
// Your code here
}

==== <code>infoSystemWillChange</code> ====
{{oolite-method-added|1.85}}

The <code>infoSystemWChange</code> handler is called just before the system displayed in F7 is updated, e.g. by moving the small blue cursor along the planned route in the chart.

this.infoSystemWillChange = function(to, from)
{
// Your code here
}

==== <code>mfdKeyChanged</code> ====
{{oolite-method-added|1.85}}

The <code>mfdKeyChanged</code> handler is called whenever the player changes the content of an MFD slot. The <code>activeMFD</code> parameter identifies which MFD slot is being changed, and the <code>mfdKey</code> specifies the key code now in use in this slot.

this.mfdKeyChanged = function(activeMFD : integer, mfdKey : string)
{
// Your code here
}

'''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#setMultiFunctionDisplay|PlayerShip.setMultiFunctionDisplay()]]</code>

==== <code>missionChoiceWasReset</code> ====

The <code>missionChoiceWasReset</code> handler is called when the mission choice is set to <code>null</code> via script (either using the legacy script method resetMissionChice or using <code>mission.runScreen ({choices: null})</code> in javascript)

this.missionChoiceWasReset= function()
{
// Your code here
}

==== <code>missionScreenEnded</code> ====

The <code>missionScreenEnded</code> handler is called when a mission screen ends. Note that another script may have put up a new mission screen in the meantime. (world script only)

this.missionScreenEnded = function()
{
// Your code here
}

==== <code>missionScreenOpportunity</code> ====

The <code>missionScreenOpportunity</code> handler is called if there are no mission/report screens active and the player's ship is docked. It gets fired at game startup, upon docking and after an arrival report or previous mission screen has ended. (world script only)

this.missionScreenOpportunity= function()
{
// Your code here
}

This handler works a bit different from other handlers. It fires for every installed OXP/OXZ until one creates a mission screen during this handler, and then it stops. When the mission screen ends and there is no callback function that creates a new mission screen, the <code>missionScreenOpportunity</code> is sent again to all installed OXPs/OXZs starting with the one that created the last mission screen. All this means is that when this handler fires, it is safe to show a mission screen and no further tests are needed.

==== <code>reportScreenEnded</code> ====

The <code>reportScreenEnded</code> handler is called when the last arrival-report screen ends. This is a screen that should not be written by a missionscreen. The code should wait until this eventhandler fires. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

this.reportScreenEnded = function()
{
// Your code here
}

==== <code>selectedMFDChanged</code> ====
{{oolite-method-added|1.85}}

The <code>selectedMFDChanged</code> handler is send whenever the player selects a new MFD slot (normally using the default keypress ";"). The <code>activeMFD</code> paramater is the index of the MFD which is now active.

this.selectedMFDChanged = function(activeMFD : integer)
{
// Your code here
}

==== <code>shipCollided</code> ====

The <code>shipCollided</code> handler is send after a collision with otherShip.

this.shipCollided = function(otherShip)
{
// Your code here
}

==== <code>shipSpawned</code> ====

The <code>shipSpawned</code> handler is called after an NPC ship has been added to the system. After a witchspace jump it means that first all ships are added to the system, then all the relevant shipSpawned events are triggered.<br>
This handler for the worldScript is new since Oolite 1.74. After the event is sent to the shipScript, it is now also send to the worldScript with the added entity as argument.

this.shipSpawned = function(ship)
{
// Your code here
}

==== <code>shipLaunchedEscapePod</code> ====

The <code>shipLaunchedEscapePod</code> handler is called when the player bails out. This will be followed by the <code>escapePodSequenceOver</code> event, and then a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds.

this.shipLaunchedEscapePod = function(escapepod)
{
// Your code here
}

==== <code>systemInformationChanged</code> ====
{{oolite-method-added|1.79}}

The <code>systemInformationChanged</code> handler is called when system information is modified. It is passed the galaxy and system ID which were changed, and the key and new value in the SystemInfo object.

To avoid problems with recursion, attempting to change the value of any system information property from within this handler will fail and log an error. Also note that changes which take place while Oolite is not running (from OXP planetinfo.plist files) will not cause this handler to be called when the game is reloaded.

this.systemInformationChanged = function(galaxy,system,key,newValue)
{
// Your code here
}

==== <code>viewDirectionChanged</code> ====

The <code>viewDirectionChanged</code> handler is called when the player view changes, with a string to indicate which view the player is facing. Amongst its possible values are "VIEW_FORWARD", "VIEW_AFT", "VIEW_PORT", "VIEW_STARBOARD",
"VIEW_CUSTOM",
"VIEW_GUI_DISPLAY".

this.viewDirectionChanged = function(viewString)
{
if (viewString == "VIEW_PORT")
{
// Your code here
}
}

=== System population ===

In Oolite 1.79 and later, functions are called to populate and repopulate the system. These functions do not have fixed names, as they depend on the system, but otherwise act like normal worldscript functions. [[Oolite System Populator|The populator page]] has more documentation on these functions.

=== Defunct ===

==== <code>equipmentDestroyed</code> ====
''Handler no longer exists in current stable version 1.80''

The <code>equipmentDestroyed</code> handler is called when equipment gets destroyed completely beyond repair. (in strict mode, 1.77 or earlier only) (world script only)

this.equipmentDestroyed = function(equipment)
{
// Your code here
}

==== <code>tickle</code> (removed in 1.77) ====

The <code>tickle</code> handler is called periodically-ish, whenever the old [[property list|plist]] scripts are updated. <code>tickle()</code> is deprecated. In new code, use appropriate event handlers or [[Oolite JavaScript Reference: Timer|timers]] instead.

=== Missing Events ===

All the initially planned events have been implemented in 1.74.

If there are other events you would like to be able to respond to, please write a request [http://www.aegidian.org/bb/viewtopic.php?t=3296 on the forum].

'''See also:''' [[Oolite JavaScript Reference: Ship script event handlers|ship script event handlers]]

[[Category:Oolite JavaScript Reference]]

File:TionislaChronicleArray.oxz

2023-06-07T13:45:39Z

Alnivel: Alnivel uploaded a new version of File:TionislaChronicleArray.oxz

Version 1.04

Debug OXP

2023-05-26T21:01:24Z

Alnivel: /* The console script */ Updated the example and added a section about using variables

If you are developing OXPs, the Debug Console is a tool that you should keep handy at all times, because it enables you to test things that normally are either impossible to test without it, or require substantial effort to generate the right conditions for testing. '''Debug.oxp''' enables JavaScript console support in Oolite (1.70 and later). It also adds a menu with various debug facilities under Mac OS X.

'''To run this OXP you need the [http://www.oolite.org/download/ ''OXP Developer release''] version of Oolite.''' There are subtle differences between the versions for each of the three platforms (AppleMac, Windows & Linux).

=== Downloads ===
[[Media:Basic-debug.oxz|Basic-Debug OXZ for Oolite v1.83/84]]

== External JavaScript console support ==
On all platforms, installing Debug.oxp enables support for external console applications using the [[Oolite debug console TCP protocol]]. By default, it will attempt to connect to a console running on the same computer, but this can be changed by specifying a different <code>console-host</code> (and, optionally, <code>console-port</code>) in ''debugConfig.plist''. For external console support on the same computer under Mac OS X, <code>console-host</code> must be explicitly set to “127.0.0.1”; if this is not done, the [[#Integrated JavaScript console|integrated JavaScript console]] will be used instead. For information on using a console (integrated or external), see [[#Using the JavaScript console|Using the JavaScript console]] below.

'''Note:''' A cross-platform, python based, external console application is available in the [https://github.com/OoliteProject/oolite-debug-console/releases/download/v1.5/OoDebugConsole1.5.zip Oolite GitHub project] area.

It contains a precompiled console for windows based computers, and the original python based console for Linux and Posix compliant computers.

On Debian or Ubuntu Linux you will need python 2.6.x installed and (at least) the packages <code>blt python-tk tk8.5</code> (or the equivalents in other distros.)

== Mac OS X-specific features ==
Under Mac OS X, the Debug OXP provides a menu with various debugging options and an integrated JavaScript console, as well as enabling external console support as on all platforms. This was originally written by [http://www.aegidian.org/bb/viewtopic.php?f=8&t=3661 Jens Ayton/Ahruman] for version 1.69 (TR) back in 2007. To use this you need the '''Debug OXP''' in your AddOns folder ''and'' the '''Test Release''' version of Oolite.

=== Debug menu (Mac OS X only) ===
[[Image:Oolite-debug-menu.png|494px]]

The Debug menu provides options to
* Show the Oolite run log in the standard [[OXP_howto#OXP_Verifier|Console]] application.
* Enable or disable various classes of log message at runtime (like editing ''logcontrol.plist'', without the need to restart Oolite).
* Enable various testing features, such as drawing of bounding boxes.
* Show the JavaScript console, and specify when it should be shown automatically. (This may not have any effect with external consoles, depending on the external console implementation.)
* Create a ship of any role near the main station (equivalent to the <code>:spawn</code> [[#Macros|macro]]).
Note: some of these features are implemented by sending JavaScript messages to the [[#The console script|console script]]. If the script has been modified, some features may not work properly.

The Log Message Classes submenu can be modified by editing ''debugLogMessageClassesMenu.plist'', found inside the OXP. This is merged from Config directories in the usual fashion.

=== Integrated JavaScript console (Mac OS X only) ===
[[Image:Oolite debug protocol example 1.png|594px]]

The integrated JavaScript console provides a window within Oolite which acts as a [[#Using the JavaScript console|JavaScript console]]. It can be shown using the Show JavaScript Console command in the Debug menu, unless external console mode has been enabled by setting <code>console-host</code> in ''debugConfig.plist''.

The integrated console has a 100-line memory. To see previous commands, press ⇞ (Page Up) or ⌥↑ (Option-Up Arrow). You can go the other way in the obvious manner.

== Using the JavaScript console ==
The JavaScript console, whether integrated or external, provides a powerful mechanism for interactively manipulating the game world. It can be used to issue simple commands, like <code>player.ship.awardEquipment("EQ_FUEL_INJECTION")</code>. It can be used to inspect properties of entities in the game world. And it can be used to develop scripts, by rewriting and testing methods of live ship scripts and world scripts.

=== Macros ===
Macros are a special type of command prefixed with a colon. Instead of being interpreted as a JavaScript command, a macro is looked up in a dictionary, and the result is used as the “real” command. For instance, if you enter the command <code>:listM</code> (short for “list macros”), the macro dictionary is queried for the string “listM”, and (by default) the code <code>for (let prop in macros) { ConsoleMessage('macro-list', ':' + prop) }</code> is found and executed. This code is called the ''expansion'' of the macro. The result is a list of macros being printed:
:clr
:clear
:spawn
:bgColor
:showM
:rmFgColor
::
:d
:ds
:listM
:setM
:delM
:fgColor
:rmBgColor
:resetM

As you can see in the example, To see the expansion of a macro without executing it, use <code>:showM</code>:
> :showM :delM
:delM = deleteMacro(PARAM)

When a macro with the word <code>PARAM</code> is executed, <code>PARAM</code> is replaced with any text following the macro name, surrounded in quotation marks. This is how <code>:showM</code> functions, for example; the string “:showM :delM” is expanded to “showMacro(":delM")”, causing the JavaScript function <code>showMacro()</code>, which is part of the [[#The console script|console script]], to be called. You can see the implementation of <code>showMacro()</code> by entering <code>showMacro</code> – without any parentheses – into the console.

An initial set of macros is loaded from ''debugConfig.plist''. If you edit any macros, using <code>:setM</code> or <code>:delM</code>, all macros are saved in Oolite’s preferences from that point forwards. This means that you don’t have to re-enter any macros you write with <code>:setM</code> after restarting Oolite.

The following example creates a simple :msg macro:
> :setM msg ConsoleMessage(' ',PARAM)
If you then type:
> :msg Hello World
The macro will be expanded, and you'll see “Hello World” on the console. However, macros are not functions, so you cannot use macros in the middle of javascript, or as part of another macro.

=== Console Properties ===

The <code>console</code> object has several properties. To see the full list of them check <code>oolite-debug-console.js</code> inside your copy of the Debug OXP.

==== Debug Flags ====
'''debugFlags''' : Number (integer, read/write)
An integer bit mask specifying various debug options. Note that the flags vary between builds.
The current flags can be seen in OODebugFlags.h in the Oolite source code, for instance at:
https://github.com/OoliteProject/oolite/blob/master/src/Core/Debug/OODebugFlags.h

DEBUG_LINKED_LISTS = 0x00000001
DEBUG_COLLISIONS = 0x00000004
DEBUG_DOCKING = 0x00000008
DEBUG_OCTREE_LOGGING = 0x00000010
DEBUG_BOUNDING_BOXES = 0x00000040
DEBUG_OCTREE_DRAW = 0x00000080
DEBUG_DRAW_NORMALS = 0x00000100
DEBUG_NO_DUST = 0x00000200
DEBUG_NO_SHADER_FALLBACK = 0x00000400
DEBUG_SHADER_VALIDATION = 0x00000800
DEBUG_MISC = 0x10000000

To set flags, you can use either numeric literals directly or symbolic names as properties of the console object. For example, to toggle rendering of bounding boxes and surface normals, you might use:
console.debugFlags ^= console.DEBUG_BOUNDING_BOXES;
console.debugFlags ^= console.DEBUG_DRAW_NORMALS;

This will work as well:
console.debugFlags ^= 0x00000040;
console.debugFlags ^= 0x00000100;

To disable everything just set it to zero:
console.debugFlags = 0

==== Shaders ====
'''shaderMode''' : String (read/write)
A string specifying the current shader mode. One of the following:
* "SHADERS_NOT_SUPPORTED"
* "SHADERS_OFF"
* "SHADERS_SIMPLE"
* "SHADERS_FULL"
If it is SHADERS_NOT_SUPPORTED, it cannot be set to any other value. If it is not SHADERS_NOT_SUPPORTED, it can be set to SHADERS_OFF, SHADERS_SIMPLE or SHADERS_FULL, unless maximumShaderMode (see below) is SHADERS_SIMPLE, in which case SHADERS_FULL is not allowed.

'''Note:''' this is equivalent to <code>[[Oolite JavaScript Reference: Oolite#gameSettings|oolite.gameSettings]].shaderEffectsLevel</code>, which is available even when the debug console is not active, but is read-only.

'''maximumShaderMode''' : String (read-only)
A string specifying the fanciest available shader mode. One of the following:
* "SHADERS_NOT_SUPPORTED"
* "SHADERS_SIMPLE"
* "SHADERS_FULL"

'''reducedDetailMode''': Boolean (read/write)
Whether reduced detail mode is in effect (simplifies graphics in various ways).

'''glVendorString''' : String (read-only)

'''glRendererString''' : String (read-only)
Information about the OpenGL renderer.

==== Error Logging ====
'''dumpStackForErrors''' : Boolean (read/write)
If <code>true</code>, when an error or exception is reported a stack trace will be written to the log (if possible). Ignored if not showing error locations.

'''dumpStackForWarnings''' : Boolean (read/write)
If <code>true</code>, when a warning is reported a stack trace will be written to the log (if possible). Ignored if not showing error locations.

'''showErrorLocations''' : Boolean (read/write)
<code>true</code> if file and line should be shown when reporting JavaScript errors and warnings. Default: <code>true</code>.

'''showErrorLocationsDuringConsoleEval''': Boolean (read/write)
Override value for showErrorLocations used while evaluating code entered in the console. Default: <code>false</code>. (This information is generally not useful for code passed to eval().)

==== Miscellaneous ====
'''displayFPS''': Boolean (read/write)
Boolean specifying whether FPS (and associated information) should be displayed.

'''platformDescription''' : String (read-only)
Information about the system Oolite is running on. The format of this string is not guaranteed, do not attempt to parse it.

'''settings''' : Object
A key-value store that is saved persistently. Values from debugConfig.plist are used as defaults, and any changed values are stored with the game’s preferences.

'''ignoreDroppedPackets''' : Boolean (read/write)
If <code>true</code> the TCP console will try to stay connected, ignoring dropped TCP packets, if <code>false</code> - will disconnect if an error affects.



=== Profiling ===
{{QuoteText|Text=
Just pointing out the obvious here, but I think it needs to be noted that all these optimization techniques explained here are not themselves the objective, but the means to get performance. These techniques are not there to jump in and start writing complicated code. They should be used when there is need and where they are needed. And to find this out, the biggest weapon we have is profiling. I fully recommend that before you change anything in your code, you profile it and find out where it really needs attention.

Oolite Test Release writes something in the log header that may have escaped the attention of many, but if you look more carefully, you'll see it: It says: Build options: [...] JavaScript profiling. So you can use Oolite itself to see where bottlenecks in your OXP might be and then you can apply all these techniques exactly where there is a gain to be obtained.

. . .

Once the bottlenecks have been identified, then you know where you need to turn to and apply all the tips contained here. If you want performance, always profile.
|Source=([http://www.aegidian.org/bb/viewtopic.php?p=257063#p257063 another_commander] regarding [[Optimization_tips|optimization tips]])}}

==== <code>profile</code> ====
function '''profile'''(func : function [, this : Object]) : String
Time the specified function, report the time spent in various Oolite functions and how much time is excluded from the time limiter mechanism. If the second argument isn't specified it defaults to the console world script.

Example of use:
console.profile(function() { return this._systemName(42) }, worldScripts["oolite-contracts-helpers"])
It will result in something like this:
Total time: 0.059 ms
JavaScript: 0.034 ms, native: 0.024 ms
Counted towards limit: 0.0439983 ms, excluded: 0.0150017 ms
Profiler overhead: 0.034 ms
NAME T COUNT TOTAL SELF TOTAL% SELF% SELFMAX
(oolite-contracts-helpers.js:161) <anonymous> J 1 0.05 0.02 81.4 40.7 0.02
SystemInfoGetProperty N 4 0.02 0.01 28.8 20.3 0.01
(<console input>) <anonymous> J 1 0.06 0.01 98.3 16.9 0.01
GetJSSystemInfoForSystem N 1 0.00 0.00 8.5 8.5 0.00
OOJSNativeObjectFromJSObject N 4 0.00 0.00 6.8 6.8 0.00
SystemStaticInfoForSystem N 1 0.01 0.00 10.2 1.7 0.00
OOStringFromJSString N 4 0.00 0.00 1.7 1.7 0.00
GlobalGetProperty N 1 0.00 0.00 1.7 1.7 0.00
-[NSString(OOJavaScriptExtensions) oo:jsValueInContext:] N 1 0.00 0.00 0.0 0.0 0.00
The table contains the trace of the calls, with separate metrics for each one of them, as well as their type (J for Javascript, N for Native).

You may want to copy the result to the editor with a monospace font if the columns don't appear to be aligned.

'''Note:''' while profile() is running, the time limiter is effectively disabled (specifically, it's set to ten million seconds).

==== <code>getProfile</code> ====
function '''getProfile'''(func : function [, this : Object]) : Object
Like <code>profile()</code>, but returns an object, which is more amenable to processing in scripts. To see the structure of the object, run:
console.getProfile(function(){PS.position.add([0, 0, 0])})



=== Variables in the console ===
You may want to save the result of a command so that you can use it in one of the next commands. There are several ways to do this, as well as several pitfalls.

First of all, as var, let and const limit the scope of the variable to the enclosing function, they do it as well for command scope, so do not use them if you want to reuse the result. In most cases, instead of this just assign the result to the variable without declaration - it will be stored in the <code>[[Oolite JavaScript Reference: Global | global]]</code> object:
> a // Check to ensure that the variable is not defined
Exception: ReferenceError: a is not defined
> a = 123
123
> global.a
123
> a
123
> global.a = 456
456
> a
456

It's the simplest way, and it has one minor pitfall - the variable name must not overlap with existing global properties from the Oolite or other OXPs.

You can also use the console script's <code>this</code>. After defining the variable as a property of <code>this</code> it can be used without explicit <code>this<u>.</u></code>. Property of <code>this</code> hides property of <code>global</code>. See the example (continues the previous):
> this.a = 789
789
> a
789
> global.a // still has the old value
456

Note that <code>this</code> is [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this not a variable but keyword], and has somewhat non-obvious behaviour when used inside of functions (the example continues the previous):
> f = function() { return a } // There is no local a, so it uses one from the command's this, if it wasn't there, it will it would use one from the global scope.
> f()
789
> f = function() { return this.a }
> f() // function called not as a method, so uses "global" as "this" (only in nonstrict code)
456

==== Predefined and special variables ====
The console also offers a few short aliases by default:
P = player;
PS = player.ship;
S = system;
M = missionVariables;
They added in the <code>this</code> way and you can add your own - check the next section for it.

The special variable <code>$</code> stores the last non-<code>undefined</code> result:
> system.addShipsToRoute("trader", 1, 1)
<nowiki>[[Ship "Boa" position: (-105926, 56511.4, 896027) scanClass: CLASS_NEUTRAL status: STATUS_IN_FLIGHT]]</nowiki>
> $[0]
<nowiki>[Ship "Boa" position: (-105926, 56511.4, 896027) scanClass: CLASS_NEUTRAL status: STATUS_IN_FLIGHT]</nowiki>
> $.dataKey
griff_boa_alt-NPC
> $
griff_boa_alt-NPC

=== The console script ===
While an external or integrated console is required to provide a means of user interaction, most of the actual behaviour of the console is implemented in JavaScript, in a script called ''oolite-debug-console.js''. Input typed into the console is passed to the console script, which then generates output. The console script is also informed of log messages and JavaScript errors, and provides a global function, <code>ConsoleMessage(colorCode: String, message: String)</code>, to write messages to the console using its background colour support. Lastly, the console script implements the entire macro system.

This means that the console’s behaviour can be extensively customized, for instance, by replacing the macro system with something more powerful. There are two basic approaches to doing this:
* Creating a custom script (or a copy) with the same name, in an OXP which loads later than Debug.oxp (e.g., one which has a name which comes later in alphabetical order).
* Using a normal world script, and changing the console script object at startup.
The latter approach has the advantage that it can continue to work with future versions of the console script, and multiple patches can coexist. For example, a modification to supplement the macro system with a better one might look as follows:
this.name = "my-super-console-macros"

this.startUp = function()
{
// Ensure debug console is installed
if (!console) return

// Save the original implementation of consolePerformJSCommand
// Note the prefix, used to ensure uniqueness. If several scripts patch
// the same method, it's important that they use different names.
console.script.mySuperConsoleMacros_original_consolePerformJSCommand = console.script.consolePerformJSCommand

// Replace console.script.consolePerformJSCommand with custom function
console.script.consolePerformJSCommand = function(command)
{
// Note that in this function "this" will refer to console.script, "oolite-debug-console", not
// "my-super-console-macros", since the function will be called as a
// method of the console.

// Strip leading spaces, same code as the original function.
while (command.charAt(0) == " ")
{
command = command.substring(1)
}

if (command.charAt(0) == "!")
{
// Super macro call detected.
// Insert super macro system here.
}
else
{
// Otherwise, call through to the original method.
console.script.mySuperConsoleMacros_original_consolePerformJSCommand(command)
}
}
}
This same patching technique, incidentally, can be used to modify scripts at runtime, either from the console or from other scripts.

== Links ==
* [http://www.aegidian.org/bb/viewtopic.php?f=3&t=20965 How do I? .... (on Debug Console)] (2021) - change system, change ship... - 2 pages

* Debug console issues: [http://www.aegidian.org/bb/viewtopic.php?f=10&t=20877 Problem with external debug console on Mac] (2021+)
* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=20512 (WIP) new GUI for debug console] (CAG 2020) - an improved Debug console - see below
* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=20512 Debug Console] for Python and Windows (CAG 2020)
* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=17731 Some Tips] on using the Debug Console (2015) - 1 page
* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=12030 Hints and tips for using the debug console] (2012) - 5 pages
* [http://aegidian.org/bb/viewtopic.php?f=9&t=12779 Handy tip for starting the Debug Console in Linux] (2012)

{{misc-OXP}}
[[Category:Oolite utilities]]
[[Category:Oolite scripting]]

Debug OXP

2023-05-26T18:10:18Z

Alnivel: Added "Profiling" section

If you are developing OXPs, the Debug Console is a tool that you should keep handy at all times, because it enables you to test things that normally are either impossible to test without it, or require substantial effort to generate the right conditions for testing. '''Debug.oxp''' enables JavaScript console support in Oolite (1.70 and later). It also adds a menu with various debug facilities under Mac OS X.

'''To run this OXP you need the [http://www.oolite.org/download/ ''OXP Developer release''] version of Oolite.''' There are subtle differences between the versions for each of the three platforms (AppleMac, Windows & Linux).

=== Downloads ===
[[Media:Basic-debug.oxz|Basic-Debug OXZ for Oolite v1.83/84]]

== External JavaScript console support ==
On all platforms, installing Debug.oxp enables support for external console applications using the [[Oolite debug console TCP protocol]]. By default, it will attempt to connect to a console running on the same computer, but this can be changed by specifying a different <code>console-host</code> (and, optionally, <code>console-port</code>) in ''debugConfig.plist''. For external console support on the same computer under Mac OS X, <code>console-host</code> must be explicitly set to “127.0.0.1”; if this is not done, the [[#Integrated JavaScript console|integrated JavaScript console]] will be used instead. For information on using a console (integrated or external), see [[#Using the JavaScript console|Using the JavaScript console]] below.

'''Note:''' A cross-platform, python based, external console application is available in the [https://github.com/OoliteProject/oolite-debug-console/releases/download/v1.5/OoDebugConsole1.5.zip Oolite GitHub project] area.

It contains a precompiled console for windows based computers, and the original python based console for Linux and Posix compliant computers.

On Debian or Ubuntu Linux you will need python 2.6.x installed and (at least) the packages <code>blt python-tk tk8.5</code> (or the equivalents in other distros.)

== Mac OS X-specific features ==
Under Mac OS X, the Debug OXP provides a menu with various debugging options and an integrated JavaScript console, as well as enabling external console support as on all platforms. This was originally written by [http://www.aegidian.org/bb/viewtopic.php?f=8&t=3661 Jens Ayton/Ahruman] for version 1.69 (TR) back in 2007. To use this you need the '''Debug OXP''' in your AddOns folder ''and'' the '''Test Release''' version of Oolite.

=== Debug menu (Mac OS X only) ===
[[Image:Oolite-debug-menu.png|494px]]

The Debug menu provides options to
* Show the Oolite run log in the standard [[OXP_howto#OXP_Verifier|Console]] application.
* Enable or disable various classes of log message at runtime (like editing ''logcontrol.plist'', without the need to restart Oolite).
* Enable various testing features, such as drawing of bounding boxes.
* Show the JavaScript console, and specify when it should be shown automatically. (This may not have any effect with external consoles, depending on the external console implementation.)
* Create a ship of any role near the main station (equivalent to the <code>:spawn</code> [[#Macros|macro]]).
Note: some of these features are implemented by sending JavaScript messages to the [[#The console script|console script]]. If the script has been modified, some features may not work properly.

The Log Message Classes submenu can be modified by editing ''debugLogMessageClassesMenu.plist'', found inside the OXP. This is merged from Config directories in the usual fashion.

=== Integrated JavaScript console (Mac OS X only) ===
[[Image:Oolite debug protocol example 1.png|594px]]

The integrated JavaScript console provides a window within Oolite which acts as a [[#Using the JavaScript console|JavaScript console]]. It can be shown using the Show JavaScript Console command in the Debug menu, unless external console mode has been enabled by setting <code>console-host</code> in ''debugConfig.plist''.

The integrated console has a 100-line memory. To see previous commands, press ⇞ (Page Up) or ⌥↑ (Option-Up Arrow). You can go the other way in the obvious manner.

== Using the JavaScript console ==
The JavaScript console, whether integrated or external, provides a powerful mechanism for interactively manipulating the game world. It can be used to issue simple commands, like <code>player.ship.awardEquipment("EQ_FUEL_INJECTION")</code>. It can be used to inspect properties of entities in the game world. And it can be used to develop scripts, by rewriting and testing methods of live ship scripts and world scripts.

=== Macros ===
Macros are a special type of command prefixed with a colon. Instead of being interpreted as a JavaScript command, a macro is looked up in a dictionary, and the result is used as the “real” command. For instance, if you enter the command <code>:listM</code> (short for “list macros”), the macro dictionary is queried for the string “listM”, and (by default) the code <code>for (let prop in macros) { ConsoleMessage('macro-list', ':' + prop) }</code> is found and executed. This code is called the ''expansion'' of the macro. The result is a list of macros being printed:
:clr
:clear
:spawn
:bgColor
:showM
:rmFgColor
::
:d
:ds
:listM
:setM
:delM
:fgColor
:rmBgColor
:resetM

As you can see in the example, To see the expansion of a macro without executing it, use <code>:showM</code>:
> :showM :delM
:delM = deleteMacro(PARAM)

When a macro with the word <code>PARAM</code> is executed, <code>PARAM</code> is replaced with any text following the macro name, surrounded in quotation marks. This is how <code>:showM</code> functions, for example; the string “:showM :delM” is expanded to “showMacro(":delM")”, causing the JavaScript function <code>showMacro()</code>, which is part of the [[#The console script|console script]], to be called. You can see the implementation of <code>showMacro()</code> by entering <code>showMacro</code> – without any parentheses – into the console.

An initial set of macros is loaded from ''debugConfig.plist''. If you edit any macros, using <code>:setM</code> or <code>:delM</code>, all macros are saved in Oolite’s preferences from that point forwards. This means that you don’t have to re-enter any macros you write with <code>:setM</code> after restarting Oolite.

The following example creates a simple :msg macro:
> :setM msg ConsoleMessage(' ',PARAM)
If you then type:
> :msg Hello World
The macro will be expanded, and you'll see “Hello World” on the console. However, macros are not functions, so you cannot use macros in the middle of javascript, or as part of another macro.

=== Console Properties ===

The <code>console</code> object has several properties. To see the full list of them check <code>oolite-debug-console.js</code> inside your copy of the Debug OXP.

==== Debug Flags ====
'''debugFlags''' : Number (integer, read/write)
An integer bit mask specifying various debug options. Note that the flags vary between builds.
The current flags can be seen in OODebugFlags.h in the Oolite source code, for instance at:
https://github.com/OoliteProject/oolite/blob/master/src/Core/Debug/OODebugFlags.h

DEBUG_LINKED_LISTS = 0x00000001
DEBUG_COLLISIONS = 0x00000004
DEBUG_DOCKING = 0x00000008
DEBUG_OCTREE_LOGGING = 0x00000010
DEBUG_BOUNDING_BOXES = 0x00000040
DEBUG_OCTREE_DRAW = 0x00000080
DEBUG_DRAW_NORMALS = 0x00000100
DEBUG_NO_DUST = 0x00000200
DEBUG_NO_SHADER_FALLBACK = 0x00000400
DEBUG_SHADER_VALIDATION = 0x00000800
DEBUG_MISC = 0x10000000

To set flags, you can use either numeric literals directly or symbolic names as properties of the console object. For example, to toggle rendering of bounding boxes and surface normals, you might use:
console.debugFlags ^= console.DEBUG_BOUNDING_BOXES;
console.debugFlags ^= console.DEBUG_DRAW_NORMALS;

This will work as well:
console.debugFlags ^= 0x00000040;
console.debugFlags ^= 0x00000100;

To disable everything just set it to zero:
console.debugFlags = 0

==== Shaders ====
'''shaderMode''' : String (read/write)
A string specifying the current shader mode. One of the following:
* "SHADERS_NOT_SUPPORTED"
* "SHADERS_OFF"
* "SHADERS_SIMPLE"
* "SHADERS_FULL"
If it is SHADERS_NOT_SUPPORTED, it cannot be set to any other value. If it is not SHADERS_NOT_SUPPORTED, it can be set to SHADERS_OFF, SHADERS_SIMPLE or SHADERS_FULL, unless maximumShaderMode (see below) is SHADERS_SIMPLE, in which case SHADERS_FULL is not allowed.

'''Note:''' this is equivalent to <code>[[Oolite JavaScript Reference: Oolite#gameSettings|oolite.gameSettings]].shaderEffectsLevel</code>, which is available even when the debug console is not active, but is read-only.

'''maximumShaderMode''' : String (read-only)
A string specifying the fanciest available shader mode. One of the following:
* "SHADERS_NOT_SUPPORTED"
* "SHADERS_SIMPLE"
* "SHADERS_FULL"

'''reducedDetailMode''': Boolean (read/write)
Whether reduced detail mode is in effect (simplifies graphics in various ways).

'''glVendorString''' : String (read-only)

'''glRendererString''' : String (read-only)
Information about the OpenGL renderer.

==== Error Logging ====
'''dumpStackForErrors''' : Boolean (read/write)
If <code>true</code>, when an error or exception is reported a stack trace will be written to the log (if possible). Ignored if not showing error locations.

'''dumpStackForWarnings''' : Boolean (read/write)
If <code>true</code>, when a warning is reported a stack trace will be written to the log (if possible). Ignored if not showing error locations.

'''showErrorLocations''' : Boolean (read/write)
<code>true</code> if file and line should be shown when reporting JavaScript errors and warnings. Default: <code>true</code>.

'''showErrorLocationsDuringConsoleEval''': Boolean (read/write)
Override value for showErrorLocations used while evaluating code entered in the console. Default: <code>false</code>. (This information is generally not useful for code passed to eval().)

==== Miscellaneous ====
'''displayFPS''': Boolean (read/write)
Boolean specifying whether FPS (and associated information) should be displayed.

'''platformDescription''' : String (read-only)
Information about the system Oolite is running on. The format of this string is not guaranteed, do not attempt to parse it.

'''settings''' : Object
A key-value store that is saved persistently. Values from debugConfig.plist are used as defaults, and any changed values are stored with the game’s preferences.

'''ignoreDroppedPackets''' : Boolean (read/write)
If <code>true</code> the TCP console will try to stay connected, ignoring dropped TCP packets, if <code>false</code> - will disconnect if an error affects.



=== Profiling ===
{{QuoteText|Text=
Just pointing out the obvious here, but I think it needs to be noted that all these optimization techniques explained here are not themselves the objective, but the means to get performance. These techniques are not there to jump in and start writing complicated code. They should be used when there is need and where they are needed. And to find this out, the biggest weapon we have is profiling. I fully recommend that before you change anything in your code, you profile it and find out where it really needs attention.

Oolite Test Release writes something in the log header that may have escaped the attention of many, but if you look more carefully, you'll see it: It says: Build options: [...] JavaScript profiling. So you can use Oolite itself to see where bottlenecks in your OXP might be and then you can apply all these techniques exactly where there is a gain to be obtained.

. . .

Once the bottlenecks have been identified, then you know where you need to turn to and apply all the tips contained here. If you want performance, always profile.
|Source=([http://www.aegidian.org/bb/viewtopic.php?p=257063#p257063 another_commander] regarding [[Optimization_tips|optimization tips]])}}

==== <code>profile</code> ====
function '''profile'''(func : function [, this : Object]) : String
Time the specified function, report the time spent in various Oolite functions and how much time is excluded from the time limiter mechanism. If the second argument isn't specified it defaults to the console world script.

Example of use:
console.profile(function() { return this._systemName(42) }, worldScripts["oolite-contracts-helpers"])
It will result in something like this:
Total time: 0.059 ms
JavaScript: 0.034 ms, native: 0.024 ms
Counted towards limit: 0.0439983 ms, excluded: 0.0150017 ms
Profiler overhead: 0.034 ms
NAME T COUNT TOTAL SELF TOTAL% SELF% SELFMAX
(oolite-contracts-helpers.js:161) <anonymous> J 1 0.05 0.02 81.4 40.7 0.02
SystemInfoGetProperty N 4 0.02 0.01 28.8 20.3 0.01
(<console input>) <anonymous> J 1 0.06 0.01 98.3 16.9 0.01
GetJSSystemInfoForSystem N 1 0.00 0.00 8.5 8.5 0.00
OOJSNativeObjectFromJSObject N 4 0.00 0.00 6.8 6.8 0.00
SystemStaticInfoForSystem N 1 0.01 0.00 10.2 1.7 0.00
OOStringFromJSString N 4 0.00 0.00 1.7 1.7 0.00
GlobalGetProperty N 1 0.00 0.00 1.7 1.7 0.00
-[NSString(OOJavaScriptExtensions) oo:jsValueInContext:] N 1 0.00 0.00 0.0 0.0 0.00
The table contains the trace of the calls, with separate metrics for each one of them, as well as their type (J for Javascript, N for Native).

You may want to copy the result to the editor with a monospace font if the columns don't appear to be aligned.

'''Note:''' while profile() is running, the time limiter is effectively disabled (specifically, it's set to ten million seconds).

==== <code>getProfile</code> ====
function '''getProfile'''(func : function [, this : Object]) : Object
Like <code>profile()</code>, but returns an object, which is more amenable to processing in scripts. To see the structure of the object, run:
console.getProfile(function(){PS.position.add([0, 0, 0])})



=== The console script ===
While an external or integrated console is required to provide a means of user interaction, most of the actual behaviour of the console is implemented in JavaScript, in a script called ''oolite-debug-console.js''. Input typed into the console is passed to the console script, which then generates output. The console script is also informed of log messages and JavaScript errors, and provides a global function, <code>ConsoleMessage(colorCode: String, message: String)</code>, to write messages to the console using its background colour support. Lastly, the console script implements the entire macro system.

This means that the console’s behaviour can be extensively customized, for instance, by replacing the macro system with something more powerful. There are two basic approaches to doing this:
* Creating a custom script (or a copy) with the same name, in an OXP which loads later than Debug.oxp (e.g., one which has a name which comes later in alphabetical order).
* Using a normal world script, and changing the console script object at startup.
The latter approach has the advantage that it can continue to work with future versions of the console script, and multiple patches can coexist. For example, a modification to supplement the macro system with a better one might look as follows:
this.name = "my-super-console-macros"

this.startUp = function()
{
// Ensure debug console is installed
if (!debugConsole) return

// Save original implementation of consolePerformJSCommand
// Note the prefix, used to ensure uniqueness. If several scripts patch
// the same method, it's important that they use different names.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand = debugConsole.consolePerformJSCommand

// Replace debugConsole.consolePerformJSCommand with custom function
debugConsole.consolePerformJSCommand = function(command)
{
// Note that in this function "this" will refer to debugconsole, not
// my-super-console-macros, since the function will be called as a
// method of debugConsole.

// Strip leading spaces, same code as original function.
while (command.charAt(0) == " ")
{
command = command.substring(1)
}

if (command.charAt(0) == "!")
{
// Super macro call detected.
// Insert super macro system here.
}
else
{
// Otherwise, call through to original method.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand(command)
}
}
}
This same patching technique, incidentally, can be used to modify scripts at runtime, either from the console or from other scripts.

== Links ==
* [http://www.aegidian.org/bb/viewtopic.php?f=3&t=20965 How do I? .... (on Debug Console)] (2021) - change system, change ship... - 2 pages

* Debug console issues: [http://www.aegidian.org/bb/viewtopic.php?f=10&t=20877 Problem with external debug console on Mac] (2021+)
* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=20512 (WIP) new GUI for debug console] (CAG 2020) - an improved Debug console - see below
* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=20512 Debug Console] for Python and Windows (CAG 2020)
* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=17731 Some Tips] on using the Debug Console (2015) - 1 page
* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=12030 Hints and tips for using the debug console] (2012) - 5 pages
* [http://aegidian.org/bb/viewtopic.php?f=9&t=12779 Handy tip for starting the Debug Console in Linux] (2012)

{{misc-OXP}}
[[Category:Oolite utilities]]
[[Category:Oolite scripting]]

Debug OXP

2023-05-26T16:59:09Z

Alnivel: /* Console Properties */ Rearranged and formatted section

If you are developing OXPs, the Debug Console is a tool that you should keep handy at all times, because it enables you to test things that normally are either impossible to test without it, or require substantial effort to generate the right conditions for testing. '''Debug.oxp''' enables JavaScript console support in Oolite (1.70 and later). It also adds a menu with various debug facilities under Mac OS X.

'''To run this OXP you need the [http://www.oolite.org/download/ ''OXP Developer release''] version of Oolite.''' There are subtle differences between the versions for each of the three platforms (AppleMac, Windows & Linux).

=== Downloads ===
[[Media:Basic-debug.oxz|Basic-Debug OXZ for Oolite v1.83/84]]

== External JavaScript console support ==
On all platforms, installing Debug.oxp enables support for external console applications using the [[Oolite debug console TCP protocol]]. By default, it will attempt to connect to a console running on the same computer, but this can be changed by specifying a different <code>console-host</code> (and, optionally, <code>console-port</code>) in ''debugConfig.plist''. For external console support on the same computer under Mac OS X, <code>console-host</code> must be explicitly set to “127.0.0.1”; if this is not done, the [[#Integrated JavaScript console|integrated JavaScript console]] will be used instead. For information on using a console (integrated or external), see [[#Using the JavaScript console|Using the JavaScript console]] below.

'''Note:''' A cross-platform, python based, external console application is available in the [https://github.com/OoliteProject/oolite-debug-console/releases/download/v1.5/OoDebugConsole1.5.zip Oolite GitHub project] area.

It contains a precompiled console for windows based computers, and the original python based console for Linux and Posix compliant computers.

On Debian or Ubuntu Linux you will need python 2.6.x installed and (at least) the packages <code>blt python-tk tk8.5</code> (or the equivalents in other distros.)

== Mac OS X-specific features ==
Under Mac OS X, the Debug OXP provides a menu with various debugging options and an integrated JavaScript console, as well as enabling external console support as on all platforms. This was originally written by [http://www.aegidian.org/bb/viewtopic.php?f=8&t=3661 Jens Ayton/Ahruman] for version 1.69 (TR) back in 2007. To use this you need the '''Debug OXP''' in your AddOns folder ''and'' the '''Test Release''' version of Oolite.

=== Debug menu (Mac OS X only) ===
[[Image:Oolite-debug-menu.png|494px]]

The Debug menu provides options to
* Show the Oolite run log in the standard [[OXP_howto#OXP_Verifier|Console]] application.
* Enable or disable various classes of log message at runtime (like editing ''logcontrol.plist'', without the need to restart Oolite).
* Enable various testing features, such as drawing of bounding boxes.
* Show the JavaScript console, and specify when it should be shown automatically. (This may not have any effect with external consoles, depending on the external console implementation.)
* Create a ship of any role near the main station (equivalent to the <code>:spawn</code> [[#Macros|macro]]).
Note: some of these features are implemented by sending JavaScript messages to the [[#The console script|console script]]. If the script has been modified, some features may not work properly.

The Log Message Classes submenu can be modified by editing ''debugLogMessageClassesMenu.plist'', found inside the OXP. This is merged from Config directories in the usual fashion.

=== Integrated JavaScript console (Mac OS X only) ===
[[Image:Oolite debug protocol example 1.png|594px]]

The integrated JavaScript console provides a window within Oolite which acts as a [[#Using the JavaScript console|JavaScript console]]. It can be shown using the Show JavaScript Console command in the Debug menu, unless external console mode has been enabled by setting <code>console-host</code> in ''debugConfig.plist''.

The integrated console has a 100-line memory. To see previous commands, press ⇞ (Page Up) or ⌥↑ (Option-Up Arrow). You can go the other way in the obvious manner.

== Using the JavaScript console ==
The JavaScript console, whether integrated or external, provides a powerful mechanism for interactively manipulating the game world. It can be used to issue simple commands, like <code>player.ship.awardEquipment("EQ_FUEL_INJECTION")</code>. It can be used to inspect properties of entities in the game world. And it can be used to develop scripts, by rewriting and testing methods of live ship scripts and world scripts.

=== Macros ===
Macros are a special type of command prefixed with a colon. Instead of being interpreted as a JavaScript command, a macro is looked up in a dictionary, and the result is used as the “real” command. For instance, if you enter the command <code>:listM</code> (short for “list macros”), the macro dictionary is queried for the string “listM”, and (by default) the code <code>for (let prop in macros) { ConsoleMessage('macro-list', ':' + prop) }</code> is found and executed. This code is called the ''expansion'' of the macro. The result is a list of macros being printed:
:clr
:clear
:spawn
:bgColor
:showM
:rmFgColor
::
:d
:ds
:listM
:setM
:delM
:fgColor
:rmBgColor
:resetM

As you can see in the example, To see the expansion of a macro without executing it, use <code>:showM</code>:
> :showM :delM
:delM = deleteMacro(PARAM)

When a macro with the word <code>PARAM</code> is executed, <code>PARAM</code> is replaced with any text following the macro name, surrounded in quotation marks. This is how <code>:showM</code> functions, for example; the string “:showM :delM” is expanded to “showMacro(":delM")”, causing the JavaScript function <code>showMacro()</code>, which is part of the [[#The console script|console script]], to be called. You can see the implementation of <code>showMacro()</code> by entering <code>showMacro</code> – without any parentheses – into the console.

An initial set of macros is loaded from ''debugConfig.plist''. If you edit any macros, using <code>:setM</code> or <code>:delM</code>, all macros are saved in Oolite’s preferences from that point forwards. This means that you don’t have to re-enter any macros you write with <code>:setM</code> after restarting Oolite.

The following example creates a simple :msg macro:
> :setM msg ConsoleMessage(' ',PARAM)
If you then type:
> :msg Hello World
The macro will be expanded, and you'll see “Hello World” on the console. However, macros are not functions, so you cannot use macros in the middle of javascript, or as part of another macro.

=== Console Properties ===

The <code>console</code> object has several properties. To see the full list of them check <code>oolite-debug-console.js</code> inside your copy of the Debug OXP.

==== Debug Flags ====
'''debugFlags''' : Number (integer, read/write)
An integer bit mask specifying various debug options. Note that the flags vary between builds.
The current flags can be seen in OODebugFlags.h in the Oolite source code, for instance at:
https://github.com/OoliteProject/oolite/blob/master/src/Core/Debug/OODebugFlags.h

DEBUG_LINKED_LISTS = 0x00000001
DEBUG_COLLISIONS = 0x00000004
DEBUG_DOCKING = 0x00000008
DEBUG_OCTREE_LOGGING = 0x00000010
DEBUG_BOUNDING_BOXES = 0x00000040
DEBUG_OCTREE_DRAW = 0x00000080
DEBUG_DRAW_NORMALS = 0x00000100
DEBUG_NO_DUST = 0x00000200
DEBUG_NO_SHADER_FALLBACK = 0x00000400
DEBUG_SHADER_VALIDATION = 0x00000800
DEBUG_MISC = 0x10000000

To set flags, you can use either numeric literals directly or symbolic names as properties of the console object. For example, to toggle rendering of bounding boxes and surface normals, you might use:
console.debugFlags ^= console.DEBUG_BOUNDING_BOXES;
console.debugFlags ^= console.DEBUG_DRAW_NORMALS;

This will work as well:
console.debugFlags ^= 0x00000040;
console.debugFlags ^= 0x00000100;

To disable everything just set it to zero:
console.debugFlags = 0

==== Shaders ====
'''shaderMode''' : String (read/write)
A string specifying the current shader mode. One of the following:
* "SHADERS_NOT_SUPPORTED"
* "SHADERS_OFF"
* "SHADERS_SIMPLE"
* "SHADERS_FULL"
If it is SHADERS_NOT_SUPPORTED, it cannot be set to any other value. If it is not SHADERS_NOT_SUPPORTED, it can be set to SHADERS_OFF, SHADERS_SIMPLE or SHADERS_FULL, unless maximumShaderMode (see below) is SHADERS_SIMPLE, in which case SHADERS_FULL is not allowed.

'''Note:''' this is equivalent to <code>[[Oolite JavaScript Reference: Oolite#gameSettings|oolite.gameSettings]].shaderEffectsLevel</code>, which is available even when the debug console is not active, but is read-only.

'''maximumShaderMode''' : String (read-only)
A string specifying the fanciest available shader mode. One of the following:
* "SHADERS_NOT_SUPPORTED"
* "SHADERS_SIMPLE"
* "SHADERS_FULL"

'''reducedDetailMode''': Boolean (read/write)
Whether reduced detail mode is in effect (simplifies graphics in various ways).

'''glVendorString''' : String (read-only)

'''glRendererString''' : String (read-only)
Information about the OpenGL renderer.

==== Error Logging ====
'''dumpStackForErrors''' : Boolean (read/write)
If <code>true</code>, when an error or exception is reported a stack trace will be written to the log (if possible). Ignored if not showing error locations.

'''dumpStackForWarnings''' : Boolean (read/write)
If <code>true</code>, when a warning is reported a stack trace will be written to the log (if possible). Ignored if not showing error locations.

'''showErrorLocations''' : Boolean (read/write)
<code>true</code> if file and line should be shown when reporting JavaScript errors and warnings. Default: <code>true</code>.

'''showErrorLocationsDuringConsoleEval''': Boolean (read/write)
Override value for showErrorLocations used while evaluating code entered in the console. Default: <code>false</code>. (This information is generally not useful for code passed to eval().)

==== Miscellaneous ====
'''displayFPS''': Boolean (read/write)
Boolean specifying whether FPS (and associated information) should be displayed.

'''platformDescription''' : String (read-only)
Information about the system Oolite is running on. The format of this string is not guaranteed, do not attempt to parse it.

'''settings''' : Object
A key-value store that is saved persistently. Values from debugConfig.plist are used as defaults, and any changed values are stored with the game’s preferences.

'''ignoreDroppedPackets''' : Boolean (read/write)
If <code>true</code> the TCP console will try to stay connected, ignoring dropped TCP packets, if <code>false</code> - will disconnect if an error affects.



=== The console script ===
While an external or integrated console is required to provide a means of user interaction, most of the actual behaviour of the console is implemented in JavaScript, in a script called ''oolite-debug-console.js''. Input typed into the console is passed to the console script, which then generates output. The console script is also informed of log messages and JavaScript errors, and provides a global function, <code>ConsoleMessage(colorCode: String, message: String)</code>, to write messages to the console using its background colour support. Lastly, the console script implements the entire macro system.

This means that the console’s behaviour can be extensively customized, for instance, by replacing the macro system with something more powerful. There are two basic approaches to doing this:
* Creating a custom script (or a copy) with the same name, in an OXP which loads later than Debug.oxp (e.g., one which has a name which comes later in alphabetical order).
* Using a normal world script, and changing the console script object at startup.
The latter approach has the advantage that it can continue to work with future versions of the console script, and multiple patches can coexist. For example, a modification to supplement the macro system with a better one might look as follows:
this.name = "my-super-console-macros"

this.startUp = function()
{
// Ensure debug console is installed
if (!debugConsole) return

// Save original implementation of consolePerformJSCommand
// Note the prefix, used to ensure uniqueness. If several scripts patch
// the same method, it's important that they use different names.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand = debugConsole.consolePerformJSCommand

// Replace debugConsole.consolePerformJSCommand with custom function
debugConsole.consolePerformJSCommand = function(command)
{
// Note that in this function "this" will refer to debugconsole, not
// my-super-console-macros, since the function will be called as a
// method of debugConsole.

// Strip leading spaces, same code as original function.
while (command.charAt(0) == " ")
{
command = command.substring(1)
}

if (command.charAt(0) == "!")
{
// Super macro call detected.
// Insert super macro system here.
}
else
{
// Otherwise, call through to original method.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand(command)
}
}
}
This same patching technique, incidentally, can be used to modify scripts at runtime, either from the console or from other scripts.

== Links ==
* [http://www.aegidian.org/bb/viewtopic.php?f=3&t=20965 How do I? .... (on Debug Console)] (2021) - change system, change ship... - 2 pages

* Debug console issues: [http://www.aegidian.org/bb/viewtopic.php?f=10&t=20877 Problem with external debug console on Mac] (2021+)
* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=20512 (WIP) new GUI for debug console] (CAG 2020) - an improved Debug console - see below
* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=20512 Debug Console] for Python and Windows (CAG 2020)
* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=17731 Some Tips] on using the Debug Console (2015) - 1 page
* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=12030 Hints and tips for using the debug console] (2012) - 5 pages
* [http://aegidian.org/bb/viewtopic.php?f=9&t=12779 Handy tip for starting the Debug Console in Linux] (2012)

{{misc-OXP}}
[[Category:Oolite utilities]]
[[Category:Oolite scripting]]

Planetinfo.plist

2023-05-05T00:45:14Z

Alnivel: /* Properties of the Planet */ Added illumination_color and minor tweaks

'''planetinfo.[[plist]]''' in 'AddOns/Config' contains a dictionary for each of systems for which you wish to set custom data. A list of all galaxies and planets can be found [[Oolite planet list|here]]. Each of the properties mentioned below can be set (but, notably, not the location of the main planet, which is hard coded into the system seed value):

=== Added for Oolite v.1.91 ===
*air_density / or the Javascript planet entity airDensity - see below (pretty picture!)

=== Added for Oolite v.1.89 ===
This needs editing by somebody who understands it! Snatched from the Progress thread
*[http://aegidian.org/bb/viewtopic.php?p=270737#p270737 air_color] now produces the right color for the sky. Not only that, it is now used as the atmosphere scatter color when the planet is viewed from space. Non-blue atmospheres are finally possible!
*[http://aegidian.org/bb/viewtopic.php?p=270771#p270771 air_color_mix_ratio]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 terminator_threshold_vector shipdata key]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 JSPlanet terminatorThresholdVector property]
*[http://aegidian.org/bb/viewtopic.php?p=269833#p269833 MULTIPLIER_LIGHTSRCRADIANCE and MULITPLIER_EXPOSURE]: Planet, ships and atmosphere shaders can now define lightsource radiance and scene exposure multipliers
*Also stuff about city lights
*And probably other stuff I missed!

=Where Settings Apply=

==Universal Settings==

Some options can be applied to the entire universe, such as ambient lighting levels, eg.
"universal" =
{
...
}
Universal options can be over-ridden by specifying the same option for a specific system or location in interstellar space. Obviously, not all options make sense to apply to the whole universe.

==Interstellar Space==

Conditions for interstellar space in general can be set with the “interstellar space” key.

==Specific Systems==

Each system is keyed by a string consisting of the galaxy number (0..7) followed by a space and then the planet number (0..255), eg.
"0 7" =
{
...
}
specifies system 7, in galaxy 0, ''Lave''.

==Specific Interstellar Spaces==

You can also specify a position in interstellar space, eg.
"interstellar: 0 7 129" =
{
...
}
specifies the space in galaxy 0 between systems 7 and 129, ''Lave'' and ''Zaonce''.

In 1.81 the property "link_color" when set on a specific interstellar space changes the colour of the link between the two systems in the advanced navigation array (assuming no route is in place above it).

Note that
"interstellar: 0 7 129" = // jumping from Lave towards Zaonce
{
...
}
and
"interstellar: 0 129 7" = // jumping from Zaonce towards Lave
{
...
}
are distinct locations and if they both need the same properties this must be explicitly set for both. When setting link_color, the lower system ID must be placed first, because of how the chart is drawn.

==Layers==

Settings other than "universal" in Oolite 1.81 or later have a 'layer' property from 0 to 3. The default value for planetinfo.plist files is 1. If multiple OXPs specify a setting for a particular property, the order they will be checked in is:
* Layer 3 settings
* Layer 2 settings (default for Javascript changes to data)
* Layer 1 settings (default for planetinfo.plist)
* Universal settings
* Layer 0 settings (value for core game settings)

This allows OXPs to safely override each other's changes if necessary, and for OXPs which really need a specific setting in a particular system to set it at layer 3

Example
"layer" = 2;

==Terraforming Example==

For the planet Lave, you would use the key '0 7' (planet 7 in galaxy 0) Then you set the values. The following example sets Lave's sea to blue, land to green, and land to sea ratio to 75%.

Code:
{
"0 7" =
{
"percent_land" = "75";
"land_color" = "0.5 1.0 0.5";
"sea_color" = "0.3 0.7 1.0";
}
}

Then you can override any of the settings listed above, for example to change Zaatxe's (Galaxy 0 Planet 8) inhabitants into blue frogs you'd enter

Code:
"0 8" =
{
"inhabitants" = "Blue Frogs";
}

You can use any or all of the keys in each of the entries. It's probably best to only use the key's you want to change. So, another example, to change the sky_blur_xxx settings for Zaonce (Galaxy 0 Planet 129) to big, heavily clustered, but pale blurs - you'd enter

Code:
"0 129" =
{
"sky_blur_cluster_chance" = "0.9";
"sky_blur_alpha" = "0.1";
"sky_blur_scale" = "32.0";
}

=About the Inhabitants=

==Concealment==
{{oolite-prop-added|1.83}}

An integer that determines how much information about the system is unknown.

Example:
"concealment" = "300";
The following values are recognised:
* 0: default, all information visible
* 100 or more: F7 screen shows no information, economy/government/TL/star colour not visible on chart
* 200 or more: system name is not shown
* 300 or more: system vanishes entirely from chart, will not be used in route plotting, cannot be targeted by player (NPCs can still jump to it, though)

==Government==

An integer between 0 and 7 indicating the government type of the system.

Example:
"goverment" = "7";

Possible values:
: 0: Anarchy
: 1: Feudal
: 2: Multi-Governmental
: 3: Dictatorship
: 4: Communist
: 5: Confederacy
: 6: Democracy
: 7: Corporate State

==Economy==
An integer between 0 and 7 indicating the economy type of the system.

Example:
"economy" = "5";

Possible values:
: 0: Rich Industrial
: 1: Average Industrial
: 2: Poor Industrial
: 3: Mainly Industrial
: 4: Mainly Agricultural
: 5: Rich Agricultural
: 6: Average Agricultural
: 7: Poor Agricultural

==Tech Level==

An integer between 0 and 14 indicating the sophistication of the planets technology. The tech level displayed on the system data screens in game is one higher than this number (range 1 to 15).

Example:
"techlevel" = "13";

==Population==

An integer between 0 and 67 indicating the number of inhabitants of a planet in hundreds of millions

Example:
"population" = "23";

==Productivity==

An integer indicating the productivity of a planet.

Example:
"productivity" = "1000";

==Name==

The name of the planet.

Example:
"name" = "The planet's name";

==Inhabitant==

The name for one of the inhabitants of the main planet.

Example:
"inhabitant" = "Green Platypus";

==Inhabitants==

The name of the inhabitants of the main planet.

Example:
"inhabitants" = "Green Platypi";

==Description==

A short description of the planet.

Example:
"description" = "Really, anything you want to say about the place!";

==Government Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the government.

Example:
"government_description" = "Dictatorship (Monarchy)";

==Economy Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the economy.

Example:
"economy_description" = "Mainly Industrial (Machine Tools)";

==Population Description==
{{oolite-prop-added|1.77}}

Overrides the default text used to describe the population.

Example:
"population_description" = "13 Billion";

==Random Seed==
{{oolite-prop-added|1.81}}

A seed for a random number generator used in Oolite 1.81 to generate system properties impractical to store in this file (e.g. the positions of each star on the background starfield)

For historical reasons, this is a string of 6 integers between 0 and 255, for example:
random_seed = "74 90 72 2 83 183";

=System population=
These properties are only used in Oolite 1.79 or later.

==Populator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|populate the system]]

Example:
"populator" = "systemWillPopulate";

==Repopulator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|repopulate the system]]

Example:
"repopulator" = "systemWillRepopulate";

=Properties of the Planet=

Most of these properties are ignored if a planet texture is set.

Note that the available planet texture generator properties changed in places between Oolite 1.77 and Oolite 1.80

==Air Color==
A colour specifier determining the color of the planet's sky, as well as the atmosphere scatter color.

Example:
"air_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Air Color Mix Ratio==
{{oolite-prop-added|1.89}}

The amount of air color that be mixed in the overall atmosphere color. A number from 0.0 to 1.0 (default 0.5).

Example:
"air_color_mix_ratio" = "0.0..1.0";

==Atmosphere Rotational Velocity==

Sets how fast the atmosphere is rotating. (A random value between 0.0 to 0.03 is the default).

Example:
"atmosphere_rotational_velocity" = "0.1";

==Cloud Alpha==
{{oolite-prop-added|1.77}}

The transparency level of the cloud layer, relative to the standard transparency. 1.0 is the default. Texture packs which include clouds on the planetary texture may wish to reduce this.

Example:
"cloud_alpha" = "0.2";

==Has Atmosphere==
{{oolite-prop-added|1.81}}

This boolean property is used for the main planet only. If it is unset or true, the main planet has an atmosphere, as is always the case in 1.80 and before. If it is set to be false, then the planet will not have an atmosphere.

Example:
"has_atmosphere" = 0;

This has no effect on secondary planets - their atmosphere is determined by whether addition uses <code>addPlanet</code> or <code>addMoon</code>.

[[File:AtmDensityExample.png|thumb|320px|right|Atmosphere Density examples: Stranger's ''FPO Lave'' in four increasing atmosphere densities: 0.2, 0.5, 0.75 and 1.0. Every other parameter in the planet definition is the same in all pictures.]]
== Air Density ==
{{oolite-prop-added|1.91}}

A number clamped in range from 0.0 to 1.0 describing the density of the planet's atmosphere. All planets in the core use 0.75 as default.

Example:
"air_density" = "0.0..1.0";

==Illumination Color==
{{oolite-prop-added|1.91}}

A colour specifier determining the colour of the planet's illumination such as cities light. Illumination is inserted as a grayscale map in the alpha channel of the planet's diffuse texture. You can specify this key even if no illumination map is defined, but it won't have any effect - without an illumination map the dark side of the planet remains dark in all cases.

Example:
"illumination_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Land Color==

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Percent Cloud==
The percentage of the planet's atmosphere occupied by clouds.

Example:
"percent_cloud" = "0..100";

Note that with a low cloud_alpha setting not all of the clouds defined here may actually be visible

==Percent Ice==
The percentage of the planet occupied by the polar ice caps. Oolite 1.81 or later.

Example:
"percent_ice" = "0..100";

==Percent Land==
The percentage of the planet occupied by land.

Example:
"percent_land" = "0..100";

==Planet Distance==
{{oolite-prop-added|1.81}}

The distance from the centre of the planet to the witchpoint. Only used for the system main planet - secondary planets are positioned separately.

Example
"planet_distance" = "410000";

The main planet is always positioned on the z-axis.

==Planet Name==
{{oolite-prop-added|1.79}}

The planet's name. For the main planet, this defaults to being the same as the system name - the property is mainly intended for secondary planets.

Example
"planet_name" = "Earth";

==Polar Land Color==
{{oolite-prop-added|1.81}}

Sets the land colour in polar regions.

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Polar Sea Color==
{{oolite-prop-added|1.81}}

Sets the sea colour in polar regions.

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Radius==
An integer between 3000 and 7000 indicating the radius of the main planet. On the F7 screen, this is measured in kilometres. The radius in game is 1/100th of this.

Example:
"radius" = "5500";

==Rotational Velocity==
A number describing the rotational velocity of the planet in radians per second. Overrides rotation_speed if both are set.

Example:
"rotational_velocity" = 0.0015;

==Rotation Speed==
A number describing the rotational velocity of the planet in radians per second. Unlike rotational_velocity, this is affected by rotation_speed_factor.

Example:
"rotation_speed" = 0.0015;

==Rotation Speed Factor==
The rotational speed of all planets whose rotational speed was set by rotation_speed and not by rotational_velocity will be multiplied by this number.

Example:
"rotation_speed_factor" = 1.0;

(Intended more for the universal section as a "personal taste" option than for individual planets)

==Sea Color==

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Terminator Threshold Vector==
{{oolite-prop-added|1.89}}

This property gives control over the color of the planet's terminator. The way the property works is not entirely straightforward, so see [http://aegidian.org/bb/viewtopic.php?p=271058#p271058 this post on BB] for more information.

Example:
"terminator_threshold_vector" = "0.0..1.0 0.0..1.0 0.0..1.0";
By default the terminator vector is "0.105 0.18 0.28" - which results in a reddish orange colour.

==Texture==
The replacement texture to be used by a system's main planet.<br>

For textures you can use lat-long maps (twice as wide as high) with a special elongation at the poles or cube maps. Other maps also will be wraped around planets but give always distortions.<br>
Since Oolite 1.74 you can also use cube maps for planets. Cube maps are 6 times higher as wide and will be recognised automatic by Oolite, based on its dimensions. Cube maps are the preferred method because lat-long give some distortion and have the poles improperly placed in Oolites implementation. See also [[Planettool]] for conversion from lat-long into cube maps.

From Oolite 1.89 onwards, illumination mapping on custom planets is supported. The illumination map goes in the diffuse map's alpha channel. Low alpha values translate to high illumination. This allows for effects like city lights on a planet's dark side.

Example:
"texture" = "newPlanetTexture.png";
;N.B.
The illumination mapping feature is disabled by setting ''Graphics Detail: Shaders Enabled'' or lower in the game setting menu. ''Enabled'' at ''Graphics Detail: Extra Detail''.

==Texture HSB Color==
This changes the overall hue of the replacement texture.

Example:
"texture_hsb_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Texture NormSpec==
{{oolite-prop-added|1.89}}

The external texture that will be used as a normal and specular map for the given planet. Colorspace should be linear, with the normal map in the r,g and b and the specular map in the a channel. The texture can be of either equirectangular or cubemap formats. This feature is available at the Extra Detail setting only. To set:
"texture_normspec" = "planetNormalAndSpecularMap.png";

=Properties of the Sky=

==Ambient Level==

Sets how much ambient light (shed by stars and nebulae) illuminates the dark side of objects like planets and ships. Values should typically be between 0.0 and 1.0 (1.0 is the default) but can be higher for a flat lit, cartoon-like effect.

Example:
"ambient_level" = "0.0";

==Nebula Count Multiplier==
This is used for defining the number of nebulas. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"nebula_count_multiplier" = "1.5";

==Sky Blur Alpha==
Default 0.1

Example:
"sky_blur_alpha" = "0.0 .. 1.0";

==Sky Blur Cluster Chance==
This is used for creating nebulae (typically 0.80)

Example:
"sky_blur_cluster_chance" = "0.85";

==Sky Blur Scale==
Default 10. Larger numbers generate bigger nebula, but slow down the game considerable on slower machines.

Example:
"sky_blur_scale" = "0.0 .. 128.0 or more";

==Sky N Blurs==
This is used for defining the number of nebulas (typical is 80, maximum is 1280). This key is multiplied by a "nebula_count_multiplier" definition in Oolite 1.81 or later.

Example:
"sky_n_blurs" = "800";

==Sky N Stars==
This is used for defining the number of stars (typical = 600, maximum in 1.76 or earlier is 4800). This key is multiplied by a "star_count_multiplier" definition in Oolite 1.81 or later. In reduced detail mode, this number will be capped to 2400.

Example:
"sky_n_stars" = "1200";

==Sky and Nebula RGB Colors==

These are rgb values (from 0.0 to 1.0) for the two colours between which the colour of the stars (and nebulaesque blurs) vary, ordered r1 g1 b1 r2 g2 b2 where (r1 g1 b1) defines the first colour and (r2 g2 b2) the second.<br>
(Default values are "0.75 0.8 1.0 1.0 0.85 0.6")

Example:
"sky_rgb_colors" = "0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0";

Alternatively, two [[Materials in Oolite#Colour specifiers|colour specifiers]] may be used:
"sky_color_1" = "redColor";
"sky_color_2" =
{
"hue" = "60";
"brightness" = "0.8";
}

"nebula_color_1" = "greenColor";
"nebula_color_2" = "blueColor";

==Star Count Multiplier==
This is used for defining the number of stars. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"star_count_multiplier" = "0.5";

=Properties of the Station=

==Market==
The market to be used in this system as the default market. It points to a key in commodities.plist

Example:
"market" = "rockhermit";
Will use the rockhermit market as default for for all stations in the system. When no market is defined a key in commodities.plist is used that matches the role of the main station. Than that is not defined, the default market is used in this system.

In 1.81 and later, this is replaced by market_script

==market_script==
{{oolite-prop-added|1.81}}

A Javascript file used to load a [[Oolite Market Scripts|market script]] for global system price and quantity modifications.

"market_script" = "myoxp_newsystemmarket.js";

==Station==
The type of station orbiting the main planet.

Example:
"station" = "coriolis..dodec..special";

==Station Roll==
The speed at which the station rotates (as with all rotational velocities this is in radians per second) and affects all rotating stations in a system. For a specific station you can use the key [[Shipdata.plist#station_roll | station_roll]] in shipdata.plist.

Example:
"station_roll" = "0.5";

==Station Vector==
The direction of the main station from the main planet

Example:
"station_vector" = "-0.717 -0.668 0.201";

==Stations Require Docking Clearance==

Specifies if a player has to explicit ask docking permission. See also [[Oolite_Docking_Clearance_Protocol_%28v1.72_or_later%29|Oolite Docking Clearance]]

=Properties of the Sun=
;N.B.
The corona effect, modified by the first three properties mentioned below, is disabled by setting ''Reduced Detail:On'' in the game setting menu. ''Enabled'' by default (''Reduced Detail:Off'').

==Corona Flare==

Sets the overall size of the corona in proportion to its sun. (See note above.)

A number from 0.0 (invisibly small) to 1.0 (huge)

Example:
"corona_flare" = "0.075";

==Corona Hues==

Specifies whether the corona should have visible bands of colours within the corona. (See note above.)

A number from 0.0 (monochromatic) to 1.0 (vivid alternating colours).

Example:
"corona_hues" = "0.6";

==Corona Shimmer==

Specifies how quickly the corona colours change. (See note above.)

A number from 0.0 (very slow) to 1.0 (very fast).

Example:
"corona_shimmer" = "0.4";

==Sun Color==

Sets the colour of a system's sun.

Can be any [[Materials in Oolite#Colour specifiers|colour specifier]] or [[Materials in Oolite#Named colours|named colour]]. The specified colour is blended with 50% white so it will never be a saturated colour. Dark colours will be brightened by this blending.

Example:
"sun_color" = "blueColor";

==Sun Distance==
{{oolite-prop-added|1.81}}

Sets the distance between the sun and the main planet in metres.

Example:
"sun_distance" = 924122;

Ignored if sun_distance_modifier is set.

==Sun Distance Multiplier==
{{oolite-prop-added|1.81}}

Multiplies the distance between the sun and the main planet by this factor.

Example:
"sun_distance_multiplier" = 2;

Ignored if sun_distance_modifier is set.

==Sun Distance Modifier==

Sets the approximate distance between a system sun and its main planet. The standard distance is 20 planetary radii. Setting it much lower (10, or even less) will cause delays when generating systems, as Oolite compensates for possible collisions between the sun and other system objects.

Example:
"sun_distance_modifier" = "15.0";

In Oolite 1.81 or later, sun_distance_multiplier is more useful.

== Sun Gone Nova ==

Sets a nova sun in the system.

Example:
"sun_gone_nova" = "YES";

==Sun Name==

Stores the name of a system's sun. This is only implemented in Oolite from version 1.79 onwards, though was used by OXPs before then.

Example:
"sun_name" = "Alpha Centauri";

==Sun Radius==

Sets the radius of a system's sun. A number between 1000 and 1000000.

Example:
"sun_radius" = "100000";

==Sun Vector==
The direction of the sun from the main planet

Example:
"sun_vector" = "-0.717 -0.668 0.201";

=Hyperspace Travel=

In Oolite 1.81 and later these properties have been moved into [[global-settings.plist]]

==Galactic Hyperspace Behaviour==

The key galactic_hyperspace_behaviour controls where the player will arrive after a G.H. has been executed. There are three possible types of G.H. behavior and are as follows:

1) Oolite standard. This is what we have up to this moment. Executing a G.H. jump will poisition the player in the next galaxy, to the closest non-isolated system with regards to their current galaxy coordinates. So, for example, if you jump from coordinates (100, 50) in galaxy 1 you will arrive in galaxy 2 at the same coordinates, unless these coordinates refer to an unreachable system, in which case the arrival point will be adjusted by the engine to maybe something like (102, 51). This is set as default behavior. It is set by assigning the string BEHAVIOUR_STANDARD to the galactic_hyperspace_behaviour key.

2) All systems reachable. Same as above, only this time we do not check for arrival at an isolated system. Using this method, systems like Oresrati in G8, the lower left hand cluster of systems in G7, the two islands of isolated systems in G6 etc. are now possible arrival points. If you land there, you may not be able to exit again, depending on the tech levels of the systems you get to. Mission scripters may want to use this. This behaviour is set by assigning the string BEHAVIOUR_ALL_SYSTEMS_REACHABLE to galactic_hyperspace_behaviour key in planetinfo.plist.

3) Fixed coordinates arrival point. This will make Oolite simulate some older 8-bit versions, that were putting the player in the same fixed point every time a galactic jump was performed, but there is also good potential for scripting (see below). This is set by assigning the string BEHAVIOUR_FIXED_COORDINATES to the galactic_hyperspace_behaviour key.

==Galactic Hyperspace Fixed Coords==

If the fixed coordinates method is chosen, then the engine will look in planetinfo.plist for a key named galactic_hyperspace_fixed_coords, from which it will read the actual coordinates that will be used as the arrival point in the next galaxy. If none is found, then coordinates (96,96) will be used.

==Hyperspace Tunnel Color==

One or two colours can be set, using RGBA format, to over-ride the appearance of the hyperspace tunnel effect.
Example:

hyperspace_tunnel_color_1 = (1.0, 0.0, 0.0, 0.5);
hyperspace_tunnel_color_2 = (0.0, 0.0, 1.0, 0.25);



=Additional Planets=

Finally you can also define your own custom planets and moons:
"LavesPurpleMoon" =
{
...
}


To add them to the system, use JS methods <code>[[Oolite_JavaScript_Reference:_System#addPlanet|system.addPlanet]]</code> and <code>[[Oolite_JavaScript_Reference:_System#addPlanet|system.addMoon]]</code>. For the example above, the <code>planetInfoKey</code> will be <code>"LavesPurpleMoon"</code>.

==Position==
Position of the planet in space. The first parameter is 3-character code of the coordinate system, other three is x, y and z components of position vector.
"position" = "pwm 0 -50000 0";

You can omit the coordinate system parameter, then the absolute coordinate system will be used:
"position" = "0 -50000 0";

See [[Oolite coordinate systems]] for more info about it.

==Orientation==
Orientation of the planet in space (seems not to be working correct).

Example:
"orientation" = "0.0 1.0 0.0 0.0";

==Other keys==

You can use other keys from the [[#Properties_of_the_Planet| Properties of the Planet]] section for your planets and moons.

Here are some of the keys you may want to use:
* "radius": Radius of the planet in km. e.g. a value of 500 is drawn with a radius of 5000 meters but in player dialogues this value is presented as 500 km.
* "rotational_velocity": Rotation of the planet in rotations per second.
* "texture": The name of the texture file that is used to wrap around the surface.
* "seed": Seed value used to create the planet's surface features. If no seed is defined it uses the same seed as the main planet, and will create a copy of it.

= Links =
*[[Random number generator]] - originally used for creating planet descriptions
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=3860 seed = "1 2 3 4 5 6";]: Psuedo-random number generation & planet descriptions (2007)
*[http://aegidian.org/bb/viewtopic.php?f=4&t=3808 position = "x y z" in planetinfo.plist] (2007)
*Submersible's [https://www.youtube.com/user/submersibletoaster YouTube videos] of planet textures (2012)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=5044 Question: How to add custom planet descriptions] (2008)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20959 Empty system] Removing the stations (and presumably inhabitants) from a system (2021)

[[Category:Oolite]]
[[Category:Oolite scripting]]

Oolite JavaScript Reference: Planet

2023-05-05T00:34:08Z

Alnivel: /* Properties */ Added missing properties

<small>'''Prototype:''' <code>[[Oolite/Development/Scripting/Class/Entity|Entity]]</code></small><br />
<small>'''Subtypes:''' none</small>

The '''<code>Planet</code>''' class is an <code>[[Oolite/Development/Scripting/Class/Entity|Entity]]</code> representing a planet or moon. A <code>Planet</code> has all the properties and methods of a <code>Entity</code>, and several others.

== Properties ==
=== <code>airColor</code> ===
{{oolite-prop-added|1.89}}
'''airColor''' : Array (read/write)
The colour of the planets atmosphere. An array of RGBA components, but can be set with any other [[Materials_in_Oolite#Colour_specifiers|colour specifier]].

=== <code>airColorMixRatio</code> ===
{{oolite-prop-added|1.89}}
'''airColorMixRatio''' : Number (read/write)
The amount of air colour that be mixed in the overall atmosphere color. A number from 0.0 to 1.0.

=== <code>airDensity</code> ===
{{oolite-prop-added|1.91}}
'''airDensity''' : Number (read/write)
The density of the planet's atmosphere. A number from 0.0 to 1.0.

=== <code>hasAtmosphere</code> ===
'''hasAtmosphere''' : Boolean (read-only)
<code>true</code> if the entity has an atmosphere, <code>false</code> otherwise. Planets created with the <code>System.[[Oolite/Development/Scripting/Class/System#addMoon|addMoon]]()</code> method (or corresponding legacy scripting method) have no atmosphere, other planets do.

=== <code>illuminationColor</code> ===
{{oolite-prop-added|1.91}}
'''illuminationColor''' : Array (read/write)
The colour of the planet's illumination such as cities light. An array of RGBA components, but can be set with any other [[Materials_in_Oolite#Colour_specifiers|colour specifier]].

'''Note:''' Illumination is inserted as a grayscale map in the alpha channel of the planet's diffuse texture. If no illumination map is defined, then you can still access this property but you will not see any difference by changing it - without an illumination map the dark side of the planet remains dark in all cases.

=== <code>isMainPlanet</code> ===
'''isMainPlanet''' : Boolean (read-only)
<code>true</code> if the entity is the main planet of the current system, <code>false</code> otherwise.

'''See also''': <code>[[Oolite JavaScript Reference: System#mainPlanet|system.mainPlanet]]</code>

=== <code>name</code> ===
{{oolite-prop-added|1.79}}
'''name''' : String (read/write)
The name of the planet, as set by the <code>planet_name</code> property in [[planetinfo.plist]]

For convenience of working with secondary planets, this can be written to by JS. For the system main planet, writing to <code>system.info.planet_name</code> is preferred.

=== <code>radius</code> ===
'''radius''' : Number (read-only)
The equatorial radius of the planet, in metres.

For reference: radii of main planets generated by Oolite vary between 28160 and 69110 meters. This value is shown on the planet information screen as: 2816 km to 6911 km. (Note the discrepancy of a factor 100.)

=== <code>rotationalVelocity</code> ===
'''rotationalVelocity''' : Number (read/write)
The rotation speed of a planet. A value of x means: x/Math.PI rotations per second. The main planet default value is pseudorandom and varies between 0.0 until 0.01

=== <code>texture</code> ===
'''texture''' : String (read/write)

The name of the texture file (diffuse map) used by the planet. This may only be assigned to during the <code>shipWillExitWitchspace</code> and <code>shipWillLaunchFromStation</code> events.

=== <code>terminatorThresholdVector</code> ===
{{oolite-prop-added|1.89}}
'''terminatorThresholdVector''' : [[Oolite JavaScript Reference: Vector|Vector]] (read/write)

This property gives control over the color of the planet's terminator. The way the property works is not entirely straightforward, so see [http://aegidian.org/bb/viewtopic.php?p=271058#p271058 this post on BB] for more information.

== Non-standard Properties ==
''These are not part of the official object model, but are used in various OXPs by the authors to allow manipulation of the OXP by other scripts and expansions. '''Important:''' the use of custom properties without a unique OXP-specific prefix is '''strongly discouraged''' and may cause conflicts with future versions of Oolite.''

=== <code>solarGasGiant</code> ===
'''solarGasGiant''' : Boolean (read/write)
<code>true</code> if the entity is a gas giant and should therefore prevent attempts to land on the planet's surface, <code>false</code> otherwise. Created for the Solar System OXP and used by the [[Planetfall OXP]].

=== <code>PFNoLand</code> and <code>PFNoLandQuiet</code> ===
'''PFNoLand''' : Boolean (read/write)
'''PFNoLandQuiet''' : Boolean (read/write)
<code>true</code> if landing will be prevented on the planet's surface (with and without a warning message), <code>false</code> otherwise. Created and used by the [[Planetfall OXP]] from version 1.40 onwards.

=== <code>isGasGiant</code> ===
'''isGasGiant''' : Boolean (read/write)
<code>true</code> if the entity is a gas giant, <code>false</code> otherwise. Created and used by the [[System_Redux_(Oolite) | System Redux OXP]].

[[Category:Oolite JavaScript Reference]]

Planetinfo.plist

2023-05-04T23:45:57Z

Alnivel: /* Additional Planets */ Rearranged section

'''planetinfo.[[plist]]''' in 'AddOns/Config' contains a dictionary for each of systems for which you wish to set custom data. A list of all galaxies and planets can be found [[Oolite planet list|here]]. Each of the properties mentioned below can be set (but, notably, not the location of the main planet, which is hard coded into the system seed value):

=== Added for Oolite v.1.91 ===
*air_density / or the Javascript planet entity airDensity - see below (pretty picture!)

=== Added for Oolite v.1.89 ===
This needs editing by somebody who understands it! Snatched from the Progress thread
*[http://aegidian.org/bb/viewtopic.php?p=270737#p270737 air_color] now produces the right color for the sky. Not only that, it is now used as the atmosphere scatter color when the planet is viewed from space. Non-blue atmospheres are finally possible!
*[http://aegidian.org/bb/viewtopic.php?p=270771#p270771 air_color_mix_ratio]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 terminator_threshold_vector shipdata key]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 JSPlanet terminatorThresholdVector property]
*[http://aegidian.org/bb/viewtopic.php?p=269833#p269833 MULTIPLIER_LIGHTSRCRADIANCE and MULITPLIER_EXPOSURE]: Planet, ships and atmosphere shaders can now define lightsource radiance and scene exposure multipliers
*Also stuff about city lights
*And probably other stuff I missed!

=Where Settings Apply=

==Universal Settings==

Some options can be applied to the entire universe, such as ambient lighting levels, eg.
"universal" =
{
...
}
Universal options can be over-ridden by specifying the same option for a specific system or location in interstellar space. Obviously, not all options make sense to apply to the whole universe.

==Interstellar Space==

Conditions for interstellar space in general can be set with the “interstellar space” key.

==Specific Systems==

Each system is keyed by a string consisting of the galaxy number (0..7) followed by a space and then the planet number (0..255), eg.
"0 7" =
{
...
}
specifies system 7, in galaxy 0, ''Lave''.

==Specific Interstellar Spaces==

You can also specify a position in interstellar space, eg.
"interstellar: 0 7 129" =
{
...
}
specifies the space in galaxy 0 between systems 7 and 129, ''Lave'' and ''Zaonce''.

In 1.81 the property "link_color" when set on a specific interstellar space changes the colour of the link between the two systems in the advanced navigation array (assuming no route is in place above it).

Note that
"interstellar: 0 7 129" = // jumping from Lave towards Zaonce
{
...
}
and
"interstellar: 0 129 7" = // jumping from Zaonce towards Lave
{
...
}
are distinct locations and if they both need the same properties this must be explicitly set for both. When setting link_color, the lower system ID must be placed first, because of how the chart is drawn.

==Layers==

Settings other than "universal" in Oolite 1.81 or later have a 'layer' property from 0 to 3. The default value for planetinfo.plist files is 1. If multiple OXPs specify a setting for a particular property, the order they will be checked in is:
* Layer 3 settings
* Layer 2 settings (default for Javascript changes to data)
* Layer 1 settings (default for planetinfo.plist)
* Universal settings
* Layer 0 settings (value for core game settings)

This allows OXPs to safely override each other's changes if necessary, and for OXPs which really need a specific setting in a particular system to set it at layer 3

Example
"layer" = 2;

==Terraforming Example==

For the planet Lave, you would use the key '0 7' (planet 7 in galaxy 0) Then you set the values. The following example sets Lave's sea to blue, land to green, and land to sea ratio to 75%.

Code:
{
"0 7" =
{
"percent_land" = "75";
"land_color" = "0.5 1.0 0.5";
"sea_color" = "0.3 0.7 1.0";
}
}

Then you can override any of the settings listed above, for example to change Zaatxe's (Galaxy 0 Planet 8) inhabitants into blue frogs you'd enter

Code:
"0 8" =
{
"inhabitants" = "Blue Frogs";
}

You can use any or all of the keys in each of the entries. It's probably best to only use the key's you want to change. So, another example, to change the sky_blur_xxx settings for Zaonce (Galaxy 0 Planet 129) to big, heavily clustered, but pale blurs - you'd enter

Code:
"0 129" =
{
"sky_blur_cluster_chance" = "0.9";
"sky_blur_alpha" = "0.1";
"sky_blur_scale" = "32.0";
}

=About the Inhabitants=

==Concealment==
{{oolite-prop-added|1.83}}

An integer that determines how much information about the system is unknown.

Example:
"concealment" = "300";
The following values are recognised:
* 0: default, all information visible
* 100 or more: F7 screen shows no information, economy/government/TL/star colour not visible on chart
* 200 or more: system name is not shown
* 300 or more: system vanishes entirely from chart, will not be used in route plotting, cannot be targeted by player (NPCs can still jump to it, though)

==Government==

An integer between 0 and 7 indicating the government type of the system.

Example:
"goverment" = "7";

Possible values:
: 0: Anarchy
: 1: Feudal
: 2: Multi-Governmental
: 3: Dictatorship
: 4: Communist
: 5: Confederacy
: 6: Democracy
: 7: Corporate State

==Economy==
An integer between 0 and 7 indicating the economy type of the system.

Example:
"economy" = "5";

Possible values:
: 0: Rich Industrial
: 1: Average Industrial
: 2: Poor Industrial
: 3: Mainly Industrial
: 4: Mainly Agricultural
: 5: Rich Agricultural
: 6: Average Agricultural
: 7: Poor Agricultural

==Tech Level==

An integer between 0 and 14 indicating the sophistication of the planets technology. The tech level displayed on the system data screens in game is one higher than this number (range 1 to 15).

Example:
"techlevel" = "13";

==Population==

An integer between 0 and 67 indicating the number of inhabitants of a planet in hundreds of millions

Example:
"population" = "23";

==Productivity==

An integer indicating the productivity of a planet.

Example:
"productivity" = "1000";

==Name==

The name of the planet.

Example:
"name" = "The planet's name";

==Inhabitant==

The name for one of the inhabitants of the main planet.

Example:
"inhabitant" = "Green Platypus";

==Inhabitants==

The name of the inhabitants of the main planet.

Example:
"inhabitants" = "Green Platypi";

==Description==

A short description of the planet.

Example:
"description" = "Really, anything you want to say about the place!";

==Government Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the government.

Example:
"government_description" = "Dictatorship (Monarchy)";

==Economy Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the economy.

Example:
"economy_description" = "Mainly Industrial (Machine Tools)";

==Population Description==
{{oolite-prop-added|1.77}}

Overrides the default text used to describe the population.

Example:
"population_description" = "13 Billion";

==Random Seed==
{{oolite-prop-added|1.81}}

A seed for a random number generator used in Oolite 1.81 to generate system properties impractical to store in this file (e.g. the positions of each star on the background starfield)

For historical reasons, this is a string of 6 integers between 0 and 255, for example:
random_seed = "74 90 72 2 83 183";

=System population=
These properties are only used in Oolite 1.79 or later.

==Populator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|populate the system]]

Example:
"populator" = "systemWillPopulate";

==Repopulator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|repopulate the system]]

Example:
"repopulator" = "systemWillRepopulate";

=Properties of the Planet=

Most of these properties are ignored if a planet texture is set.

Note that the available planet texture generator properties changed in places between Oolite 1.77 and Oolite 1.80

==Air color==
A colour specifier determining the color of the planet's sky, as well as the atmosphere scatter color.

Example:
"air_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Air Color Mix Ratio==
{{oolite-prop-added|1.89}}

The amount of air color that be mixed in the overall atmosphere color. A number from 0.0 to 1.0 (default 0.5).

Example:
"air_color_mix_ratio" = "0.0..1.0";

==Atmosphere Rotational Velocity==

Sets how fast the atmosphere is rotating. (A random value between 0.0 to 0.03 is the default).

Example:
"atmosphere_rotational_velocity" = "0.1";

==Cloud Alpha==
{{oolite-prop-added|1.77}}

The transparency level of the cloud layer, relative to the standard transparency. 1.0 is the default. Texture packs which include clouds on the planetary texture may wish to reduce this.

Example:
"cloud_alpha" = "0.2";

==Has Atmosphere==
{{oolite-prop-added|1.81}}

This boolean property is used for the main planet only. If it is unset or true, the main planet has an atmosphere, as is always the case in 1.80 and before. If it is set to be false, then the planet will not have an atmosphere.

Example:
"has_atmosphere" = 0;

This has no effect on secondary planets - their atmosphere is determined by whether addition uses <code>addPlanet</code> or <code>addMoon</code>.

[[File:AtmDensityExample.png|thumb|320px|right|Atmosphere Density examples: Stranger's ''FPO Lave'' in four increasing atmosphere densities: 0.2, 0.5, 0.75 and 1.0. Every other parameter in the planet definition is the same in all pictures.]]
== Atmosphere Density ==
{{oolite-prop-added|1.91}}

A number clamped in range from 0.0 to 1.0 describing the density of the planet's atmosphere. All planets in the core use 0.75 as default.

Example:
"air_density" = "0.0..1.0";

==Land Color==

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Percent Cloud==
The percentage of the planet's atmosphere occupied by clouds.

Example:
"percent_cloud" = "0..100";

Note that with a low cloud_alpha setting not all of the clouds defined here may actually be visible

==Percent Ice==
The percentage of the planet occupied by the polar ice caps. Oolite 1.81 or later.

Example:
"percent_ice" = "0..100";

==Percent Land==
The percentage of the planet occupied by land.

Example:
"percent_land" = "0..100";

==Planet Distance==
{{oolite-prop-added|1.81}}

The distance from the centre of the planet to the witchpoint. Only used for the system main planet - secondary planets are positioned separately.

Example
"planet_distance" = "410000";

The main planet is always positioned on the z-axis.

==Planet Name==
{{oolite-prop-added|1.79}}

The planet's name. For the main planet, this defaults to being the same as the system name - the property is mainly intended for secondary planets.

Example
"planet_name" = "Earth";

==Polar Land Color==
{{oolite-prop-added|1.81}}

Sets the land colour in polar regions.

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Polar Sea Color==
{{oolite-prop-added|1.81}}

Sets the sea colour in polar regions.

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Radius==
An integer between 3000 and 7000 indicating the radius of the main planet. On the F7 screen, this is measured in kilometres. The radius in game is 1/100th of this.

Example:
"radius" = "5500";

==Rotational Velocity==
A number describing the rotational velocity of the planet in radians per second. Overrides rotation_speed if both are set.

Example:
"rotational_velocity" = 0.0015;

==Rotation Speed==
A number describing the rotational velocity of the planet in radians per second. Unlike rotational_velocity, this is affected by rotation_speed_factor.

Example:
"rotation_speed" = 0.0015;

==Rotation Speed Factor==
The rotational speed of all planets whose rotational speed was set by rotation_speed and not by rotational_velocity will be multiplied by this number.

Example:
"rotation_speed_factor" = 1.0;

(Intended more for the universal section as a "personal taste" option than for individual planets)

==Sea Color==

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Terminator Threshold Vector==
{{oolite-prop-added|1.89}}

This property gives control over the color of the planet's terminator. The way the property works is not entirely straightforward, so see [http://aegidian.org/bb/viewtopic.php?p=271058#p271058 this post on BB] for more information.

Example:
"terminator_threshold_vector" = "0.0..1.0 0.0..1.0 0.0..1.0";
By default the terminator vector is "0.105 0.18 0.28" - which results in a reddish orange colour.

==Texture==
The replacement texture to be used by a system's main planet.<br>

For textures you can use lat-long maps (twice as wide as high) with a special elongation at the poles or cube maps. Other maps also will be wraped around planets but give always distortions.<br>
Since Oolite 1.74 you can also use cube maps for planets. Cube maps are 6 times higher as wide and will be recognised automatic by Oolite, based on its dimensions. Cube maps are the preferred method because lat-long give some distortion and have the poles improperly placed in Oolites implementation. See also [[Planettool]] for conversion from lat-long into cube maps.

From Oolite 1.89 onwards, illumination mapping on custom planets is supported. The illumination map goes in the diffuse map's alpha channel. Low alpha values translate to high illumination. This allows for effects like city lights on a planet's dark side.

Example:
"texture" = "newPlanetTexture.png";
;N.B.
The illumination mapping feature is disabled by setting ''Graphics Detail: Shaders Enabled'' or lower in the game setting menu. ''Enabled'' at ''Graphics Detail: Extra Detail''.

==Texture HSB Color==
This changes the overall hue of the replacement texture.

Example:
"texture_hsb_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Texture NormSpec==
{{oolite-prop-added|1.89}}

The external texture that will be used as a normal and specular map for the given planet. Colorspace should be linear, with the normal map in the r,g and b and the specular map in the a channel. The texture can be of either equirectangular or cubemap formats. This feature is available at the Extra Detail setting only. To set:
"texture_normspec" = "planetNormalAndSpecularMap.png";

=Properties of the Sky=

==Ambient Level==

Sets how much ambient light (shed by stars and nebulae) illuminates the dark side of objects like planets and ships. Values should typically be between 0.0 and 1.0 (1.0 is the default) but can be higher for a flat lit, cartoon-like effect.

Example:
"ambient_level" = "0.0";

==Nebula Count Multiplier==
This is used for defining the number of nebulas. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"nebula_count_multiplier" = "1.5";

==Sky Blur Alpha==
Default 0.1

Example:
"sky_blur_alpha" = "0.0 .. 1.0";

==Sky Blur Cluster Chance==
This is used for creating nebulae (typically 0.80)

Example:
"sky_blur_cluster_chance" = "0.85";

==Sky Blur Scale==
Default 10. Larger numbers generate bigger nebula, but slow down the game considerable on slower machines.

Example:
"sky_blur_scale" = "0.0 .. 128.0 or more";

==Sky N Blurs==
This is used for defining the number of nebulas (typical is 80, maximum is 1280). This key is multiplied by a "nebula_count_multiplier" definition in Oolite 1.81 or later.

Example:
"sky_n_blurs" = "800";

==Sky N Stars==
This is used for defining the number of stars (typical = 600, maximum in 1.76 or earlier is 4800). This key is multiplied by a "star_count_multiplier" definition in Oolite 1.81 or later. In reduced detail mode, this number will be capped to 2400.

Example:
"sky_n_stars" = "1200";

==Sky and Nebula RGB Colors==

These are rgb values (from 0.0 to 1.0) for the two colours between which the colour of the stars (and nebulaesque blurs) vary, ordered r1 g1 b1 r2 g2 b2 where (r1 g1 b1) defines the first colour and (r2 g2 b2) the second.<br>
(Default values are "0.75 0.8 1.0 1.0 0.85 0.6")

Example:
"sky_rgb_colors" = "0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0";

Alternatively, two [[Materials in Oolite#Colour specifiers|colour specifiers]] may be used:
"sky_color_1" = "redColor";
"sky_color_2" =
{
"hue" = "60";
"brightness" = "0.8";
}

"nebula_color_1" = "greenColor";
"nebula_color_2" = "blueColor";

==Star Count Multiplier==
This is used for defining the number of stars. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"star_count_multiplier" = "0.5";

=Properties of the Station=

==Market==
The market to be used in this system as the default market. It points to a key in commodities.plist

Example:
"market" = "rockhermit";
Will use the rockhermit market as default for for all stations in the system. When no market is defined a key in commodities.plist is used that matches the role of the main station. Than that is not defined, the default market is used in this system.

In 1.81 and later, this is replaced by market_script

==market_script==
{{oolite-prop-added|1.81}}

A Javascript file used to load a [[Oolite Market Scripts|market script]] for global system price and quantity modifications.

"market_script" = "myoxp_newsystemmarket.js";

==Station==
The type of station orbiting the main planet.

Example:
"station" = "coriolis..dodec..special";

==Station Roll==
The speed at which the station rotates (as with all rotational velocities this is in radians per second) and affects all rotating stations in a system. For a specific station you can use the key [[Shipdata.plist#station_roll | station_roll]] in shipdata.plist.

Example:
"station_roll" = "0.5";

==Station Vector==
The direction of the main station from the main planet

Example:
"station_vector" = "-0.717 -0.668 0.201";

==Stations Require Docking Clearance==

Specifies if a player has to explicit ask docking permission. See also [[Oolite_Docking_Clearance_Protocol_%28v1.72_or_later%29|Oolite Docking Clearance]]

=Properties of the Sun=
;N.B.
The corona effect, modified by the first three properties mentioned below, is disabled by setting ''Reduced Detail:On'' in the game setting menu. ''Enabled'' by default (''Reduced Detail:Off'').

==Corona Flare==

Sets the overall size of the corona in proportion to its sun. (See note above.)

A number from 0.0 (invisibly small) to 1.0 (huge)

Example:
"corona_flare" = "0.075";

==Corona Hues==

Specifies whether the corona should have visible bands of colours within the corona. (See note above.)

A number from 0.0 (monochromatic) to 1.0 (vivid alternating colours).

Example:
"corona_hues" = "0.6";

==Corona Shimmer==

Specifies how quickly the corona colours change. (See note above.)

A number from 0.0 (very slow) to 1.0 (very fast).

Example:
"corona_shimmer" = "0.4";

==Sun Color==

Sets the colour of a system's sun.

Can be any [[Materials in Oolite#Colour specifiers|colour specifier]] or [[Materials in Oolite#Named colours|named colour]]. The specified colour is blended with 50% white so it will never be a saturated colour. Dark colours will be brightened by this blending.

Example:
"sun_color" = "blueColor";

==Sun Distance==
{{oolite-prop-added|1.81}}

Sets the distance between the sun and the main planet in metres.

Example:
"sun_distance" = 924122;

Ignored if sun_distance_modifier is set.

==Sun Distance Multiplier==
{{oolite-prop-added|1.81}}

Multiplies the distance between the sun and the main planet by this factor.

Example:
"sun_distance_multiplier" = 2;

Ignored if sun_distance_modifier is set.

==Sun Distance Modifier==

Sets the approximate distance between a system sun and its main planet. The standard distance is 20 planetary radii. Setting it much lower (10, or even less) will cause delays when generating systems, as Oolite compensates for possible collisions between the sun and other system objects.

Example:
"sun_distance_modifier" = "15.0";

In Oolite 1.81 or later, sun_distance_multiplier is more useful.

== Sun Gone Nova ==

Sets a nova sun in the system.

Example:
"sun_gone_nova" = "YES";

==Sun Name==

Stores the name of a system's sun. This is only implemented in Oolite from version 1.79 onwards, though was used by OXPs before then.

Example:
"sun_name" = "Alpha Centauri";

==Sun Radius==

Sets the radius of a system's sun. A number between 1000 and 1000000.

Example:
"sun_radius" = "100000";

==Sun Vector==
The direction of the sun from the main planet

Example:
"sun_vector" = "-0.717 -0.668 0.201";

=Hyperspace Travel=

In Oolite 1.81 and later these properties have been moved into [[global-settings.plist]]

==Galactic Hyperspace Behaviour==

The key galactic_hyperspace_behaviour controls where the player will arrive after a G.H. has been executed. There are three possible types of G.H. behavior and are as follows:

1) Oolite standard. This is what we have up to this moment. Executing a G.H. jump will poisition the player in the next galaxy, to the closest non-isolated system with regards to their current galaxy coordinates. So, for example, if you jump from coordinates (100, 50) in galaxy 1 you will arrive in galaxy 2 at the same coordinates, unless these coordinates refer to an unreachable system, in which case the arrival point will be adjusted by the engine to maybe something like (102, 51). This is set as default behavior. It is set by assigning the string BEHAVIOUR_STANDARD to the galactic_hyperspace_behaviour key.

2) All systems reachable. Same as above, only this time we do not check for arrival at an isolated system. Using this method, systems like Oresrati in G8, the lower left hand cluster of systems in G7, the two islands of isolated systems in G6 etc. are now possible arrival points. If you land there, you may not be able to exit again, depending on the tech levels of the systems you get to. Mission scripters may want to use this. This behaviour is set by assigning the string BEHAVIOUR_ALL_SYSTEMS_REACHABLE to galactic_hyperspace_behaviour key in planetinfo.plist.

3) Fixed coordinates arrival point. This will make Oolite simulate some older 8-bit versions, that were putting the player in the same fixed point every time a galactic jump was performed, but there is also good potential for scripting (see below). This is set by assigning the string BEHAVIOUR_FIXED_COORDINATES to the galactic_hyperspace_behaviour key.

==Galactic Hyperspace Fixed Coords==

If the fixed coordinates method is chosen, then the engine will look in planetinfo.plist for a key named galactic_hyperspace_fixed_coords, from which it will read the actual coordinates that will be used as the arrival point in the next galaxy. If none is found, then coordinates (96,96) will be used.

==Hyperspace Tunnel Color==

One or two colours can be set, using RGBA format, to over-ride the appearance of the hyperspace tunnel effect.
Example:

hyperspace_tunnel_color_1 = (1.0, 0.0, 0.0, 0.5);
hyperspace_tunnel_color_2 = (0.0, 0.0, 1.0, 0.25);



=Additional Planets=

Finally you can also define your own custom planets and moons:
"LavesPurpleMoon" =
{
...
}


To add them to the system, use JS methods <code>[[Oolite_JavaScript_Reference:_System#addPlanet|system.addPlanet]]</code> and <code>[[Oolite_JavaScript_Reference:_System#addPlanet|system.addMoon]]</code>. For the example above, the <code>planetInfoKey</code> will be <code>"LavesPurpleMoon"</code>.

==Position==
Position of the planet in space. The first parameter is 3-character code of the coordinate system, other three is x, y and z components of position vector.
"position" = "pwm 0 -50000 0";

You can omit the coordinate system parameter, then the absolute coordinate system will be used:
"position" = "0 -50000 0";

See [[Oolite coordinate systems]] for more info about it.

==Orientation==
Orientation of the planet in space (seems not to be working correct).

Example:
"orientation" = "0.0 1.0 0.0 0.0";

==Other keys==

You can use other keys from the [[#Properties_of_the_Planet| Properties of the Planet]] section for your planets and moons.

Here are some of the keys you may want to use:
* "radius": Radius of the planet in km. e.g. a value of 500 is drawn with a radius of 5000 meters but in player dialogues this value is presented as 500 km.
* "rotational_velocity": Rotation of the planet in rotations per second.
* "texture": The name of the texture file that is used to wrap around the surface.
* "seed": Seed value used to create the planet's surface features. If no seed is defined it uses the same seed as the main planet, and will create a copy of it.

= Links =
*[[Random number generator]] - originally used for creating planet descriptions
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=3860 seed = "1 2 3 4 5 6";]: Psuedo-random number generation & planet descriptions (2007)
*[http://aegidian.org/bb/viewtopic.php?f=4&t=3808 position = "x y z" in planetinfo.plist] (2007)
*Submersible's [https://www.youtube.com/user/submersibletoaster YouTube videos] of planet textures (2012)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=5044 Question: How to add custom planet descriptions] (2008)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20959 Empty system] Removing the stations (and presumably inhabitants) from a system (2021)

[[Category:Oolite]]
[[Category:Oolite scripting]]

Planetinfo.plist

2023-05-04T22:14:48Z

Alnivel: /* Properties of the Planet */ Added air_color, air_color_mix_ratio, terminator_threshold_vector properties, tweaked air_density

'''planetinfo.[[plist]]''' in 'AddOns/Config' contains a dictionary for each of systems for which you wish to set custom data. A list of all galaxies and planets can be found [[Oolite planet list|here]]. Each of the properties mentioned below can be set (but, notably, not the location of the main planet, which is hard coded into the system seed value):

=== Added for Oolite v.1.91 ===
*air_density / or the Javascript planet entity airDensity - see below (pretty picture!)

=== Added for Oolite v.1.89 ===
This needs editing by somebody who understands it! Snatched from the Progress thread
*[http://aegidian.org/bb/viewtopic.php?p=270737#p270737 air_color] now produces the right color for the sky. Not only that, it is now used as the atmosphere scatter color when the planet is viewed from space. Non-blue atmospheres are finally possible!
*[http://aegidian.org/bb/viewtopic.php?p=270771#p270771 air_color_mix_ratio]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 terminator_threshold_vector shipdata key]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 JSPlanet terminatorThresholdVector property]
*[http://aegidian.org/bb/viewtopic.php?p=269833#p269833 MULTIPLIER_LIGHTSRCRADIANCE and MULITPLIER_EXPOSURE]: Planet, ships and atmosphere shaders can now define lightsource radiance and scene exposure multipliers
*Also stuff about city lights
*And probably other stuff I missed!

=Where Settings Apply=

==Universal Settings==

Some options can be applied to the entire universe, such as ambient lighting levels, eg.
"universal" =
{
...
}
Universal options can be over-ridden by specifying the same option for a specific system or location in interstellar space. Obviously, not all options make sense to apply to the whole universe.

==Interstellar Space==

Conditions for interstellar space in general can be set with the “interstellar space” key.

==Specific Systems==

Each system is keyed by a string consisting of the galaxy number (0..7) followed by a space and then the planet number (0..255), eg.
"0 7" =
{
...
}
specifies system 7, in galaxy 0, ''Lave''.

==Specific Interstellar Spaces==

You can also specify a position in interstellar space, eg.
"interstellar: 0 7 129" =
{
...
}
specifies the space in galaxy 0 between systems 7 and 129, ''Lave'' and ''Zaonce''.

In 1.81 the property "link_color" when set on a specific interstellar space changes the colour of the link between the two systems in the advanced navigation array (assuming no route is in place above it).

Note that
"interstellar: 0 7 129" = // jumping from Lave towards Zaonce
{
...
}
and
"interstellar: 0 129 7" = // jumping from Zaonce towards Lave
{
...
}
are distinct locations and if they both need the same properties this must be explicitly set for both. When setting link_color, the lower system ID must be placed first, because of how the chart is drawn.

==Layers==

Settings other than "universal" in Oolite 1.81 or later have a 'layer' property from 0 to 3. The default value for planetinfo.plist files is 1. If multiple OXPs specify a setting for a particular property, the order they will be checked in is:
* Layer 3 settings
* Layer 2 settings (default for Javascript changes to data)
* Layer 1 settings (default for planetinfo.plist)
* Universal settings
* Layer 0 settings (value for core game settings)

This allows OXPs to safely override each other's changes if necessary, and for OXPs which really need a specific setting in a particular system to set it at layer 3

Example
"layer" = 2;

==Terraforming Example==

For the planet Lave, you would use the key '0 7' (planet 7 in galaxy 0) Then you set the values. The following example sets Lave's sea to blue, land to green, and land to sea ratio to 75%.

Code:
{
"0 7" =
{
"percent_land" = "75";
"land_color" = "0.5 1.0 0.5";
"sea_color" = "0.3 0.7 1.0";
}
}

Then you can override any of the settings listed above, for example to change Zaatxe's (Galaxy 0 Planet 8) inhabitants into blue frogs you'd enter

Code:
"0 8" =
{
"inhabitants" = "Blue Frogs";
}

You can use any or all of the keys in each of the entries. It's probably best to only use the key's you want to change. So, another example, to change the sky_blur_xxx settings for Zaonce (Galaxy 0 Planet 129) to big, heavily clustered, but pale blurs - you'd enter

Code:
"0 129" =
{
"sky_blur_cluster_chance" = "0.9";
"sky_blur_alpha" = "0.1";
"sky_blur_scale" = "32.0";
}

=About the Inhabitants=

==Concealment==
{{oolite-prop-added|1.83}}

An integer that determines how much information about the system is unknown.

Example:
"concealment" = "300";
The following values are recognised:
* 0: default, all information visible
* 100 or more: F7 screen shows no information, economy/government/TL/star colour not visible on chart
* 200 or more: system name is not shown
* 300 or more: system vanishes entirely from chart, will not be used in route plotting, cannot be targeted by player (NPCs can still jump to it, though)

==Government==

An integer between 0 and 7 indicating the government type of the system.

Example:
"goverment" = "7";

Possible values:
: 0: Anarchy
: 1: Feudal
: 2: Multi-Governmental
: 3: Dictatorship
: 4: Communist
: 5: Confederacy
: 6: Democracy
: 7: Corporate State

==Economy==
An integer between 0 and 7 indicating the economy type of the system.

Example:
"economy" = "5";

Possible values:
: 0: Rich Industrial
: 1: Average Industrial
: 2: Poor Industrial
: 3: Mainly Industrial
: 4: Mainly Agricultural
: 5: Rich Agricultural
: 6: Average Agricultural
: 7: Poor Agricultural

==Tech Level==

An integer between 0 and 14 indicating the sophistication of the planets technology. The tech level displayed on the system data screens in game is one higher than this number (range 1 to 15).

Example:
"techlevel" = "13";

==Population==

An integer between 0 and 67 indicating the number of inhabitants of a planet in hundreds of millions

Example:
"population" = "23";

==Productivity==

An integer indicating the productivity of a planet.

Example:
"productivity" = "1000";

==Name==

The name of the planet.

Example:
"name" = "The planet's name";

==Inhabitant==

The name for one of the inhabitants of the main planet.

Example:
"inhabitant" = "Green Platypus";

==Inhabitants==

The name of the inhabitants of the main planet.

Example:
"inhabitants" = "Green Platypi";

==Description==

A short description of the planet.

Example:
"description" = "Really, anything you want to say about the place!";

==Government Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the government.

Example:
"government_description" = "Dictatorship (Monarchy)";

==Economy Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the economy.

Example:
"economy_description" = "Mainly Industrial (Machine Tools)";

==Population Description==
{{oolite-prop-added|1.77}}

Overrides the default text used to describe the population.

Example:
"population_description" = "13 Billion";

==Random Seed==
{{oolite-prop-added|1.81}}

A seed for a random number generator used in Oolite 1.81 to generate system properties impractical to store in this file (e.g. the positions of each star on the background starfield)

For historical reasons, this is a string of 6 integers between 0 and 255, for example:
random_seed = "74 90 72 2 83 183";

=System population=
These properties are only used in Oolite 1.79 or later.

==Populator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|populate the system]]

Example:
"populator" = "systemWillPopulate";

==Repopulator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|repopulate the system]]

Example:
"repopulator" = "systemWillRepopulate";

=Properties of the Planet=

Most of these properties are ignored if a planet texture is set.

Note that the available planet texture generator properties changed in places between Oolite 1.77 and Oolite 1.80

==Air color==
A colour specifier determining the color of the planet's sky, as well as the atmosphere scatter color.

Example:
"air_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Air Color Mix Ratio==
{{oolite-prop-added|1.89}}

The amount of air color that be mixed in the overall atmosphere color. A number from 0.0 to 1.0 (default 0.5).

Example:
"air_color_mix_ratio" = "0.0..1.0";

==Atmosphere Rotational Velocity==

Sets how fast the atmosphere is rotating. (A random value between 0.0 to 0.03 is the default).

Example:
"atmosphere_rotational_velocity" = "0.1";

==Cloud Alpha==
{{oolite-prop-added|1.77}}

The transparency level of the cloud layer, relative to the standard transparency. 1.0 is the default. Texture packs which include clouds on the planetary texture may wish to reduce this.

Example:
"cloud_alpha" = "0.2";

==Has Atmosphere==
{{oolite-prop-added|1.81}}

This boolean property is used for the main planet only. If it is unset or true, the main planet has an atmosphere, as is always the case in 1.80 and before. If it is set to be false, then the planet will not have an atmosphere.

Example:
"has_atmosphere" = 0;

This has no effect on secondary planets - their atmosphere is determined by whether addition uses <code>addPlanet</code> or <code>addMoon</code>.

[[File:AtmDensityExample.png|thumb|320px|right|Atmosphere Density examples: Stranger's ''FPO Lave'' in four increasing atmosphere densities: 0.2, 0.5, 0.75 and 1.0. Every other parameter in the planet definition is the same in all pictures.]]
== Atmosphere Density ==
{{oolite-prop-added|1.91}}

A number clamped in range from 0.0 to 1.0 describing the density of the planet's atmosphere. All planets in the core use 0.75 as default.

Example:
"air_density" = "0.0..1.0";

==Land Color==

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Percent Cloud==
The percentage of the planet's atmosphere occupied by clouds.

Example:
"percent_cloud" = "0..100";

Note that with a low cloud_alpha setting not all of the clouds defined here may actually be visible

==Percent Ice==
The percentage of the planet occupied by the polar ice caps. Oolite 1.81 or later.

Example:
"percent_ice" = "0..100";

==Percent Land==
The percentage of the planet occupied by land.

Example:
"percent_land" = "0..100";

==Planet Distance==
{{oolite-prop-added|1.81}}

The distance from the centre of the planet to the witchpoint. Only used for the system main planet - secondary planets are positioned separately.

Example
"planet_distance" = "410000";

The main planet is always positioned on the z-axis.

==Planet Name==
{{oolite-prop-added|1.79}}

The planet's name. For the main planet, this defaults to being the same as the system name - the property is mainly intended for secondary planets.

Example
"planet_name" = "Earth";

==Polar Land Color==
{{oolite-prop-added|1.81}}

Sets the land colour in polar regions.

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Polar Sea Color==
{{oolite-prop-added|1.81}}

Sets the sea colour in polar regions.

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Radius==
An integer between 3000 and 7000 indicating the radius of the main planet. On the F7 screen, this is measured in kilometres. The radius in game is 1/100th of this.

Example:
"radius" = "5500";

==Rotational Velocity==
A number describing the rotational velocity of the planet in radians per second. Overrides rotation_speed if both are set.

Example:
"rotational_velocity" = 0.0015;

==Rotation Speed==
A number describing the rotational velocity of the planet in radians per second. Unlike rotational_velocity, this is affected by rotation_speed_factor.

Example:
"rotation_speed" = 0.0015;

==Rotation Speed Factor==
The rotational speed of all planets whose rotational speed was set by rotation_speed and not by rotational_velocity will be multiplied by this number.

Example:
"rotation_speed_factor" = 1.0;

(Intended more for the universal section as a "personal taste" option than for individual planets)

==Sea Color==

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Terminator Threshold Vector==
{{oolite-prop-added|1.89}}

This property gives control over the color of the planet's terminator. The way the property works is not entirely straightforward, so see [http://aegidian.org/bb/viewtopic.php?p=271058#p271058 this post on BB] for more information.

Example:
"terminator_threshold_vector" = "0.0..1.0 0.0..1.0 0.0..1.0";
By default the terminator vector is "0.105 0.18 0.28" - which results in a reddish orange colour.

==Texture==
The replacement texture to be used by a system's main planet.<br>

For textures you can use lat-long maps (twice as wide as high) with a special elongation at the poles or cube maps. Other maps also will be wraped around planets but give always distortions.<br>
Since Oolite 1.74 you can also use cube maps for planets. Cube maps are 6 times higher as wide and will be recognised automatic by Oolite, based on its dimensions. Cube maps are the preferred method because lat-long give some distortion and have the poles improperly placed in Oolites implementation. See also [[Planettool]] for conversion from lat-long into cube maps.

From Oolite 1.89 onwards, illumination mapping on custom planets is supported. The illumination map goes in the diffuse map's alpha channel. Low alpha values translate to high illumination. This allows for effects like city lights on a planet's dark side.

Example:
"texture" = "newPlanetTexture.png";
;N.B.
The illumination mapping feature is disabled by setting ''Graphics Detail: Shaders Enabled'' or lower in the game setting menu. ''Enabled'' at ''Graphics Detail: Extra Detail''.

==Texture HSB Color==
This changes the overall hue of the replacement texture.

Example:
"texture_hsb_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Texture NormSpec==
{{oolite-prop-added|1.89}}

The external texture that will be used as a normal and specular map for the given planet. Colorspace should be linear, with the normal map in the r,g and b and the specular map in the a channel. The texture can be of either equirectangular or cubemap formats. This feature is available at the Extra Detail setting only. To set:
"texture_normspec" = "planetNormalAndSpecularMap.png";

=Properties of the Sky=

==Ambient Level==

Sets how much ambient light (shed by stars and nebulae) illuminates the dark side of objects like planets and ships. Values should typically be between 0.0 and 1.0 (1.0 is the default) but can be higher for a flat lit, cartoon-like effect.

Example:
"ambient_level" = "0.0";

==Nebula Count Multiplier==
This is used for defining the number of nebulas. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"nebula_count_multiplier" = "1.5";

==Sky Blur Alpha==
Default 0.1

Example:
"sky_blur_alpha" = "0.0 .. 1.0";

==Sky Blur Cluster Chance==
This is used for creating nebulae (typically 0.80)

Example:
"sky_blur_cluster_chance" = "0.85";

==Sky Blur Scale==
Default 10. Larger numbers generate bigger nebula, but slow down the game considerable on slower machines.

Example:
"sky_blur_scale" = "0.0 .. 128.0 or more";

==Sky N Blurs==
This is used for defining the number of nebulas (typical is 80, maximum is 1280). This key is multiplied by a "nebula_count_multiplier" definition in Oolite 1.81 or later.

Example:
"sky_n_blurs" = "800";

==Sky N Stars==
This is used for defining the number of stars (typical = 600, maximum in 1.76 or earlier is 4800). This key is multiplied by a "star_count_multiplier" definition in Oolite 1.81 or later. In reduced detail mode, this number will be capped to 2400.

Example:
"sky_n_stars" = "1200";

==Sky and Nebula RGB Colors==

These are rgb values (from 0.0 to 1.0) for the two colours between which the colour of the stars (and nebulaesque blurs) vary, ordered r1 g1 b1 r2 g2 b2 where (r1 g1 b1) defines the first colour and (r2 g2 b2) the second.<br>
(Default values are "0.75 0.8 1.0 1.0 0.85 0.6")

Example:
"sky_rgb_colors" = "0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0";

Alternatively, two [[Materials in Oolite#Colour specifiers|colour specifiers]] may be used:
"sky_color_1" = "redColor";
"sky_color_2" =
{
"hue" = "60";
"brightness" = "0.8";
}

"nebula_color_1" = "greenColor";
"nebula_color_2" = "blueColor";

==Star Count Multiplier==
This is used for defining the number of stars. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"star_count_multiplier" = "0.5";

=Properties of the Station=

==Market==
The market to be used in this system as the default market. It points to a key in commodities.plist

Example:
"market" = "rockhermit";
Will use the rockhermit market as default for for all stations in the system. When no market is defined a key in commodities.plist is used that matches the role of the main station. Than that is not defined, the default market is used in this system.

In 1.81 and later, this is replaced by market_script

==market_script==
{{oolite-prop-added|1.81}}

A Javascript file used to load a [[Oolite Market Scripts|market script]] for global system price and quantity modifications.

"market_script" = "myoxp_newsystemmarket.js";

==Station==
The type of station orbiting the main planet.

Example:
"station" = "coriolis..dodec..special";

==Station Roll==
The speed at which the station rotates (as with all rotational velocities this is in radians per second) and affects all rotating stations in a system. For a specific station you can use the key [[Shipdata.plist#station_roll | station_roll]] in shipdata.plist.

Example:
"station_roll" = "0.5";

==Station Vector==
The direction of the main station from the main planet

Example:
"station_vector" = "-0.717 -0.668 0.201";

==Stations Require Docking Clearance==

Specifies if a player has to explicit ask docking permission. See also [[Oolite_Docking_Clearance_Protocol_%28v1.72_or_later%29|Oolite Docking Clearance]]

=Properties of the Sun=
;N.B.
The corona effect, modified by the first three properties mentioned below, is disabled by setting ''Reduced Detail:On'' in the game setting menu. ''Enabled'' by default (''Reduced Detail:Off'').

==Corona Flare==

Sets the overall size of the corona in proportion to its sun. (See note above.)

A number from 0.0 (invisibly small) to 1.0 (huge)

Example:
"corona_flare" = "0.075";

==Corona Hues==

Specifies whether the corona should have visible bands of colours within the corona. (See note above.)

A number from 0.0 (monochromatic) to 1.0 (vivid alternating colours).

Example:
"corona_hues" = "0.6";

==Corona Shimmer==

Specifies how quickly the corona colours change. (See note above.)

A number from 0.0 (very slow) to 1.0 (very fast).

Example:
"corona_shimmer" = "0.4";

==Sun Color==

Sets the colour of a system's sun.

Can be any [[Materials in Oolite#Colour specifiers|colour specifier]] or [[Materials in Oolite#Named colours|named colour]]. The specified colour is blended with 50% white so it will never be a saturated colour. Dark colours will be brightened by this blending.

Example:
"sun_color" = "blueColor";

==Sun Distance==
{{oolite-prop-added|1.81}}

Sets the distance between the sun and the main planet in metres.

Example:
"sun_distance" = 924122;

Ignored if sun_distance_modifier is set.

==Sun Distance Multiplier==
{{oolite-prop-added|1.81}}

Multiplies the distance between the sun and the main planet by this factor.

Example:
"sun_distance_multiplier" = 2;

Ignored if sun_distance_modifier is set.

==Sun Distance Modifier==

Sets the approximate distance between a system sun and its main planet. The standard distance is 20 planetary radii. Setting it much lower (10, or even less) will cause delays when generating systems, as Oolite compensates for possible collisions between the sun and other system objects.

Example:
"sun_distance_modifier" = "15.0";

In Oolite 1.81 or later, sun_distance_multiplier is more useful.

== Sun Gone Nova ==

Sets a nova sun in the system.

Example:
"sun_gone_nova" = "YES";

==Sun Name==

Stores the name of a system's sun. This is only implemented in Oolite from version 1.79 onwards, though was used by OXPs before then.

Example:
"sun_name" = "Alpha Centauri";

==Sun Radius==

Sets the radius of a system's sun. A number between 1000 and 1000000.

Example:
"sun_radius" = "100000";

==Sun Vector==
The direction of the sun from the main planet

Example:
"sun_vector" = "-0.717 -0.668 0.201";

=Hyperspace Travel=

In Oolite 1.81 and later these properties have been moved into [[global-settings.plist]]

==Galactic Hyperspace Behaviour==

The key galactic_hyperspace_behaviour controls where the player will arrive after a G.H. has been executed. There are three possible types of G.H. behavior and are as follows:

1) Oolite standard. This is what we have up to this moment. Executing a G.H. jump will poisition the player in the next galaxy, to the closest non-isolated system with regards to their current galaxy coordinates. So, for example, if you jump from coordinates (100, 50) in galaxy 1 you will arrive in galaxy 2 at the same coordinates, unless these coordinates refer to an unreachable system, in which case the arrival point will be adjusted by the engine to maybe something like (102, 51). This is set as default behavior. It is set by assigning the string BEHAVIOUR_STANDARD to the galactic_hyperspace_behaviour key.

2) All systems reachable. Same as above, only this time we do not check for arrival at an isolated system. Using this method, systems like Oresrati in G8, the lower left hand cluster of systems in G7, the two islands of isolated systems in G6 etc. are now possible arrival points. If you land there, you may not be able to exit again, depending on the tech levels of the systems you get to. Mission scripters may want to use this. This behaviour is set by assigning the string BEHAVIOUR_ALL_SYSTEMS_REACHABLE to galactic_hyperspace_behaviour key in planetinfo.plist.

3) Fixed coordinates arrival point. This will make Oolite simulate some older 8-bit versions, that were putting the player in the same fixed point every time a galactic jump was performed, but there is also good potential for scripting (see below). This is set by assigning the string BEHAVIOUR_FIXED_COORDINATES to the galactic_hyperspace_behaviour key.

==Galactic Hyperspace Fixed Coords==

If the fixed coordinates method is chosen, then the engine will look in planetinfo.plist for a key named galactic_hyperspace_fixed_coords, from which it will read the actual coordinates that will be used as the arrival point in the next galaxy. If none is found, then coordinates (96,96) will be used.

==Hyperspace Tunnel Color==

One or two colours can be set, using RGBA format, to over-ride the appearance of the hyperspace tunnel effect.
Example:

hyperspace_tunnel_color_1 = (1.0, 0.0, 0.0, 0.5);
hyperspace_tunnel_color_2 = (0.0, 0.0, 1.0, 0.25);



=Additional Planets=

Finally you can also add keys for your own custom planets and moons, eg.
"LavesPurpleMoon" =
{
...
}

The contents of the { could be:
Orientation of the planet in space (seems not to be working correct)
"orientation" = "0.0 1.0 0.0 0.0";

Position of the planet in space. You can use 3 or 4 parameters. With only 3 parameters the internal absolute coordinates are used.
"position" = "0 -50000 0";
or
"position" = "pwm 0 -50000 0";

Radius of the planet in km. e.g. a value of 500 is drawn with a radius of 5000 meters but in player dialogues this value is presented as 500 km.
"radius" = "500";

Rotation of the planet in rotations per second.
"rotational_velocity" = "1";

The name of the texture file that is used to wrap around the surface.
"texture" = "grid.png";

Seed value used to create the planet's surface features. If no seed is defined it uses the same seed as the main planet, and will create a copy of it.
"seed" = "1 2 3 4 5 6";

A lot of the keys for the main planet, like: '''percent_land''', can also used in custom planets.

== Links ==
*[[Random number generator]] - originally used for creating planet descriptions
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=3860 seed = "1 2 3 4 5 6";]: Psuedo-random number generation & planet descriptions (2007)
*[http://aegidian.org/bb/viewtopic.php?f=4&t=3808 position = "x y z" in planetinfo.plist] (2007)
*Submersible's [https://www.youtube.com/user/submersibletoaster YouTube videos] of planet textures (2012)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=5044 Question: How to add custom planet descriptions] (2008)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20959 Empty system] Removing the stations (and presumably inhabitants) from a system (2021)

[[Category:Oolite]]
[[Category:Oolite scripting]]

Planetinfo.plist

2023-05-04T20:50:41Z

Alnivel: /* About the Inhabitants */ Uniform properties format

'''planetinfo.[[plist]]''' in 'AddOns/Config' contains a dictionary for each of systems for which you wish to set custom data. A list of all galaxies and planets can be found [[Oolite planet list|here]]. Each of the properties mentioned below can be set (but, notably, not the location of the main planet, which is hard coded into the system seed value):

=== Added for Oolite v.1.91 ===
*air_density / or the Javascript planet entity airDensity - see below (pretty picture!)

=== Added for Oolite v.1.89 ===
This needs editing by somebody who understands it! Snatched from the Progress thread
*[http://aegidian.org/bb/viewtopic.php?p=270737#p270737 air_color] now produces the right color for the sky. Not only that, it is now used as the atmosphere scatter color when the planet is viewed from space. Non-blue atmospheres are finally possible!
*[http://aegidian.org/bb/viewtopic.php?p=270771#p270771 air_color_mix_ratio]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 terminator_threshold_vector shipdata key]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 JSPlanet terminatorThresholdVector property]
*[http://aegidian.org/bb/viewtopic.php?p=269833#p269833 MULTIPLIER_LIGHTSRCRADIANCE and MULITPLIER_EXPOSURE]: Planet, ships and atmosphere shaders can now define lightsource radiance and scene exposure multipliers
*Also stuff about city lights
*And probably other stuff I missed!

=Where Settings Apply=

==Universal Settings==

Some options can be applied to the entire universe, such as ambient lighting levels, eg.
"universal" =
{
...
}
Universal options can be over-ridden by specifying the same option for a specific system or location in interstellar space. Obviously, not all options make sense to apply to the whole universe.

==Interstellar Space==

Conditions for interstellar space in general can be set with the “interstellar space” key.

==Specific Systems==

Each system is keyed by a string consisting of the galaxy number (0..7) followed by a space and then the planet number (0..255), eg.
"0 7" =
{
...
}
specifies system 7, in galaxy 0, ''Lave''.

==Specific Interstellar Spaces==

You can also specify a position in interstellar space, eg.
"interstellar: 0 7 129" =
{
...
}
specifies the space in galaxy 0 between systems 7 and 129, ''Lave'' and ''Zaonce''.

In 1.81 the property "link_color" when set on a specific interstellar space changes the colour of the link between the two systems in the advanced navigation array (assuming no route is in place above it).

Note that
"interstellar: 0 7 129" = // jumping from Lave towards Zaonce
{
...
}
and
"interstellar: 0 129 7" = // jumping from Zaonce towards Lave
{
...
}
are distinct locations and if they both need the same properties this must be explicitly set for both. When setting link_color, the lower system ID must be placed first, because of how the chart is drawn.

==Layers==

Settings other than "universal" in Oolite 1.81 or later have a 'layer' property from 0 to 3. The default value for planetinfo.plist files is 1. If multiple OXPs specify a setting for a particular property, the order they will be checked in is:
* Layer 3 settings
* Layer 2 settings (default for Javascript changes to data)
* Layer 1 settings (default for planetinfo.plist)
* Universal settings
* Layer 0 settings (value for core game settings)

This allows OXPs to safely override each other's changes if necessary, and for OXPs which really need a specific setting in a particular system to set it at layer 3

Example
"layer" = 2;

==Terraforming Example==

For the planet Lave, you would use the key '0 7' (planet 7 in galaxy 0) Then you set the values. The following example sets Lave's sea to blue, land to green, and land to sea ratio to 75%.

Code:
{
"0 7" =
{
"percent_land" = "75";
"land_color" = "0.5 1.0 0.5";
"sea_color" = "0.3 0.7 1.0";
}
}

Then you can override any of the settings listed above, for example to change Zaatxe's (Galaxy 0 Planet 8) inhabitants into blue frogs you'd enter

Code:
"0 8" =
{
"inhabitants" = "Blue Frogs";
}

You can use any or all of the keys in each of the entries. It's probably best to only use the key's you want to change. So, another example, to change the sky_blur_xxx settings for Zaonce (Galaxy 0 Planet 129) to big, heavily clustered, but pale blurs - you'd enter

Code:
"0 129" =
{
"sky_blur_cluster_chance" = "0.9";
"sky_blur_alpha" = "0.1";
"sky_blur_scale" = "32.0";
}

=About the Inhabitants=

==Concealment==
{{oolite-prop-added|1.83}}

An integer that determines how much information about the system is unknown.

Example:
"concealment" = "300";
The following values are recognised:
* 0: default, all information visible
* 100 or more: F7 screen shows no information, economy/government/TL/star colour not visible on chart
* 200 or more: system name is not shown
* 300 or more: system vanishes entirely from chart, will not be used in route plotting, cannot be targeted by player (NPCs can still jump to it, though)

==Government==

An integer between 0 and 7 indicating the government type of the system.

Example:
"goverment" = "7";

Possible values:
: 0: Anarchy
: 1: Feudal
: 2: Multi-Governmental
: 3: Dictatorship
: 4: Communist
: 5: Confederacy
: 6: Democracy
: 7: Corporate State

==Economy==
An integer between 0 and 7 indicating the economy type of the system.

Example:
"economy" = "5";

Possible values:
: 0: Rich Industrial
: 1: Average Industrial
: 2: Poor Industrial
: 3: Mainly Industrial
: 4: Mainly Agricultural
: 5: Rich Agricultural
: 6: Average Agricultural
: 7: Poor Agricultural

==Tech Level==

An integer between 0 and 14 indicating the sophistication of the planets technology. The tech level displayed on the system data screens in game is one higher than this number (range 1 to 15).

Example:
"techlevel" = "13";

==Population==

An integer between 0 and 67 indicating the number of inhabitants of a planet in hundreds of millions

Example:
"population" = "23";

==Productivity==

An integer indicating the productivity of a planet.

Example:
"productivity" = "1000";

==Name==

The name of the planet.

Example:
"name" = "The planet's name";

==Inhabitant==

The name for one of the inhabitants of the main planet.

Example:
"inhabitant" = "Green Platypus";

==Inhabitants==

The name of the inhabitants of the main planet.

Example:
"inhabitants" = "Green Platypi";

==Description==

A short description of the planet.

Example:
"description" = "Really, anything you want to say about the place!";

==Government Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the government.

Example:
"government_description" = "Dictatorship (Monarchy)";

==Economy Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the economy.

Example:
"economy_description" = "Mainly Industrial (Machine Tools)";

==Population Description==
{{oolite-prop-added|1.77}}

Overrides the default text used to describe the population.

Example:
"population_description" = "13 Billion";

==Random Seed==
{{oolite-prop-added|1.81}}

A seed for a random number generator used in Oolite 1.81 to generate system properties impractical to store in this file (e.g. the positions of each star on the background starfield)

For historical reasons, this is a string of 6 integers between 0 and 255, for example:
random_seed = "74 90 72 2 83 183";

=System population=
These properties are only used in Oolite 1.79 or later.

==Populator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|populate the system]]

Example:
"populator" = "systemWillPopulate";

==Repopulator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|repopulate the system]]

Example:
"repopulator" = "systemWillRepopulate";

=Properties of the Planet=

Most of these properties are ignored if a planet texture is set.

Note that the available planet texture generator properties changed in places between Oolite 1.77 and Oolite 1.80

==Atmosphere Rotational Velocity==

Sets how fast the atmosphere is rotating. (A random value between 0.0 to 0.03 is the default).

Example:
"atmosphere_rotational_velocity" = "0.1";

==Cloud Alpha==
{{oolite-prop-added|1.77}}

The transparency level of the cloud layer, relative to the standard transparency. 1.0 is the default. Texture packs which include clouds on the planetary texture may wish to reduce this.

Example:
"cloud_alpha" = "0.2";

==Has Atmosphere==
{{oolite-prop-added|1.81}}

This boolean property is used for the main planet only. If it is unset or true, the main planet has an atmosphere, as is always the case in 1.80 and before. If it is set to be false, then the planet will not have an atmosphere.

Example:
"has_atmosphere" = 0;

This has no effect on secondary planets - their atmosphere is determined by whether addition uses <code>addPlanet</code> or <code>addMoon</code>.

[[File:AtmDensityExample.png|thumb|320px|right|Atmosphere Density examples: Stranger's ''FPO Lave'' in four increasing atmosphere densities: 0.2, 0.5, 0.75 and 1.0. Every other parameter in the planet definition is the same in all pictures.]]
== Atmosphere Density ==
{{oolite-prop-added|1.91}}
Added by an ignoramus - needs editing by one of our cognoscenti
See [http://aegidian.org/bb/viewtopic.php?p=272721#p272721 another_commander » Sun Nov 22, 2020 2:26 pm]
In tomorrow's nightly we will have a little upgrade in the planet properties: atmosphere density.

Some planets can be made to have denser atmosphere than others. This will allow for more variety in planets' appearance. To achieve this, you can use either the planetinfo.plist property air_density or the Javascript planet entity airDensity. The accepted value range is from 0.0 to 1.0 and anything outside of this range will be automatically clamped. We default all planets to 0.75 in the core.

==Land Color==

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Percent Cloud==
The percentage of the planet's atmosphere occupied by clouds.

Example:
"percent_cloud" = "0..100";

Note that with a low cloud_alpha setting not all of the clouds defined here may actually be visible

==Percent Ice==
The percentage of the planet occupied by the polar ice caps. Oolite 1.81 or later.

Example:
"percent_ice" = "0..100";

==Percent Land==
The percentage of the planet occupied by land.

Example:
"percent_land" = "0..100";

==Planet Distance==
(1.81 or later)

The distance from the centre of the planet to the witchpoint. Only used for the system main planet - secondary planets are positioned separately.

Example
"planet_distance" = "410000";

The main planet is always positioned on the z-axis.

==Planet Name==
{{oolite-prop-added|1.79}}

The planet's name. For the main planet, this defaults to being the same as the system name - the property is mainly intended for secondary planets.

Example
"planet_name" = "Earth";

==Polar Land Color==
{{oolite-prop-added|1.81}}

Sets the land colour in polar regions.

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Polar Sea Color==
{{oolite-prop-added|1.81}}

Sets the sea colour in polar regions.

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Radius==
An integer between 3000 and 7000 indicating the radius of the main planet. On the F7 screen, this is measured in kilometres. The radius in game is 1/100th of this.

Example:
"radius" = "5500";

==Rotational Velocity==
A number describing the rotational velocity of the planet in radians per second. Overrides rotation_speed if both are set.

Example:
"rotational_velocity" = 0.0015;

==Rotation Speed==
A number describing the rotational velocity of the planet in radians per second. Unlike rotational_velocity, this is affected by rotation_speed_factor.

Example:
"rotation_speed" = 0.0015;

==Rotation Speed Factor==
The rotational speed of all planets whose rotational speed was set by rotation_speed and not by rotational_velocity will be multiplied by this number.

Example:
"rotation_speed_factor" = 1.0;

(Intended more for the universal section as a "personal taste" option than for individual planets)

==Sea Color==

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Texture==
The replacement texture to be used by a system's main planet.<br>

For textures you can use lat-long maps (twice as wide as high) with a special elongation at the poles or cube maps. Other maps also will be wraped around planets but give always distortions.<br>
Since Oolite 1.74 you can also use cube maps for planets. Cube maps are 6 times higher as wide and will be recognised automatic by Oolite, based on its dimensions. Cube maps are the preferred method because lat-long give some distortion and have the poles improperly placed in Oolites implementation. See also [[Planettool]] for conversion from lat-long into cube maps.

From Oolite 1.89 onwards, illumination mapping on custom planets is supported. The illumination map goes in the diffuse map's alpha channel. Low alpha values translate to high illumination. This allows for effects like city lights on a planet's dark side.

Example:
"texture" = "newPlanetTexture.png";
;N.B.
The illumination mapping feature is disabled by setting ''Graphics Detail: Shaders Enabled'' or lower in the game setting menu. ''Enabled'' at ''Graphics Detail: Extra Detail''.

==Texture HSB Color==
This changes the overall hue of the replacement texture.

Example:
"texture_hsb_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Texture NormSpec==
(Oolite v1.89 and higher). The external texture that will be used as a normal and specular map for the given planet. Colorspace should be linear, with the normal map in the r,g and b and the specular map in the a channel. The texture can be of either equirectangular or cubemap formats. This feature is available at the Extra Detail setting only. To set:
"texture_normspec" = "planetNormalAndSpecularMap.png";

=Properties of the Sky=

==Ambient Level==

Sets how much ambient light (shed by stars and nebulae) illuminates the dark side of objects like planets and ships. Values should typically be between 0.0 and 1.0 (1.0 is the default) but can be higher for a flat lit, cartoon-like effect.

Example:
"ambient_level" = "0.0";

==Nebula Count Multiplier==
This is used for defining the number of nebulas. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"nebula_count_multiplier" = "1.5";

==Sky Blur Alpha==
Default 0.1

Example:
"sky_blur_alpha" = "0.0 .. 1.0";

==Sky Blur Cluster Chance==
This is used for creating nebulae (typically 0.80)

Example:
"sky_blur_cluster_chance" = "0.85";

==Sky Blur Scale==
Default 10. Larger numbers generate bigger nebula, but slow down the game considerable on slower machines.

Example:
"sky_blur_scale" = "0.0 .. 128.0 or more";

==Sky N Blurs==
This is used for defining the number of nebulas (typical is 80, maximum is 1280). This key is multiplied by a "nebula_count_multiplier" definition in Oolite 1.81 or later.

Example:
"sky_n_blurs" = "800";

==Sky N Stars==
This is used for defining the number of stars (typical = 600, maximum in 1.76 or earlier is 4800). This key is multiplied by a "star_count_multiplier" definition in Oolite 1.81 or later. In reduced detail mode, this number will be capped to 2400.

Example:
"sky_n_stars" = "1200";

==Sky and Nebula RGB Colors==

These are rgb values (from 0.0 to 1.0) for the two colours between which the colour of the stars (and nebulaesque blurs) vary, ordered r1 g1 b1 r2 g2 b2 where (r1 g1 b1) defines the first colour and (r2 g2 b2) the second.<br>
(Default values are "0.75 0.8 1.0 1.0 0.85 0.6")

Example:
"sky_rgb_colors" = "0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0";

Alternatively, two [[Materials in Oolite#Colour specifiers|colour specifiers]] may be used:
"sky_color_1" = "redColor";
"sky_color_2" =
{
"hue" = "60";
"brightness" = "0.8";
}

"nebula_color_1" = "greenColor";
"nebula_color_2" = "blueColor";

==Star Count Multiplier==
This is used for defining the number of stars. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"star_count_multiplier" = "0.5";

=Properties of the Station=

==Market==
The market to be used in this system as the default market. It points to a key in commodities.plist

Example:
"market" = "rockhermit";
Will use the rockhermit market as default for for all stations in the system. When no market is defined a key in commodities.plist is used that matches the role of the main station. Than that is not defined, the default market is used in this system.

In 1.81 and later, this is replaced by market_script

==market_script==
{{oolite-prop-added|1.81}}

A Javascript file used to load a [[Oolite Market Scripts|market script]] for global system price and quantity modifications.

"market_script" = "myoxp_newsystemmarket.js";

==Station==
The type of station orbiting the main planet.

Example:
"station" = "coriolis..dodec..special";

==Station Roll==
The speed at which the station rotates (as with all rotational velocities this is in radians per second) and affects all rotating stations in a system. For a specific station you can use the key [[Shipdata.plist#station_roll | station_roll]] in shipdata.plist.

Example:
"station_roll" = "0.5";

==Station Vector==
The direction of the main station from the main planet

Example:
"station_vector" = "-0.717 -0.668 0.201";

==Stations Require Docking Clearance==

Specifies if a player has to explicit ask docking permission. See also [[Oolite_Docking_Clearance_Protocol_%28v1.72_or_later%29|Oolite Docking Clearance]]

=Properties of the Sun=
;N.B.
The corona effect, modified by the first three properties mentioned below, is disabled by setting ''Reduced Detail:On'' in the game setting menu. ''Enabled'' by default (''Reduced Detail:Off'').

==Corona Flare==

Sets the overall size of the corona in proportion to its sun. (See note above.)

A number from 0.0 (invisibly small) to 1.0 (huge)

Example:
"corona_flare" = "0.075";

==Corona Hues==

Specifies whether the corona should have visible bands of colours within the corona. (See note above.)

A number from 0.0 (monochromatic) to 1.0 (vivid alternating colours).

Example:
"corona_hues" = "0.6";

==Corona Shimmer==

Specifies how quickly the corona colours change. (See note above.)

A number from 0.0 (very slow) to 1.0 (very fast).

Example:
"corona_shimmer" = "0.4";

==Sun Color==

Sets the colour of a system's sun.

Can be any [[Materials in Oolite#Colour specifiers|colour specifier]] or [[Materials in Oolite#Named colours|named colour]]. The specified colour is blended with 50% white so it will never be a saturated colour. Dark colours will be brightened by this blending.

Example:
"sun_color" = "blueColor";

==Sun Distance==
{{oolite-prop-added|1.81}}

Sets the distance between the sun and the main planet in metres.

Example:
"sun_distance" = 924122;

Ignored if sun_distance_modifier is set.

==Sun Distance Multiplier==
{{oolite-prop-added|1.81}}

Multiplies the distance between the sun and the main planet by this factor.

Example:
"sun_distance_multiplier" = 2;

Ignored if sun_distance_modifier is set.

==Sun Distance Modifier==

Sets the approximate distance between a system sun and its main planet. The standard distance is 20 planetary radii. Setting it much lower (10, or even less) will cause delays when generating systems, as Oolite compensates for possible collisions between the sun and other system objects.

Example:
"sun_distance_modifier" = "15.0";

In Oolite 1.81 or later, sun_distance_multiplier is more useful.

== Sun Gone Nova ==

Sets a nova sun in the system.

Example:
"sun_gone_nova" = "YES";

==Sun Name==

Stores the name of a system's sun. This is only implemented in Oolite from version 1.79 onwards, though was used by OXPs before then.

Example:
"sun_name" = "Alpha Centauri";

==Sun Radius==

Sets the radius of a system's sun. A number between 1000 and 1000000.

Example:
"sun_radius" = "100000";

==Sun Vector==
The direction of the sun from the main planet

Example:
"sun_vector" = "-0.717 -0.668 0.201";

=Hyperspace Travel=

In Oolite 1.81 and later these properties have been moved into [[global-settings.plist]]

==Galactic Hyperspace Behaviour==

The key galactic_hyperspace_behaviour controls where the player will arrive after a G.H. has been executed. There are three possible types of G.H. behavior and are as follows:

1) Oolite standard. This is what we have up to this moment. Executing a G.H. jump will poisition the player in the next galaxy, to the closest non-isolated system with regards to their current galaxy coordinates. So, for example, if you jump from coordinates (100, 50) in galaxy 1 you will arrive in galaxy 2 at the same coordinates, unless these coordinates refer to an unreachable system, in which case the arrival point will be adjusted by the engine to maybe something like (102, 51). This is set as default behavior. It is set by assigning the string BEHAVIOUR_STANDARD to the galactic_hyperspace_behaviour key.

2) All systems reachable. Same as above, only this time we do not check for arrival at an isolated system. Using this method, systems like Oresrati in G8, the lower left hand cluster of systems in G7, the two islands of isolated systems in G6 etc. are now possible arrival points. If you land there, you may not be able to exit again, depending on the tech levels of the systems you get to. Mission scripters may want to use this. This behaviour is set by assigning the string BEHAVIOUR_ALL_SYSTEMS_REACHABLE to galactic_hyperspace_behaviour key in planetinfo.plist.

3) Fixed coordinates arrival point. This will make Oolite simulate some older 8-bit versions, that were putting the player in the same fixed point every time a galactic jump was performed, but there is also good potential for scripting (see below). This is set by assigning the string BEHAVIOUR_FIXED_COORDINATES to the galactic_hyperspace_behaviour key.

==Galactic Hyperspace Fixed Coords==

If the fixed coordinates method is chosen, then the engine will look in planetinfo.plist for a key named galactic_hyperspace_fixed_coords, from which it will read the actual coordinates that will be used as the arrival point in the next galaxy. If none is found, then coordinates (96,96) will be used.

==Hyperspace Tunnel Color==

One or two colours can be set, using RGBA format, to over-ride the appearance of the hyperspace tunnel effect.
Example:

hyperspace_tunnel_color_1 = (1.0, 0.0, 0.0, 0.5);
hyperspace_tunnel_color_2 = (0.0, 0.0, 1.0, 0.25);



=Additional Planets=

Finally you can also add keys for your own custom planets and moons, eg.
"LavesPurpleMoon" =
{
...
}

The contents of the { could be:
Orientation of the planet in space (seems not to be working correct)
"orientation" = "0.0 1.0 0.0 0.0";

Position of the planet in space. You can use 3 or 4 parameters. With only 3 parameters the internal absolute coordinates are used.
"position" = "0 -50000 0";
or
"position" = "pwm 0 -50000 0";

Radius of the planet in km. e.g. a value of 500 is drawn with a radius of 5000 meters but in player dialogues this value is presented as 500 km.
"radius" = "500";

Rotation of the planet in rotations per second.
"rotational_velocity" = "1";

The name of the texture file that is used to wrap around the surface.
"texture" = "grid.png";

Seed value used to create the planet's surface features. If no seed is defined it uses the same seed as the main planet, and will create a copy of it.
"seed" = "1 2 3 4 5 6";

A lot of the keys for the main planet, like: '''percent_land''', can also used in custom planets.

== Links ==
*[[Random number generator]] - originally used for creating planet descriptions
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=3860 seed = "1 2 3 4 5 6";]: Psuedo-random number generation & planet descriptions (2007)
*[http://aegidian.org/bb/viewtopic.php?f=4&t=3808 position = "x y z" in planetinfo.plist] (2007)
*Submersible's [https://www.youtube.com/user/submersibletoaster YouTube videos] of planet textures (2012)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=5044 Question: How to add custom planet descriptions] (2008)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20959 Empty system] Removing the stations (and presumably inhabitants) from a system (2021)

[[Category:Oolite]]
[[Category:Oolite scripting]]

Planetinfo.plist

2023-05-04T20:15:15Z

Alnivel: /* About the Inhabitants */ Added the concealment property

'''planetinfo.[[plist]]''' in 'AddOns/Config' contains a dictionary for each of systems for which you wish to set custom data. A list of all galaxies and planets can be found [[Oolite planet list|here]]. Each of the properties mentioned below can be set (but, notably, not the location of the main planet, which is hard coded into the system seed value):

=== Added for Oolite v.1.91 ===
*air_density / or the Javascript planet entity airDensity - see below (pretty picture!)

=== Added for Oolite v.1.89 ===
This needs editing by somebody who understands it! Snatched from the Progress thread
*[http://aegidian.org/bb/viewtopic.php?p=270737#p270737 air_color] now produces the right color for the sky. Not only that, it is now used as the atmosphere scatter color when the planet is viewed from space. Non-blue atmospheres are finally possible!
*[http://aegidian.org/bb/viewtopic.php?p=270771#p270771 air_color_mix_ratio]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 terminator_threshold_vector shipdata key]
*[http://aegidian.org/bb/viewtopic.php?p=271058#p271058 JSPlanet terminatorThresholdVector property]
*[http://aegidian.org/bb/viewtopic.php?p=269833#p269833 MULTIPLIER_LIGHTSRCRADIANCE and MULITPLIER_EXPOSURE]: Planet, ships and atmosphere shaders can now define lightsource radiance and scene exposure multipliers
*Also stuff about city lights
*And probably other stuff I missed!

=Where Settings Apply=

==Universal Settings==

Some options can be applied to the entire universe, such as ambient lighting levels, eg.
"universal" =
{
...
}
Universal options can be over-ridden by specifying the same option for a specific system or location in interstellar space. Obviously, not all options make sense to apply to the whole universe.

==Interstellar Space==

Conditions for interstellar space in general can be set with the “interstellar space” key.

==Specific Systems==

Each system is keyed by a string consisting of the galaxy number (0..7) followed by a space and then the planet number (0..255), eg.
"0 7" =
{
...
}
specifies system 7, in galaxy 0, ''Lave''.

==Specific Interstellar Spaces==

You can also specify a position in interstellar space, eg.
"interstellar: 0 7 129" =
{
...
}
specifies the space in galaxy 0 between systems 7 and 129, ''Lave'' and ''Zaonce''.

In 1.81 the property "link_color" when set on a specific interstellar space changes the colour of the link between the two systems in the advanced navigation array (assuming no route is in place above it).

Note that
"interstellar: 0 7 129" = // jumping from Lave towards Zaonce
{
...
}
and
"interstellar: 0 129 7" = // jumping from Zaonce towards Lave
{
...
}
are distinct locations and if they both need the same properties this must be explicitly set for both. When setting link_color, the lower system ID must be placed first, because of how the chart is drawn.

==Layers==

Settings other than "universal" in Oolite 1.81 or later have a 'layer' property from 0 to 3. The default value for planetinfo.plist files is 1. If multiple OXPs specify a setting for a particular property, the order they will be checked in is:
* Layer 3 settings
* Layer 2 settings (default for Javascript changes to data)
* Layer 1 settings (default for planetinfo.plist)
* Universal settings
* Layer 0 settings (value for core game settings)

This allows OXPs to safely override each other's changes if necessary, and for OXPs which really need a specific setting in a particular system to set it at layer 3

Example
"layer" = 2;

==Terraforming Example==

For the planet Lave, you would use the key '0 7' (planet 7 in galaxy 0) Then you set the values. The following example sets Lave's sea to blue, land to green, and land to sea ratio to 75%.

Code:
{
"0 7" =
{
"percent_land" = "75";
"land_color" = "0.5 1.0 0.5";
"sea_color" = "0.3 0.7 1.0";
}
}

Then you can override any of the settings listed above, for example to change Zaatxe's (Galaxy 0 Planet 8) inhabitants into blue frogs you'd enter

Code:
"0 8" =
{
"inhabitants" = "Blue Frogs";
}

You can use any or all of the keys in each of the entries. It's probably best to only use the key's you want to change. So, another example, to change the sky_blur_xxx settings for Zaonce (Galaxy 0 Planet 129) to big, heavily clustered, but pale blurs - you'd enter

Code:
"0 129" =
{
"sky_blur_cluster_chance" = "0.9";
"sky_blur_alpha" = "0.1";
"sky_blur_scale" = "32.0";
}

=About the Inhabitants=

==Concealment==
{{oolite-prop-added|1.83}}

An integer that determines how much information about the system is unknown.

Example:
"concealment" = "300";
The following values are recognised:
* 0 - default, all information visible
* 100 or more - F7 screen shows no information, economy/government/TL/star colour not visible on chart
* 200 or more - system name is not shown
* 300 or more - system vanishes entirely from chart, will not be used in route plotting, cannot be targeted by player (NPCs can still jump to it, though)

==Government==

0: Anarchy

1: Feudal

2: Multi-Governmental

3: Dictatorship

4: Communist

5: Confederacy

6: Democracy

7: Corporate State

==Economy==

0: Rich Industrial

1: Average Industrial

2: Poor Industrial

3: Mainly Industrial

4: Mainly Agricultural

5: Rich Agricultural

6: Average Agricultural

7: Poor Agricultural

==Tech Level==

An integer between 0 and 14 indicating the sophistication of the planets technology. The tech level displayed on the system data screens in game is one higher than this number (range 1 to 15).

Example:
"techlevel" = "13";

==Population==

An integer between 0 and 67 indicating the number of inhabitants of a planet in hundreds of millions

Example:
"population" = "23";

==Productivity==

An integer indicating the productivity of a planet.

Example:
"productivity" = "1000";

==Name==

The name of the planet.

Example:
"name" = "The planet's name";

==Inhabitant==

The name for one of the inhabitants of the main planet.

Example:
"inhabitant" = "Green Platypus";

==Inhabitants==

The name of the inhabitants of the main planet.

Example:
"inhabitants" = "Green Platypi";

==Description==

A short description of the planet.

Example:
"description" = "Really, anything you want to say about the place!";

==Government Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the government.

Example:
"government_description" = "Dictatorship (Monarchy)";

==Economy Description==
{{oolite-prop-added|1.81}}

Overrides the default text used to describe the economy.

Example:
"economy_description" = "Mainly Industrial (Machine Tools)";

==Population Description==
{{oolite-prop-added|1.77}}

Overrides the default text used to describe the population.

Example:
"population_description" = "13 Billion";

==Random Seed==
{{oolite-prop-added|1.81}}

A seed for a random number generator used in Oolite 1.81 to generate system properties impractical to store in this file (e.g. the positions of each star on the background starfield)

For historical reasons, this is a string of 6 integers between 0 and 255, for example:
random_seed = "74 90 72 2 83 183";

=System population=
These properties are only used in Oolite 1.79 or later.

==Populator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|populate the system]]

Example:
"populator" = "systemWillPopulate";

==Repopulator==

The name of the worldscript function which will be used to [[Oolite_System_Populator|repopulate the system]]

Example:
"repopulator" = "systemWillRepopulate";

=Properties of the Planet=

Most of these properties are ignored if a planet texture is set.

Note that the available planet texture generator properties changed in places between Oolite 1.77 and Oolite 1.80

==Atmosphere Rotational Velocity==

Sets how fast the atmosphere is rotating. (A random value between 0.0 to 0.03 is the default).

Example:
"atmosphere_rotational_velocity" = "0.1";

==Cloud Alpha==
{{oolite-prop-added|1.77}}

The transparency level of the cloud layer, relative to the standard transparency. 1.0 is the default. Texture packs which include clouds on the planetary texture may wish to reduce this.

Example:
"cloud_alpha" = "0.2";

==Has Atmosphere==
{{oolite-prop-added|1.81}}

This boolean property is used for the main planet only. If it is unset or true, the main planet has an atmosphere, as is always the case in 1.80 and before. If it is set to be false, then the planet will not have an atmosphere.

Example:
"has_atmosphere" = 0;

This has no effect on secondary planets - their atmosphere is determined by whether addition uses <code>addPlanet</code> or <code>addMoon</code>.

[[File:AtmDensityExample.png|thumb|320px|right|Atmosphere Density examples: Stranger's ''FPO Lave'' in four increasing atmosphere densities: 0.2, 0.5, 0.75 and 1.0. Every other parameter in the planet definition is the same in all pictures.]]
== Atmosphere Density ==
{{oolite-prop-added|1.91}}
Added by an ignoramus - needs editing by one of our cognoscenti
See [http://aegidian.org/bb/viewtopic.php?p=272721#p272721 another_commander » Sun Nov 22, 2020 2:26 pm]
In tomorrow's nightly we will have a little upgrade in the planet properties: atmosphere density.

Some planets can be made to have denser atmosphere than others. This will allow for more variety in planets' appearance. To achieve this, you can use either the planetinfo.plist property air_density or the Javascript planet entity airDensity. The accepted value range is from 0.0 to 1.0 and anything outside of this range will be automatically clamped. We default all planets to 0.75 in the core.

==Land Color==

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Percent Cloud==
The percentage of the planet's atmosphere occupied by clouds.

Example:
"percent_cloud" = "0..100";

Note that with a low cloud_alpha setting not all of the clouds defined here may actually be visible

==Percent Ice==
The percentage of the planet occupied by the polar ice caps. Oolite 1.81 or later.

Example:
"percent_ice" = "0..100";

==Percent Land==
The percentage of the planet occupied by land.

Example:
"percent_land" = "0..100";

==Planet Distance==
(1.81 or later)

The distance from the centre of the planet to the witchpoint. Only used for the system main planet - secondary planets are positioned separately.

Example
"planet_distance" = "410000";

The main planet is always positioned on the z-axis.

==Planet Name==
{{oolite-prop-added|1.79}}

The planet's name. For the main planet, this defaults to being the same as the system name - the property is mainly intended for secondary planets.

Example
"planet_name" = "Earth";

==Polar Land Color==
{{oolite-prop-added|1.81}}

Sets the land colour in polar regions.

Example:
"land_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Polar Sea Color==
{{oolite-prop-added|1.81}}

Sets the sea colour in polar regions.

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Radius==
An integer between 3000 and 7000 indicating the radius of the main planet. On the F7 screen, this is measured in kilometres. The radius in game is 1/100th of this.

Example:
"radius" = "5500";

==Rotational Velocity==
A number describing the rotational velocity of the planet in radians per second. Overrides rotation_speed if both are set.

Example:
"rotational_velocity" = 0.0015;

==Rotation Speed==
A number describing the rotational velocity of the planet in radians per second. Unlike rotational_velocity, this is affected by rotation_speed_factor.

Example:
"rotation_speed" = 0.0015;

==Rotation Speed Factor==
The rotational speed of all planets whose rotational speed was set by rotation_speed and not by rotational_velocity will be multiplied by this number.

Example:
"rotation_speed_factor" = 1.0;

(Intended more for the universal section as a "personal taste" option than for individual planets)

==Sea Color==

Example:
"sea_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Texture==
The replacement texture to be used by a system's main planet.<br>

For textures you can use lat-long maps (twice as wide as high) with a special elongation at the poles or cube maps. Other maps also will be wraped around planets but give always distortions.<br>
Since Oolite 1.74 you can also use cube maps for planets. Cube maps are 6 times higher as wide and will be recognised automatic by Oolite, based on its dimensions. Cube maps are the preferred method because lat-long give some distortion and have the poles improperly placed in Oolites implementation. See also [[Planettool]] for conversion from lat-long into cube maps.

From Oolite 1.89 onwards, illumination mapping on custom planets is supported. The illumination map goes in the diffuse map's alpha channel. Low alpha values translate to high illumination. This allows for effects like city lights on a planet's dark side.

Example:
"texture" = "newPlanetTexture.png";
;N.B.
The illumination mapping feature is disabled by setting ''Graphics Detail: Shaders Enabled'' or lower in the game setting menu. ''Enabled'' at ''Graphics Detail: Extra Detail''.

==Texture HSB Color==
This changes the overall hue of the replacement texture.

Example:
"texture_hsb_color" = "0.0..1.0 0.0..1.0 0.0..1.0";

==Texture NormSpec==
(Oolite v1.89 and higher). The external texture that will be used as a normal and specular map for the given planet. Colorspace should be linear, with the normal map in the r,g and b and the specular map in the a channel. The texture can be of either equirectangular or cubemap formats. This feature is available at the Extra Detail setting only. To set:
"texture_normspec" = "planetNormalAndSpecularMap.png";

=Properties of the Sky=

==Ambient Level==

Sets how much ambient light (shed by stars and nebulae) illuminates the dark side of objects like planets and ships. Values should typically be between 0.0 and 1.0 (1.0 is the default) but can be higher for a flat lit, cartoon-like effect.

Example:
"ambient_level" = "0.0";

==Nebula Count Multiplier==
This is used for defining the number of nebulas. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"nebula_count_multiplier" = "1.5";

==Sky Blur Alpha==
Default 0.1

Example:
"sky_blur_alpha" = "0.0 .. 1.0";

==Sky Blur Cluster Chance==
This is used for creating nebulae (typically 0.80)

Example:
"sky_blur_cluster_chance" = "0.85";

==Sky Blur Scale==
Default 10. Larger numbers generate bigger nebula, but slow down the game considerable on slower machines.

Example:
"sky_blur_scale" = "0.0 .. 128.0 or more";

==Sky N Blurs==
This is used for defining the number of nebulas (typical is 80, maximum is 1280). This key is multiplied by a "nebula_count_multiplier" definition in Oolite 1.81 or later.

Example:
"sky_n_blurs" = "800";

==Sky N Stars==
This is used for defining the number of stars (typical = 600, maximum in 1.76 or earlier is 4800). This key is multiplied by a "star_count_multiplier" definition in Oolite 1.81 or later. In reduced detail mode, this number will be capped to 2400.

Example:
"sky_n_stars" = "1200";

==Sky and Nebula RGB Colors==

These are rgb values (from 0.0 to 1.0) for the two colours between which the colour of the stars (and nebulaesque blurs) vary, ordered r1 g1 b1 r2 g2 b2 where (r1 g1 b1) defines the first colour and (r2 g2 b2) the second.<br>
(Default values are "0.75 0.8 1.0 1.0 0.85 0.6")

Example:
"sky_rgb_colors" = "0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0 0.0..1.0";

Alternatively, two [[Materials in Oolite#Colour specifiers|colour specifiers]] may be used:
"sky_color_1" = "redColor";
"sky_color_2" =
{
"hue" = "60";
"brightness" = "0.8";
}

"nebula_color_1" = "greenColor";
"nebula_color_2" = "blueColor";

==Star Count Multiplier==
This is used for defining the number of stars. Default is 1.0. Number can be greater or less than default and is also randomised a bit.

Example:
"star_count_multiplier" = "0.5";

=Properties of the Station=

==Market==
The market to be used in this system as the default market. It points to a key in commodities.plist

Example:
"market" = "rockhermit";
Will use the rockhermit market as default for for all stations in the system. When no market is defined a key in commodities.plist is used that matches the role of the main station. Than that is not defined, the default market is used in this system.

In 1.81 and later, this is replaced by market_script

==market_script==
{{oolite-prop-added|1.81}}

A Javascript file used to load a [[Oolite Market Scripts|market script]] for global system price and quantity modifications.

"market_script" = "myoxp_newsystemmarket.js";

==Station==
The type of station orbiting the main planet.

Example:
"station" = "coriolis..dodec..special";

==Station Roll==
The speed at which the station rotates (as with all rotational velocities this is in radians per second) and affects all rotating stations in a system. For a specific station you can use the key [[Shipdata.plist#station_roll | station_roll]] in shipdata.plist.

Example:
"station_roll" = "0.5";

==Station Vector==
The direction of the main station from the main planet

Example:
"station_vector" = "-0.717 -0.668 0.201";

==Stations Require Docking Clearance==

Specifies if a player has to explicit ask docking permission. See also [[Oolite_Docking_Clearance_Protocol_%28v1.72_or_later%29|Oolite Docking Clearance]]

=Properties of the Sun=
;N.B.
The corona effect, modified by the first three properties mentioned below, is disabled by setting ''Reduced Detail:On'' in the game setting menu. ''Enabled'' by default (''Reduced Detail:Off'').

==Corona Flare==

Sets the overall size of the corona in proportion to its sun. (See note above.)

A number from 0.0 (invisibly small) to 1.0 (huge)

Example:
"corona_flare" = "0.075";

==Corona Hues==

Specifies whether the corona should have visible bands of colours within the corona. (See note above.)

A number from 0.0 (monochromatic) to 1.0 (vivid alternating colours).

Example:
"corona_hues" = "0.6";

==Corona Shimmer==

Specifies how quickly the corona colours change. (See note above.)

A number from 0.0 (very slow) to 1.0 (very fast).

Example:
"corona_shimmer" = "0.4";

==Sun Color==

Sets the colour of a system's sun.

Can be any [[Materials in Oolite#Colour specifiers|colour specifier]] or [[Materials in Oolite#Named colours|named colour]]. The specified colour is blended with 50% white so it will never be a saturated colour. Dark colours will be brightened by this blending.

Example:
"sun_color" = "blueColor";

==Sun Distance==
{{oolite-prop-added|1.81}}

Sets the distance between the sun and the main planet in metres.

Example:
"sun_distance" = 924122;

Ignored if sun_distance_modifier is set.

==Sun Distance Multiplier==
{{oolite-prop-added|1.81}}

Multiplies the distance between the sun and the main planet by this factor.

Example:
"sun_distance_multiplier" = 2;

Ignored if sun_distance_modifier is set.

==Sun Distance Modifier==

Sets the approximate distance between a system sun and its main planet. The standard distance is 20 planetary radii. Setting it much lower (10, or even less) will cause delays when generating systems, as Oolite compensates for possible collisions between the sun and other system objects.

Example:
"sun_distance_modifier" = "15.0";

In Oolite 1.81 or later, sun_distance_multiplier is more useful.

== Sun Gone Nova ==

Sets a nova sun in the system.

Example:
"sun_gone_nova" = "YES";

==Sun Name==

Stores the name of a system's sun. This is only implemented in Oolite from version 1.79 onwards, though was used by OXPs before then.

Example:
"sun_name" = "Alpha Centauri";

==Sun Radius==

Sets the radius of a system's sun. A number between 1000 and 1000000.

Example:
"sun_radius" = "100000";

==Sun Vector==
The direction of the sun from the main planet

Example:
"sun_vector" = "-0.717 -0.668 0.201";

=Hyperspace Travel=

In Oolite 1.81 and later these properties have been moved into [[global-settings.plist]]

==Galactic Hyperspace Behaviour==

The key galactic_hyperspace_behaviour controls where the player will arrive after a G.H. has been executed. There are three possible types of G.H. behavior and are as follows:

1) Oolite standard. This is what we have up to this moment. Executing a G.H. jump will poisition the player in the next galaxy, to the closest non-isolated system with regards to their current galaxy coordinates. So, for example, if you jump from coordinates (100, 50) in galaxy 1 you will arrive in galaxy 2 at the same coordinates, unless these coordinates refer to an unreachable system, in which case the arrival point will be adjusted by the engine to maybe something like (102, 51). This is set as default behavior. It is set by assigning the string BEHAVIOUR_STANDARD to the galactic_hyperspace_behaviour key.

2) All systems reachable. Same as above, only this time we do not check for arrival at an isolated system. Using this method, systems like Oresrati in G8, the lower left hand cluster of systems in G7, the two islands of isolated systems in G6 etc. are now possible arrival points. If you land there, you may not be able to exit again, depending on the tech levels of the systems you get to. Mission scripters may want to use this. This behaviour is set by assigning the string BEHAVIOUR_ALL_SYSTEMS_REACHABLE to galactic_hyperspace_behaviour key in planetinfo.plist.

3) Fixed coordinates arrival point. This will make Oolite simulate some older 8-bit versions, that were putting the player in the same fixed point every time a galactic jump was performed, but there is also good potential for scripting (see below). This is set by assigning the string BEHAVIOUR_FIXED_COORDINATES to the galactic_hyperspace_behaviour key.

==Galactic Hyperspace Fixed Coords==

If the fixed coordinates method is chosen, then the engine will look in planetinfo.plist for a key named galactic_hyperspace_fixed_coords, from which it will read the actual coordinates that will be used as the arrival point in the next galaxy. If none is found, then coordinates (96,96) will be used.

==Hyperspace Tunnel Color==

One or two colours can be set, using RGBA format, to over-ride the appearance of the hyperspace tunnel effect.
Example:

hyperspace_tunnel_color_1 = (1.0, 0.0, 0.0, 0.5);
hyperspace_tunnel_color_2 = (0.0, 0.0, 1.0, 0.25);



=Additional Planets=

Finally you can also add keys for your own custom planets and moons, eg.
"LavesPurpleMoon" =
{
...
}

The contents of the { could be:
Orientation of the planet in space (seems not to be working correct)
"orientation" = "0.0 1.0 0.0 0.0";

Position of the planet in space. You can use 3 or 4 parameters. With only 3 parameters the internal absolute coordinates are used.
"position" = "0 -50000 0";
or
"position" = "pwm 0 -50000 0";

Radius of the planet in km. e.g. a value of 500 is drawn with a radius of 5000 meters but in player dialogues this value is presented as 500 km.
"radius" = "500";

Rotation of the planet in rotations per second.
"rotational_velocity" = "1";

The name of the texture file that is used to wrap around the surface.
"texture" = "grid.png";

Seed value used to create the planet's surface features. If no seed is defined it uses the same seed as the main planet, and will create a copy of it.
"seed" = "1 2 3 4 5 6";

A lot of the keys for the main planet, like: '''percent_land''', can also used in custom planets.

== Links ==
*[[Random number generator]] - originally used for creating planet descriptions
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=3860 seed = "1 2 3 4 5 6";]: Psuedo-random number generation & planet descriptions (2007)
*[http://aegidian.org/bb/viewtopic.php?f=4&t=3808 position = "x y z" in planetinfo.plist] (2007)
*Submersible's [https://www.youtube.com/user/submersibletoaster YouTube videos] of planet textures (2012)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=5044 Question: How to add custom planet descriptions] (2008)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20959 Empty system] Removing the stations (and presumably inhabitants) from a system (2021)

[[Category:Oolite]]
[[Category:Oolite scripting]]

File:Sector7 The Lizard's Claw RegionMap.png

2023-04-20T20:47:26Z

Alnivel: Alnivel uploaded a new version of File:Sector7 The Lizard's Claw RegionMap.png

File:Sector7 The Lizard's Claw RegionMap.png

2023-04-20T20:39:29Z

Alnivel: Alnivel uploaded a new version of File:Sector7 The Lizard's Claw RegionMap.png

Sector7/The Lizard's Claw (Region)

2023-04-20T20:22:54Z

Alnivel: Fixed links on the map

== Origin ==
Why is it called the Lizard's Claw? Go ask the lizards of Gebeti.

== Map ==
[[Sector7/The Lizard's Claw (Region)|The Lizard's Claw]] consists of the systems [[Sector7/Anisinza|Anisinza]], [[Sector7/Ceraso|Ceraso]], [[Sector7/Ceerti|Ceerti]] and [[Sector7/Gebeti|Gebeti]].



<div style="position:relative">{{ClickMapHeader|Sector=7|Image=Sector7_The_Lizard's_Claw_RegionMap.png}}
{{ClickMapEntry|Name=Anisinza|Sector=7|XPos=19|YPos=14|XPosRel=58|YPosRel=22}}
{{ClickMapEntry|Name=Ceraso|Sector=7|XPos=13|YPos=1|XPosRel=40|YPosRel=3}}
{{ClickMapEntry|Name=Ceerti|Sector=7|XPos=1|YPos=9|XPosRel=4|YPosRel=15}}
{{ClickMapEntry|Name=Gebeti|Sector=7|XPos=0|YPos=15|XPosRel=1|YPosRel=24}}
{{ClickMapFooter}}</div>


{{SectorTableHeader}}
{{SectorTableEntry|Name=Anisinza|Sector=7|System=90|XPos=19|YPos=14|Government=3|Economy=6|Techlevel=7|Population=3.4|Inhabitants=Human Colonists|Productivity=7616|Hubcount=2|Description=The world Anisinza is scourged by deadly disease.}}

{{SectorTableEntry|Name=Ceraso|Sector=7|System=113|XPos=13|YPos=1|Government=5|Economy=1|Techlevel=11|Population=4.7|Inhabitants=Fierce Yellow Fat Humanoids|Productivity=30456|Hubcount=3|Description=The planet Ceraso is reasonably fabled for its exciting sit coms and its inhabitants' exceptional love for food blenders.}}

{{SectorTableEntry|Name=Ceerti|Sector=7|System=62|XPos=1|YPos=9|Government=1|Economy=3|Techlevel=7|Population=3.5|Inhabitants=Fierce Slimy Frogs|Productivity=8120|Hubcount=2|Description=This world is a revolting little planet.}}

{{SectorTableEntry|Name=Gebeti|Sector=7|System=126|XPos=0|YPos=15|Government=1|Economy=7|Techlevel=2|Population=1.3|Inhabitants=Large Green Lizards|Productivity=1560|Hubcount=2|Description=Gebeti is very fabled for its ancient Gebetian Et banana plantations.}}
{{SectorTableFooter}}

== Lore ==
Tucked away in the northwest corner of the seventh octant are the four worlds which comprise The Lizard's Claw. The only way into The Claw (as the locals call it) is via Maarbi, 6.4 lyrs from Anisinza. To say it's an unpopular sector would be fair, but try telling that to the humanoids, frogs, and lizards who inhabit Ceraso, Ceerti, and Gebeti respectively. The colonial inhabitants of Anisinza are far too busy fighting a deadly disease to worry about popularity. Ships refuel and do their business at Anisinza's main station, and move on fast - dirtside excursions are definitely not advisable.

Ceraso has its attractions, especially the entertainment, and is a fairly civilised planet, but don't get into an argument with the locals. Gebeti is renowned for its Et banana plantations and unspoilt countryside. Life on Gebeti, like the ponderous lizards who inhabit it, is slow moving.

Ceerti is another matter entirely. It's perhaps unfair to call it a revolting little planet - yes, it's mainly industrial, and like Gebeti it's a feudal world, but much of that industry is underground, and the frogs have a lot of history. The many lakes with their surrounding mountains are well worth a visit, just don't go there during the mating season - then it is that the frogs earn their reputation for being fierce!

A few well-known pilots have made Ceerti their home, and make their living as couriers, taking cross-chart contracts which can be highly lucrative.

== Links ==
[https://postimg.cc/gallery/xdPbyC9 Lizard's Claw gallery] (Cody 2022: The core planets with default cloud levels).

[[Category:Sector7/Region|The Ceraso Hub]]
{{RoutesAndRegionsSector7}}

File:Sector7 The Lizard's Claw RegionMap.png

2023-04-20T19:46:14Z

Alnivel:

Property list

2023-04-14T10:52:31Z

Alnivel: /* dictionary */ Fixed formatting and examples

[[Image:plist-XML-ASCII-ill.png|thumb|right|300px|the plist formats, XML and OpenStep]]
A '''property list''', or '''plist''' for short, is data structured in a standardized way, used by Oolite for a wide variety of configuration files. The concept originates with [http://en.wikipedia.org/wiki/OpenStep OpenStep], the specification on which the Cocoa and GNUstep programming libraries Oolite uses are based.

== Formats ==
A property list is an abstract structure which can be represented files using at least five different formats. Since Oolite uses two different implementations of property list support, one on Mac OS X and another on other platforms, it can’t consistently read all these formats.

Two formats are recommended for Oolite: the traditional [http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/PropertyLists/Introduction/Introduction.htmll OpenStep format], which is easy to read, and the [http://developer.apple.com/documentation/Cocoa/Conceptual/PropertyLists/Articles/XMLPListsConcept.html XML format], which is more flexible. The other formats are Apple binary format (which can be read by both implementations, but is not human-readable), and the GNUstep text and binary formats, which are not supported under Mac OS X.

While the OpenStep format does not support all the data types used by Oolite – specifically, it does not support [[#integer|integers]], [[#real|reals]] or [[#boolean|booleans]] – Oolite can in most cases automatically convert [[#string|strings]] to these types starting with Oolite 1.69. (If you find an exception, please report it.) As such, the types can be used interchangeably. In prior versions of Oolite, some types, especially booleans, could not be converted automatically, so XML format was required for some property lists.

== Data types ==
The rest of this page describes the types of property list element used by Oolite, and how they are represented in OpenStep and XML format property lists. It does not cover all property list content types or file formats and is not a general-purpose reference to property lists.

=== string ===
A string is a block of text. In OpenStep format plists, this is surrounded by straight double quotation marks, with “<code>\</code>” being used to escape quotation marks within the string: <code>"a string with a \"quotation\" and a <tag>"</code>. OpenStep format plists also allow single-word strings to be used without quotation marks when this is unambiguous. However, the definition of “unambiguous” differs between Mac OS X and GNUstep, so this usage is not recommended except for numbers. In XML format, it is surrounded by <code><string></code> tags, escaping contents with XML entities: <code><string>a string with a &quot;quotation&quot; and a &lt;tag&gt;</string></code>.

=== integer ===
An integer is a whole number. In OpenStep format plists, an integer is a string whose contents happen to be digits (and optionally a minus sign), and may be unquoted: <code>-12345</code>. In XML format, it is surrounded by <code><integer></code> tags: <code><integer>-12345</integer></code>.

=== real ===
A real is a number with a fractional part. In OpenStep format plists, reals are again written as unquoted strings: <code>42.123</code>. In XML format, reals are surrounded by <real> tags: <code><real>42.123</real></code>. Large reals can be expressed in scientific notation: <code>1.35e+20</code> means 1.35 × 10<small><sup>20</sup></small>. Integers and reals are mostly interchangeable in Oolite.

=== boolean ===
A boolean is either of the values ''true'' or ''false''. In XML format, the tags <code><true/></code> and <code><false/></code> can be used. OpenStep format does not support booleans. However, as of Oolite 1.69, a number of different methods can be used to represent them: any of the strings <code>"true"</code>, <code>"yes"</code> or <code>"on"</code> may be used to represent ''true'', and any of the strings <code>"false"</code>, <code>"no"</code> or <code>"off"</code> may be used to represent ''false''. Also the uppercase variants of these keywords can be used as casing is ignored for these booleans. Additionally, the number 0 is interpreted as ''false'' and any other number as ''true'' (but see [[#fuzzy boolean|fuzzy boolean]] below). The recommended form is to use <code>"yes"</code> and <code>"no"</code> to keep a consistent syntax that is not confusing.

Previous versions of this page indicated that numbers could be used as booleans in OpenStep-format property lists in any version of Oolite. This is incorrect and such usage will not work with versions prior to 1.69.

=== fuzzy boolean ===
A fuzzy boolean isn't really a property list type; rather, it's a special usage defined by Oolite. If a fuzzy boolean is expected, and a number is encountered, it is treated as a probability between 0 and 1. For instance, if a value of 0.5 is used, it will be treated as ''true'' half the time, and ''false'' the other half. Values other than numbers are treated like [[#boolean|booleans]].

=== array ===
An array is an ordered list of objects.

In '''OpenStep format''', an array is contained in parentheses, with items separated by commas: <code>(0, two, "three and a half", yes)</code>.
You can have several values without name, and they are grouped using round brackets:

(
value1,
value2,
value3
)

''Note that between two values there is a comma.''

In '''XML format''', it is contained in <code><array></code> tags: <code><array><integer>0</integer> <string>two</string> <string>three and a half</string> <true/></array></code>.

Later the values are just accessed by numbers: The first, the second, the next, the last, ...

Now the part that can make plist files really complex: Wherever you place a value, it can be a primitive one (a number, a string, a boolean value like true/false) or a complex value such as an array or a dictionary. And with this you can create all the complex structures you perceive when looking at Oolite's plist files.

=== dictionary ===
Dictionaries are the most complex type. They consist of key/value pairs – each pair consists of a key, which is always a string, and a value, which can be any type, including other dictionaries. Each key must be unique, and the order of pairs is not significant. Again, every value has a name or a key.

In '''OpenStep format''', dictionaries are contained in braces, with key and value separated by <code>=</code> signs and each pair followed by a semicolon:

{
"name1" = "value1";
"name2" = "value2";
}

Not all names have to go into quotes, and not all values require them. But you need to watch out where you place them and where not.

{
length = 42;
width = 36.5;
"long name" = "this is a thing with a really quite long name"; // ''note: quotes for a key with spaces are required''
attributes = ("hairy", "muscular"); // ''note: this is actually an '''array''' of string values following the key''
}


In '''XML format''', dictionaries are contained in
<code><dict></code> tags,</br>
with keys specified by <code><key></code> tags </br>
and immediately followed by values with whatever tag is appropriate for the value type:
<dict>
<key>length</key>
<integer>42</integer>
<key>width</key>
<real>36.5</real>
<key>long name</key>
<string>this is a thing with a really quite long name</string>
<key>attributes</key>
<array>
<string>hairy</string>
<string>muscular</string>
</array>
</dict>

== Root element ==
Every property list has a single value as its root. Typically this is a dictionary. In XML format, the root value must be surrounded by <code><plist></code> tags in addition to its normal type tag: <code><plist> <dictionary> <key>green</key> <array> <integer>0</integer> <integer>1</integer> <integer>0</integer> </array> </dictionary> </plist></code> (OpenStep equivalent: <code>{ green = (0, 1, 0); }</code>).

Under Mac OS X, if the root element of an OpenStep-format property list is a dictionary, it does not have to be surrounded by braces. However, ''this does not work under GNUstep'', so those creating property lists on Macs must be careful. In particular, OpenStep-format property lists exported by Property List Editor may not work under GNUstep.

== Comments ==
Both formats can also contain comments, which are ignored by the program but are useful to human readers. In OpenStep format, these can either start with “<code>//</code>” and continue to the end of the line, or start with “<code>/*</code>” and end with “<code>*/</code>”. In XML, they start with “<code></code>” (and must not contain “<code>--</code>” anywhere else in the comment).

Examples:
/* this line is a comment in OpenStep format */
// this line is also a comment in OpenStep format

<nowiki></nowiki>

== XML Preamble ==
XML plists also need a standard header, which looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "<nowiki>http://www.apple.com/DTDs/PropertyList-1.0.dtd</nowiki>">

== Real-world Example ==
The following is a shortened version of Oolite’s built-in ''[[equipment.plist]]'', in both OpenStep and XML formats.

=== OpenStep ===
(
(
1, 300, "Missile", "EQ_MISSILE",
"Faulcon de Lacy HM3 homing missile, fast and accurate when used in conjunction with standard targetting scanners.",
{
available_to_all = "yes";
}
),
(
7, 9000, "Energy Bomb", "EQ_ENERGY_BOMB",
"A one-shot super-weapon capable of destroying all small craft within range."
)
)

The round brackets are arrays in OpenStep, and are used to group information for a given key. Examples are the exhaust (if one has multiple ones for a given ship), the individual custom views and sub-entities...

The curly brackets make up dictionaries, which tie together different keys on the same subject. The two main examples there are the overall entries themselves (each ship is made up of a dictionary of keys describing it) and the external views (a dictionary of individual views, each of which is defined as an array of keys describing that given view).

One would recommend using a programmer-friendly editor like notepad++ or an equivalent. On N++ if you select an open or closing bracket (of whichever flavour) it will automatically highlight the other part of the pair and link them. It's useful for quickly checking that you have your pairs correct - a good habit to get into. And in many cases the kind of log error one sees is indicative of missing brackets. Those and missing quotes and semi-colons are arguably the three most common errors in openStep plists if one excludes typo's. [http://aegidian.org/bb/viewtopic.php?p=153556#p153556 Thargoid] (2011)

=== XML ===
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" <nowiki>"http://www.apple.com/DTDs/PropertyList-1.0.dtd"</nowiki>>
<plist version="1.0">
<array>
<array>
<integer>1</integer>
<integer>300</integer>
<string>Missile</string>
<string>EQ_MISSILE</string>
<string>Faulcon de Lacy HM3 homing missile, fast and accurate when used in conjunction with
standard targetting scanners.</string>
<dict>
<key>available_to_all</key>
<true/>
</dict>
</array>
<array>
<integer>7</integer>
<integer>9000</integer>
<string>Energy Bomb</string>
<string>EQ_ENERGY_BOMB</string>
<string>A one-shot super-weapon capable of destroying all small craft within range.</string>
</array>
</array>
</plist>

== Conversion ==
Technically the XML plists are the best, but they are only fully supported on Mac systems. Without a plist editor, the plists are not as easy to read or write as OpenStep plists. However, those editors are only easily available for the Mac. Windows and Linux users will have to rely on text editors to edit those plists. Therefore it is advised to write everything in open step format.

Converting xml to open step can be done by a python script, written by Cdr. Jettison: [http://www.box.net/shared/g79rnfx4jcp1do35liin download python conversion script] ('' xml plist must be free of comment for the script to work'')

Note that this conversion script contains CR/LF (carriage return/linefeed) end-of-lines, as used on Windows computers. This will cause ''"bad interpreter: No such file or directory"'' errors if run on Linux. You can strip out the CR characters yourself, or download this [https://www.box.com/s/n06cixgjxsxmph2drucz copy of the script which has already had the CRs removed]. (you will also need to make the script executable)

==Links==
* [http://aegidian.org/bb/viewtopic.php?f=2&t=10039 BB discussion] about converting plists (2011-21)
* [http://oolite.aegidian.org/bb/viewtopic.php?f=2&t=6836 earlier conversion discussion] (2009)
* [[OXP howto]]
* [[OXP howto plist]] has a section on finding and fixing errors
* [http://aegidian.org/bb/viewtopic.php?f=2&t=10949 Property List problems] (2011) - mostly XML, some OpenStep

[[Category:Oolite]]
[[Category:Legacy scripting]]
[[Category:Oolite scripting]]

Oolite JavaScript Reference: Condition scripts

2023-04-10T14:14:41Z

Alnivel: /* allowAwardEquipment */ Added how to add "oolite-barred-equipment" support for oxp equipment

== Condition scripts ==
Condition scripts are used to set conditions on the appearance of ships and equipment beyond the basics possible in [[shipdata.plist]], [[shipyard.plist]], [[shiplibrary.plist]] and [[equipment.plist]]. They have a similar purpose to the "conditions" parameters in those plists, which use the legacy scripting engine, but have the full flexibility of the Javascript scripting engine. If both "conditions" and a condition script are specified for the same item, they will both be tested (but you should never need to do this).

Conditions scripts may define any or all of the following methods. There is a single instance of each condition script regardless of how many ships and equipment items use it, so variables may be shared between calls in <code>this._property</code>

In 1.81 the scripts are extended slightly to modify ''how'' things may appear as well as whether they may appear.

=== allowAwardEquipment ===
{{oolite-method-added|1.77}}

In order for this method to be called, the <code>condition_script</code> property of an equipment item (as declared in the [[Equipment.plist]] file) must be specified, it must declare the name of the Javascript file where the method exists, and the method must exist in the referenced JavaScript file. The method will only be called for the equipment items which reference the condition script.

This method is called when the game engine needs to know whether a particular ship can have equipment fitted. In other words, it is asking whether to allow equipment to be awarded to a ship. This may be because the player is looking at possible upgrades at a station (on the F3 Equip Ship screen), or from a call to [[Oolite_JavaScript_Reference:_Ship#canAwardEquipment|ship.canAwardEquipment]] or [[Oolite_JavaScript_Reference:_Ship#canAwardEquipment|ship.awardEquipment]], or for other similar reasons. The equipment key and a reference to the ship entity are passed as parameters. You would use this method to control if, and under what conditions, a piece of equipment is offered for purchase and installation. Returning a value of <code>true</code> would indicate that the equipment can be installed; returning a value of <code>false</code> indicates the equipment can't be installed and so it won't appear on the F3 Equip Ship screen, and any of the JavaScript methods to add the equipment item would fail. If the method does not exist, or returns a value other than <code>false</code>, then a value of <code>true</code> is assumed and the equipment may be added or offered for sale (subject to other conditions, of course, like TL constraints)

<code>context</code> will be one of:
* <code>"newShip"</code> - equipment for a ship in a station shipyard (F3 F3)
* <code>"npc"</code> - awarding equipment to NPC on ship setup
* <code>"purchase"</code> - equipment for purchase on the F3 screen
* <code>"scripted"</code> - equipment added by JS or legacy scripts
(Context can in theory also be <code>"loading"</code>, <code>"damage"</code> or <code>"portable"</code>, but if you see one of these, it's a bug)

this.allowAwardEquipment = function(eqKey, ship, context)
{
// your code here
return bool;
}

The standard condition script for the core game equipment allows equipment to be barred using the <code>"oolite-barred-equipment"</code> key in <code>script_info</code>. If this key contains an array of equipment keys, then those items of equipment will not be sold at this station. In 1.79 and later, this <code>script_info</code> key may be applied to any ship, preventing those items being installed onto the ship. For example:

script_info = {
"oolite-barred-equipment" = ("EQ_WEAPON_MILITARY_LASER");
}

On a station, this would prevent it selling military lasers. On a ship in 1.79 or later, this would also stop the ship fitting military lasers.

If you want to allow your equipment to be barred in the same way, you can either set the <code>condition_script</code> property to use the standart <code>"oolite-conditions.js"</code> script, or add the following snippet to the <code>allowAwardEquipment</code> of your condition script:
// OXP hook to allow stations to forbid specific equipment
if(context == "purchase" && player.ship.dockedStation && player.ship.dockedStation.scriptInfo["oolite-barred-equipment"])
{
if (player.ship.dockedStation.scriptInfo["oolite-barred-equipment"].indexOf(equipment) != -1)
{
return false;
};

// OXP hook to allow ships to forbid specific "available to all" equipment
if(ship.scriptInfo && ship.scriptInfo["oolite-barred-equipment"] && ship.scriptInfo["oolite-barred-equipment"].indexOf(equipment) != -1)
{
return false;
};

=== allowOfferShip ===
{{oolite-method-added|1.77}}

This method is called when the game engine is considering adding a ship managed by this condition script to a shipyard. If the method does not exist, or returns a value other than <code>false</code>, then the ship may appear for sale (or it may not, for a variety of other reasons). The ship key from shipyard.plist is passed as a parameter.

this.allowOfferShip = function(shipKey)
{
// your code here
return bool;
}

=== allowShowLibraryShip ===
{{oolite-method-added|1.81}}

This method is called when the ship library is being shown in-game (rather than on the start screen) and determines whether the ship appears on the list for the player to view. If the method does not exist or returns a value which cannot be interpreted as a boolean, it will be assumed to have returned <code>true</code>.

this.allowShowLibraryShip = function(shipKey)
{
// your code here
return bool;
}

=== allowSpawnShip ===
{{oolite-method-added|1.77}}

This method is called when the game engine is considering spawning a ship managed by this condition script. If the method does not exist, or returns a value other than <code>false</code>, then the ship may be spawned (or it may not, if another ship with the appropriate role is selected instead). The ship key from shipdata.plist is passed as a parameter.

this.allowSpawnShip = function(shipKey)
{
// your code here
return bool;
}

=== updateEquipmentPrice ===
{{oolite-method-added|1.81}}

This method is called when the game engine needs to know the price of fitting equipment covered by this condition script. The method takes an equipment key and the current price as parameters, and must return a non-negative number for the actual price of the equipment.

this.updateEquipmentPrice = function(equipmentKey, currentPrice)
{
// your code here
return newPrice;
}

This method is called before [[Shipdata.plist#equipment_price_factor|equipment_price_factor]] is considered.

== Links ==
There is an extended bulletin board discussion with a couple of examples [http://www.aegidian.org/bb/viewtopic.php?p=286037#p286037 here] (2022).

[[Category:Oolite JavaScript Reference]]

Mission screen

2023-02-12T15:47:13Z

Alnivel: /* Tabular layout */ Added picture

{{OXPNote|This Page is a WIP aimed at dumb pilots like myself!}}

[[File:Hints.png|right|320px]]
Mission screens started off as screens which allow the player to interface with NPCs in a mission.oxp. They also allow other sorts of "communication" as in the conversation overheard in the bar in the [[Hints]] OXP.

They can have backdrops, changes in text and allow choices for the player.

The text can be placed in a descriptions.plist, details about it in a script.js (but everything can go in the script.js if so desired).

== Text ==
:Several special spatial characters can be used in determining the layout of the text, just as in this Wiki.
\" Enables the use of colons.
\\n Insert a hard Enter.

In XML:
\n Inserts a hard Enter.

:See [[Missiontext.plist]] for more complexity (''eg'' random names, naming current system ''etc'')

:Character '31' (hex:1F, octal:037) is a narrow 'hair-space'. Custom font OXPs should ensure that this character is blank and has the same narrow width as the core font definition, as it is used to allow an equivalent to 'tab stops' in mission text.

=== % codes ===
Here are the % codes that can be used inside description strings and what each one does:

Code:
* %H is replaced with <planetName>. If systemName is nil, a planet name is retrieved through -[Universe getSystemName:], treating <seed> as a system seed. <br>
* %I is equivalent to "%H[planetname-derivative-suffix]".<br>
* %N is replaced with a random "alien" name using the planet name digraphs. If used more than once in the same string, it will produce the same name on each occurence.
* %R is like %N but, due to a bug, misses some possibilities. Deprecated.
* %JNNN, where NNN is a three-digit integer, is replaced with the name of system ID NNN in the current galaxy.
* %GNNNNNN, where NNNNNN is a six-digit integer, is replaced with the name of system ID NNN (first triplet) in the specified galaxy (second triplet).
* %% is replaced with %.
* %[ is replaced with [.
* %] is replaced with ].
:From [[String expansion]]

== Colour ==
:Choices can be non-yellow (have a look at the various contracts interfaces in 1.77) but there is a more fundamental limitation of the current UI code that all text on a particular line has to be the same colour. [http://www.aegidian.org/bb/viewtopic.php?p=203777#p203777 Cim (2013)]

:Code for [http://www.aegidian.org/bb/viewtopic.php?p=283402#p283402 Colour change]

[[File:First Finance Loan Management.png|right|300px]]
== Alignment ==
There is no obvious way to do this, but [[User:Ocz|Ocz]] managed some version of right alignment for his [[First Finance OXP]]

=== Tab stops ===
Although there are no built-in tabs, they can be imitated with some JavaScript. Below you can find some of the basic functions for formating the text, but in various OXPs you can find them under other names, as well as others that can be a way more complex and specialized.
However, their core principle remains the same - they add invisible characters to the string passed to them up to the desired width - just as you can do it in a text editor, by adding spaces you can get (almost) any kind of text tabulation. The functions, however, don't use a rather wide regular space, but a narrow hair space, which allows text to align more accurately.

The unit of text width is em - the intrinsic unit size of a font. The mission screen is 32 em wide and text wider than that will wrap with breaks on spaces. You can measure the width of a string using <code>[[Oolite_JavaScript_Reference:_Global#defaultFont|defaultFont.measureString]]</code>.

Here you can see one of the implementations of <code>_limitText</code>, <code>_padTextLeft</code>, <code>_padTextRight</code> and <code>_padTextAround</code> functions. Feel free to use it in your work!
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
/**
* The function cuts text to limitWidth if necessary, and adds an ellipsis in this case.
* It's useful when you want to display text that may be larger than the available space, such as ship names.
* Large text, if left unprocessed, can make the rest of the formatting go haywire.
*
* text - the string to make sure that it won't be longer than limitWidth
* limitWidth - the maximum width of the result, in ems
* result - the limited string
*/
this._limitText = function _limitText(text, limitWidth) {
const ellipsis = "…";

var tmp = text;

while (defaultFont.measureString(tmp) > limitWidth) { // until text in wider than limit
// remove from the text two last characters and add an ellipsis
// two because we need to remove an ellipsis from previous iteration
tmp = tmp.substring(0, tmp.length - 2) + ellipsis;
}

return tmp;
}

/**
* The functions below add hair spaces to the text to make it have a desiredWidth,
* but in case if text is too wide, the function do the _limitText instead.
*
* To reduce the duplication of code they all just shorcuts for more generic _padText
*
* text - the string that we want to have a desiredWidth
* desiredWidth - the width of the result, in ems
* result - the padded string
*/
this._padTextLeft = function _padTextLeft(text, desiredWidth) {
return this._padText(text, desiredWidth, "left");
}

this._padTextRight = function _padTextRight(text, desiredWidth) {
return this._padText(text, desiredWidth, "right");
}

this._padTextAround = function _padTextAround(text, desiredWidth) {
return this._padText(text, desiredWidth, "both");
}

/**
* The function add hair spaces to the text to make it have a desiredWidth.
* But in case if text is too wide, the function do _limitText instead.
*
* text - the string that we want to have a desiredWidth
* desiredWidth - the width of the result, in ems
* padSide:
* "left" - add pads before the text
* "right" - add pads after the text
* "both" - add pads both before and after the text
* result - the padded string
*/
this._padText = function _padText(text, desiredWidth, padSide) {
// Keep character and it's width it variables for sake of optimization and clarity
const hairSpace = String.fromCharCode(31);
const hairSpaceWidth = defaultFont.measureString(hairSpace);

// Find out the width of text in ems
const textWidth = defaultFont.measureString(text);

const padsNeeded = Math.floor((desiredWidth - textWidth) / hairSpaceWidth);

var resultText;
if (padsNeeded > 1) {
// new Array(n).join(someString) - the compact way to say "repeat the someString n times"
if (padSide == "left") {
resultText = new Array(padsNeeded).join(hairSpace) + text;
}
else if (padSide == "right") {
resultText = text + new Array(padsNeeded).join(hairSpace);
}
else if (padSide == "both") {
const leftPadsNumber = Math.floor(padsNeeded / 2);
const leftPadding = new Array(leftPadsNumber).join(hairSpace);
const rightPadding = new Array(padsNeeded - leftPadsNumber).join(hairSpace);

resultText = leftPadding + text + rightPadding;
}
}
else {
resultText = this.$limitText(text, desiredWidth);
}

return resultText;
}
</pre>

=== Tabular layout ===
When you need to get something in the form of a table or columns, you can use padText-like functions to adjust the padding of the desired width to labels and data, and then concatenate them into one line, just keep in mind that max row length is 32 em.
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
var pad1em = this._padTextLeft("", 1);
var tableHeader = this._padTextLeft("#", 3) + pad1em +
this._padTextRight("Item", 11) + pad1em +
this._padTextAround("Remaining, pcs.", 7) + pad1em +
this._padTextAround("Price, ₢ ", 7) + pad1em;

var tableRows = Array(this.$items.length);
for(var i = 0; i < this.$items.length; i++) {
var item = this.$items[i];
tableRows[i] = this._padTextLeft(i + 1, 3) + pad1em +
this._padTextRight(item.name, 11) + pad1em +
this._padTextAround(item.quantity, 7) + pad1em +
this._padTextLeft(formatCredits(item.price), 7) + pad1em;
}

// Concatenate them in one string if you want to display
// the table as "message" on the mission screen
var table = tableHeader + "\n" + tableRows.join("\n") + "\n\n";
</pre>

[[User:Alaric/KV-16 Owners Manual|Alaric's unfinished Torus-field-monitor OXZ]] contains handy function to help format text in tabular layout for use in mission screens/MFDs. See his alaric-oxp-utilities.js file:
[[File:Alaric's_Tabular_text_for_MDFs_mission_screens.png|right|300px]]
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
"use strict";

this.name = "alaric-oxp-utilities";
this.author = "Alaric";
this.copyright = "2016 Alaric";
this.description = "General helper functions for OXPs";
this.licence = "CC BY-NC-SA 3.0 AU";
this.version = "1.0";

/**
* Trims a length of text to fit in the available width. If the text is truncated,
* an ellipse (U+2026) will be appended unless <ellipses> is false. If <ellipses>
* is omitted from the call, it defaults to true.
*
* text - The text to trim
* emDisplayWidth - The available width, in Em, to display the text
* ellipses - optional (default: true)
*
* Returns the new, trimmed, string.
*/
this._trimTextToFitWidth = function(text, emDisplayWidth, ellipses)
{
var font = defaultFont;
var chPadding = String.fromCharCode(31);
var ellipsesText = "\u2026";
var emEllipsesText = font.measureString(ellipsesText);
var emPaddingText = font.measureString(chPadding);

var chWidth = [0, text.length];
var emWidth = [font.measureString(text), 0];

// use default for ellipses if not supplied
if (ellipses === null || ellipses === undefined) ellipses = true;

// if the text already fits, just return it.
if (emWidth[0] <= emDisplayWidth) return text;

// if the display width is too short for ellipses, disable ellipses
if (emEllipsesText >= emDisplayWidth) ellipses = false;

// subtract ellipses with from display width if ellipses is true
emDisplayWidth -= (ellipses) ? emEllipsesText : 0;

while (chWidth[0] != chWidth[1])
{
// get Em width of text at length midway between chWidth[0] and chWidth[1]
var chPivot = Math.ceil((chWidth[0] + chWidth[1]) / 2);
var emPivot = font.measureString(text.substring(0, chPivot));

// update for next split point based on the text being too long or too short
var flagDirection = (emPivot <= emDisplayWidth) ? 0 : 1;

chWidth[flagDirection] = chPivot - flagDirection;
emWidth[flagDirection] = emPivot;
}

// At this point, chWidth[0] and emWidth[0] contain the trimmed width in
// characters and Em respectively. Return the text, appending ellipses if
// <ellipses> is true. The space for ellipses has already been accounted
// for.

return (ellipses)
? text.substring(0, chWidth[0]) + ellipsesText
: text.substring(0, chWidth[0])
;
}

/*
* Builds tabular (columns aligned) text for use in mission screens/MFDs.
*
* Input to the function is provided by an array of 'rows'. Each row is, itself, an array of
* objects with the following properties:
*
* Required properties:
* text: The text to display in this column
* width: The width of the column in em. Text will be truncated if too long.
*
* Optional properties:
* alignment: LEFT, RIGHT or CENTER. Default: LEFT
* elipses: Display elipses for truncated text? Default: true.
* blink:
*
* Multiple rows are deliniated by '\n'. No '\n' is appended to the last row.
*
*/
this._buildTabularText = function(rows)
{
var padCharacter = String.fromCharCode(31);
var padWidth = defaultFont.measureString(padCharacter);
var tabularText = "";
var row;

for (row = 0; row < rows.length; ++row)
{
if (row > 0) tabularText += "\n";

var i;

var currentEm0 = 0;
var currentEm1 = 0;
var columns = rows[row];
var rowText = "";

for (i = 0; i < columns.length; ++i)
{

currentEm0 = defaultFont.measureString(rowText);
var leading = (currentEm1 - currentEm0);
currentEm1 = currentEm1 + columns[i].width;

var text = this._trimTextToFitWidth(columns[i].text, currentEm1 - currentEm0, columns[i].ellipses);
var width = defaultFont.measureString(text);

var padding = (currentEm1 - currentEm0) - width;

switch ((columns[i].alignment !== undefined) ? columns[i].alignment : "LEFT")
{

case "LEFT" : padding = 0; break;
case "RIGHT" : leading = 0; break;
case "CENTER" : padding = padding / 2; break;

default:
log(this.name, "invalid alignment '" + columns[i].alignment + "'");
padding = 0; break;

}

padding = Math.floor((leading + padding) / padWidth);

rowText += (padding >= 1)
? new Array(padding).join(padCharacter) + text
: text
;
}

tabularText += rowText;
}

return tabularText;
}
</pre>

You can use it like this:
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
var rows = [
[ /* header */
{ width: 32, alignment: "CENTER", text: "Fleet status" }
],

[ /* line spacer */
],

[ /* row 1 */

{ width: 1.5, text: "" }, // spacer
{ width: 20.5, alignment: "LEFT", text: "Ship" },
{ width: 10, alignment: "RIGHT", text: "Maintenance" }
],
[ /* row 2 */
{ width: 1, alignment: "RIGHT", text: "1" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Cobra Mk III" },
{ width: 2.5, alignment: "RIGHT", text: "10%" }
],

[ /* row 3 */
{ width: 1, alignment: "RIGHT", text: "2" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, text: "Krait" },
{ width: 2.5, alignment: "RIGHT", text: "7%" }
],

[ /* row 4 */
{ width: 1, alignment: "RIGHT", text: "3" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Unrealisticly long ship class name that happens to be not so long for mission screen" },
{ width: 2.5, alignment: "RIGHT", text: "100%" }
],

[ /* row 5 */
{ width: 1, alignment: "RIGHT", text: "4" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Unrealisticly long name without ellipses that happens to be not so long for mission screen", ellipses: false },
{ width: 2.5, alignment: "RIGHT", text: "100%" }
],

[
],

[
{ width: 32, alignment: "CENTER", text: "Next enemy group encounter in 4 hours" }
]
]

);

var utils = worldScripts["alaric-oxp-utilities"]; // Get world script object if you copied entire file to your OXP
var messageText = utils._buildTabularText(rows); // or use this._buildTabularText(rows), if you copied just that funtions in your world script

mission.runScreen({
title: "Statistics",
screenID: "oxpname-stats-fleet"
message: messageText
});
</pre>



== Backdrop ==
: This is managed from within the script.js file:
background: ""the_file_name_of_the_image_you_want_to_display_must_be_in_the_images_folder.png",
or you can use ''overlay'' instead of ''background'' (less conflicts with other oxp's such as XenonUI which also tend to specify a background)

=== Problems with Backdrop ===
These can be prevented from appearing by other oxp's such as [[XenonUI]] which also create backdrops for the docked screens.

Using ''overlay'' helps, but also see Phkb's comments [http://aegidian.org/bb/viewtopic.php?p=282180#p282180 here] (for Dark Side solutions) and [http://aegidian.org/bb/viewtopic.php?p=278857#p278857 here] (using Library config).

== Exit Screen ==
By default, when the mission screen ends, the game returns to the status screen (F5), but this behavior can be changed.
In most cases you can just provide the <code>exitScreen</code> parameter to the <code>[[Oolite JavaScript Reference: Mission#runScreen|mission.runScreen]]</code> call, but if
if the exit screen depends on the player's choice, you need change the exit screen in the mission screen callback by setting <code>[[Oolite JavaScript Reference: Mission#exitScreen|mission.exitScreen]]</code>. Outside of a callback function, the value of this is almost meaningless, and setting it has no useful effect.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show example" data-collapsetext="Hide example" style="max-width:max-content">
The example below uses both ways: <span style="visibility: hidden">    Show Example</span>
<pre style="width:max-content" class="mw-collapsible-content">
this._runMissionScreen = function _runMissionScreen()
{
mission.runScreen(
{
title: "Exit Screen Example",
exitScreen: "GUI_SCREEN_MARKET", // <-- The first way
choices: {
"01_INTERFACES": "Do nothing",
"02_CHART": "Set mission.exitScreen to \"GUI_SCREEN_SHORT_RANGE_CHART\"",
"03_SYSDATA": "Set mission.exitScreen to \"GUI_SCREEN_SYSTEM_DATA\"",
"04_INVALID": "Set mission.exitScreen to \"INVALID VALUE\"",
}
},
this._missionScreenCallback.bind(this)
);
// The mission.exitScreen variable is set to the value
// of the exitScreen parameter of the function call above
mission.addMessageText("Current exit screen is " + mission.exitScreen + ".");
};

this._missionScreenCallback = function _missionScreenCallback(choice)
{
// The choice is null when player interrupts the mission screen (e.g., presses F1 )
if (choice === "01_INTERFACES" || choice === null) {
// Do nothing - the exit screen will be as specified in runScreen call
}
else if (choice === "02_CHART") {
mission.exitScreen = "GUI_SCREEN_SHORT_RANGE_CHART"; // <-- The second way
}
else if (choice === "03_SYSDATA") {
mission.exitScreen = "GUI_SCREEN_SYSTEM_DATA";
}
else if (choice === "04_INVALID") {
mission.exitScreen = "INVALID VALUE"; // The exit screen will be reset to default
}
};

// Add interface to F4 page for docked station
this.startUpComplete = function startUpComplete()
{
player.ship.dockedStation.setInterface("example_exit_screen",
{
title: "Show exitScreen example screen",
summary: "This is an example interface definition.",
category: "AAA",
callback: this._runMissionScreen.bind(this)
}
);
};
</pre>
</div>

[[Image:Lib_Starmap02.png|320px|thumb|right|Library OXP Demos: Starmap (animated)]]
== Visual Mission screens ==
It is possible to have animations or cutscenes instead. These require either Library.oxp or the deprecated CCL.

These two oxp's allow for more complex interractions. See [[Library OXP]]'s "Music" and the two "Demos" (Starmap & Animator). And see also the deprecated [[CCL]]'s never-used [[Cutscene]].

== Links ==
*[http://aegidian.org/bb/viewtopic.php?p=276448#p276448 Creating a mission screen] for textual messages (2021)
*[http://www.aegidian.org/bb/viewtopic.php?p=283395#p283395 Changing text colour] (2022)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18713 New Line in mission.runScreen?] (2017)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18414 Tabular text output for MFDs/mission screens] (2016)
=== Useful OXPs ===
*[[HDBG]] - High Definition BackGrounds - provides background pictures for Mission Screens
*HDBG Image Pack A (alas, Image Pack B never emerged...)
*[[Library OXP]] - enables animated Mission Screens

[[Category:Oolite scripting]]

File:Alaric's Tabular text for MDFs mission screens.png

2023-02-12T15:44:19Z

Alnivel: From http://www.aegidian.org/bb/viewtopic.php?f=4&t=18414

== Summary ==
From http://www.aegidian.org/bb/viewtopic.php?f=4&t=18414

Mission screen

2023-02-12T15:23:09Z

Alnivel: /* Tab stops */ Reworded a bit for clarity

{{OXPNote|This Page is a WIP aimed at dumb pilots like myself!}}

[[File:Hints.png|right|320px]]
Mission screens started off as screens which allow the player to interface with NPCs in a mission.oxp. They also allow other sorts of "communication" as in the conversation overheard in the bar in the [[Hints]] OXP.

They can have backdrops, changes in text and allow choices for the player.

The text can be placed in a descriptions.plist, details about it in a script.js (but everything can go in the script.js if so desired).

== Text ==
:Several special spatial characters can be used in determining the layout of the text, just as in this Wiki.
\" Enables the use of colons.
\\n Insert a hard Enter.

In XML:
\n Inserts a hard Enter.

:See [[Missiontext.plist]] for more complexity (''eg'' random names, naming current system ''etc'')

:Character '31' (hex:1F, octal:037) is a narrow 'hair-space'. Custom font OXPs should ensure that this character is blank and has the same narrow width as the core font definition, as it is used to allow an equivalent to 'tab stops' in mission text.

=== % codes ===
Here are the % codes that can be used inside description strings and what each one does:

Code:
* %H is replaced with <planetName>. If systemName is nil, a planet name is retrieved through -[Universe getSystemName:], treating <seed> as a system seed. <br>
* %I is equivalent to "%H[planetname-derivative-suffix]".<br>
* %N is replaced with a random "alien" name using the planet name digraphs. If used more than once in the same string, it will produce the same name on each occurence.
* %R is like %N but, due to a bug, misses some possibilities. Deprecated.
* %JNNN, where NNN is a three-digit integer, is replaced with the name of system ID NNN in the current galaxy.
* %GNNNNNN, where NNNNNN is a six-digit integer, is replaced with the name of system ID NNN (first triplet) in the specified galaxy (second triplet).
* %% is replaced with %.
* %[ is replaced with [.
* %] is replaced with ].
:From [[String expansion]]

== Colour ==
:Choices can be non-yellow (have a look at the various contracts interfaces in 1.77) but there is a more fundamental limitation of the current UI code that all text on a particular line has to be the same colour. [http://www.aegidian.org/bb/viewtopic.php?p=203777#p203777 Cim (2013)]

:Code for [http://www.aegidian.org/bb/viewtopic.php?p=283402#p283402 Colour change]

[[File:First Finance Loan Management.png|right|300px]]
== Alignment ==
There is no obvious way to do this, but [[User:Ocz|Ocz]] managed some version of right alignment for his [[First Finance OXP]]

=== Tab stops ===
Although there are no built-in tabs, they can be imitated with some JavaScript. Below you can find some of the basic functions for formating the text, but in various OXPs you can find them under other names, as well as others that can be a way more complex and specialized.
However, their core principle remains the same - they add invisible characters to the string passed to them up to the desired width - just as you can do it in a text editor, by adding spaces you can get (almost) any kind of text tabulation. The functions, however, don't use a rather wide regular space, but a narrow hair space, which allows text to align more accurately.

The unit of text width is em - the intrinsic unit size of a font. The mission screen is 32 em wide and text wider than that will wrap with breaks on spaces. You can measure the width of a string using <code>[[Oolite_JavaScript_Reference:_Global#defaultFont|defaultFont.measureString]]</code>.

Here you can see one of the implementations of <code>_limitText</code>, <code>_padTextLeft</code>, <code>_padTextRight</code> and <code>_padTextAround</code> functions. Feel free to use it in your work!
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
/**
* The function cuts text to limitWidth if necessary, and adds an ellipsis in this case.
* It's useful when you want to display text that may be larger than the available space, such as ship names.
* Large text, if left unprocessed, can make the rest of the formatting go haywire.
*
* text - the string to make sure that it won't be longer than limitWidth
* limitWidth - the maximum width of the result, in ems
* result - the limited string
*/
this._limitText = function _limitText(text, limitWidth) {
const ellipsis = "…";

var tmp = text;

while (defaultFont.measureString(tmp) > limitWidth) { // until text in wider than limit
// remove from the text two last characters and add an ellipsis
// two because we need to remove an ellipsis from previous iteration
tmp = tmp.substring(0, tmp.length - 2) + ellipsis;
}

return tmp;
}

/**
* The functions below add hair spaces to the text to make it have a desiredWidth,
* but in case if text is too wide, the function do the _limitText instead.
*
* To reduce the duplication of code they all just shorcuts for more generic _padText
*
* text - the string that we want to have a desiredWidth
* desiredWidth - the width of the result, in ems
* result - the padded string
*/
this._padTextLeft = function _padTextLeft(text, desiredWidth) {
return this._padText(text, desiredWidth, "left");
}

this._padTextRight = function _padTextRight(text, desiredWidth) {
return this._padText(text, desiredWidth, "right");
}

this._padTextAround = function _padTextAround(text, desiredWidth) {
return this._padText(text, desiredWidth, "both");
}

/**
* The function add hair spaces to the text to make it have a desiredWidth.
* But in case if text is too wide, the function do _limitText instead.
*
* text - the string that we want to have a desiredWidth
* desiredWidth - the width of the result, in ems
* padSide:
* "left" - add pads before the text
* "right" - add pads after the text
* "both" - add pads both before and after the text
* result - the padded string
*/
this._padText = function _padText(text, desiredWidth, padSide) {
// Keep character and it's width it variables for sake of optimization and clarity
const hairSpace = String.fromCharCode(31);
const hairSpaceWidth = defaultFont.measureString(hairSpace);

// Find out the width of text in ems
const textWidth = defaultFont.measureString(text);

const padsNeeded = Math.floor((desiredWidth - textWidth) / hairSpaceWidth);

var resultText;
if (padsNeeded > 1) {
// new Array(n).join(someString) - the compact way to say "repeat the someString n times"
if (padSide == "left") {
resultText = new Array(padsNeeded).join(hairSpace) + text;
}
else if (padSide == "right") {
resultText = text + new Array(padsNeeded).join(hairSpace);
}
else if (padSide == "both") {
const leftPadsNumber = Math.floor(padsNeeded / 2);
const leftPadding = new Array(leftPadsNumber).join(hairSpace);
const rightPadding = new Array(padsNeeded - leftPadsNumber).join(hairSpace);

resultText = leftPadding + text + rightPadding;
}
}
else {
resultText = this.$limitText(text, desiredWidth);
}

return resultText;
}
</pre>

=== Tabular layout ===
When you need to get something in the form of a table or columns, you can use padText-like functions to adjust the padding of the desired width to labels and data, and then concatenate them into one line, just keep in mind that max row length is 32 em.
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
var pad1em = this._padTextLeft("", 1);
var tableHeader = this._padTextLeft("#", 3) + pad1em +
this._padTextRight("Item", 11) + pad1em +
this._padTextAround("Remaining, pcs.", 7) + pad1em +
this._padTextAround("Price, ₢ ", 7) + pad1em;

var tableRows = Array(this.$items.length);
for(var i = 0; i < this.$items.length; i++) {
var item = this.$items[i];
tableRows[i] = this._padTextLeft(i + 1, 3) + pad1em +
this._padTextRight(item.name, 11) + pad1em +
this._padTextAround(item.quantity, 7) + pad1em +
this._padTextLeft(formatCredits(item.price), 7) + pad1em;
}

// Concatenate them in one string if you want to display
// the table as "message" on the mission screen
var table = tableHeader + "\n" + tableRows.join("\n") + "\n\n";
</pre>

[[User:Alaric/KV-16 Owners Manual|Alaric's unfinished Torus-field-monitor OXZ]] contains handy function to help format text in tabular layout for use in mission screens/MFDs. See his alaric-oxp-utilities.js file:
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
"use strict";

this.name = "alaric-oxp-utilities";
this.author = "Alaric";
this.copyright = "2016 Alaric";
this.description = "General helper functions for OXPs";
this.licence = "CC BY-NC-SA 3.0 AU";
this.version = "1.0";

/**
* Trims a length of text to fit in the available width. If the text is truncated,
* an ellipse (U+2026) will be appended unless <ellipses> is false. If <ellipses>
* is omitted from the call, it defaults to true.
*
* text - The text to trim
* emDisplayWidth - The available width, in Em, to display the text
* ellipses - optional (default: true)
*
* Returns the new, trimmed, string.
*/
this._trimTextToFitWidth = function(text, emDisplayWidth, ellipses)
{
var font = defaultFont;
var chPadding = String.fromCharCode(31);
var ellipsesText = "\u2026";
var emEllipsesText = font.measureString(ellipsesText);
var emPaddingText = font.measureString(chPadding);

var chWidth = [0, text.length];
var emWidth = [font.measureString(text), 0];

// use default for ellipses if not supplied
if (ellipses === null || ellipses === undefined) ellipses = true;

// if the text already fits, just return it.
if (emWidth[0] <= emDisplayWidth) return text;

// if the display width is too short for ellipses, disable ellipses
if (emEllipsesText >= emDisplayWidth) ellipses = false;

// subtract ellipses with from display width if ellipses is true
emDisplayWidth -= (ellipses) ? emEllipsesText : 0;

while (chWidth[0] != chWidth[1])
{
// get Em width of text at length midway between chWidth[0] and chWidth[1]
var chPivot = Math.ceil((chWidth[0] + chWidth[1]) / 2);
var emPivot = font.measureString(text.substring(0, chPivot));

// update for next split point based on the text being too long or too short
var flagDirection = (emPivot <= emDisplayWidth) ? 0 : 1;

chWidth[flagDirection] = chPivot - flagDirection;
emWidth[flagDirection] = emPivot;
}

// At this point, chWidth[0] and emWidth[0] contain the trimmed width in
// characters and Em respectively. Return the text, appending ellipses if
// <ellipses> is true. The space for ellipses has already been accounted
// for.

return (ellipses)
? text.substring(0, chWidth[0]) + ellipsesText
: text.substring(0, chWidth[0])
;
}

/*
* Builds tabular (columns aligned) text for use in mission screens/MFDs.
*
* Input to the function is provided by an array of 'rows'. Each row is, itself, an array of
* objects with the following properties:
*
* Required properties:
* text: The text to display in this column
* width: The width of the column in em. Text will be truncated if too long.
*
* Optional properties:
* alignment: LEFT, RIGHT or CENTER. Default: LEFT
* elipses: Display elipses for truncated text? Default: true.
* blink:
*
* Multiple rows are deliniated by '\n'. No '\n' is appended to the last row.
*
*/
this._buildTabularText = function(rows)
{
var padCharacter = String.fromCharCode(31);
var padWidth = defaultFont.measureString(padCharacter);
var tabularText = "";
var row;

for (row = 0; row < rows.length; ++row)
{
if (row > 0) tabularText += "\n";

var i;

var currentEm0 = 0;
var currentEm1 = 0;
var columns = rows[row];
var rowText = "";

for (i = 0; i < columns.length; ++i)
{

currentEm0 = defaultFont.measureString(rowText);
var leading = (currentEm1 - currentEm0);
currentEm1 = currentEm1 + columns[i].width;

var text = this._trimTextToFitWidth(columns[i].text, currentEm1 - currentEm0, columns[i].ellipses);
var width = defaultFont.measureString(text);

var padding = (currentEm1 - currentEm0) - width;

switch ((columns[i].alignment !== undefined) ? columns[i].alignment : "LEFT")
{

case "LEFT" : padding = 0; break;
case "RIGHT" : leading = 0; break;
case "CENTER" : padding = padding / 2; break;

default:
log(this.name, "invalid alignment '" + columns[i].alignment + "'");
padding = 0; break;

}

padding = Math.floor((leading + padding) / padWidth);

rowText += (padding >= 1)
? new Array(padding).join(padCharacter) + text
: text
;
}

tabularText += rowText;
}

return tabularText;
}
</pre>

You can use it like this:
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
var rows = [
[ /* header */
{ width: 32, alignment: "CENTER", text: "Fleet status" }
],

[ /* line spacer */
],

[ /* row 1 */

{ width: 1.5, text: "" }, // spacer
{ width: 20.5, alignment: "LEFT", text: "Ship" },
{ width: 10, alignment: "RIGHT", text: "Maintenance" }
],
[ /* row 2 */
{ width: 1, alignment: "RIGHT", text: "1" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Cobra Mk III" },
{ width: 2.5, alignment: "RIGHT", text: "10%" }
],

[ /* row 3 */
{ width: 1, alignment: "RIGHT", text: "2" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, text: "Krait" },
{ width: 2.5, alignment: "RIGHT", text: "7%" }
],

[ /* row 4 */
{ width: 1, alignment: "RIGHT", text: "3" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Unrealisticly long ship class name that happens to be not so long for mission screen" },
{ width: 2.5, alignment: "RIGHT", text: "100%" }
],

[ /* row 5 */
{ width: 1, alignment: "RIGHT", text: "4" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Unrealisticly long name without ellipses that happens to be not so long for mission screen", ellipses: false },
{ width: 2.5, alignment: "RIGHT", text: "100%" }
],

[
],

[
{ width: 32, alignment: "CENTER", text: "Next enemy group encounter in 4 hours" }
]
]

);

var utils = worldScripts["alaric-oxp-utilities"]; // Get world script object if you copied entire file to your OXP
var messageText = utils._buildTabularText(rows); // or use this._buildTabularText(rows), if you copied just that funtions in your world script

mission.runScreen({
title: "Statistics",
screenID: "oxpname-stats-fleet"
message: messageText
});
</pre>



== Backdrop ==
: This is managed from within the script.js file:
background: ""the_file_name_of_the_image_you_want_to_display_must_be_in_the_images_folder.png",
or you can use ''overlay'' instead of ''background'' (less conflicts with other oxp's such as XenonUI which also tend to specify a background)

=== Problems with Backdrop ===
These can be prevented from appearing by other oxp's such as [[XenonUI]] which also create backdrops for the docked screens.

Using ''overlay'' helps, but also see Phkb's comments [http://aegidian.org/bb/viewtopic.php?p=282180#p282180 here] (for Dark Side solutions) and [http://aegidian.org/bb/viewtopic.php?p=278857#p278857 here] (using Library config).

== Exit Screen ==
By default, when the mission screen ends, the game returns to the status screen (F5), but this behavior can be changed.
In most cases you can just provide the <code>exitScreen</code> parameter to the <code>[[Oolite JavaScript Reference: Mission#runScreen|mission.runScreen]]</code> call, but if
if the exit screen depends on the player's choice, you need change the exit screen in the mission screen callback by setting <code>[[Oolite JavaScript Reference: Mission#exitScreen|mission.exitScreen]]</code>. Outside of a callback function, the value of this is almost meaningless, and setting it has no useful effect.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show example" data-collapsetext="Hide example" style="max-width:max-content">
The example below uses both ways: <span style="visibility: hidden">    Show Example</span>
<pre style="width:max-content" class="mw-collapsible-content">
this._runMissionScreen = function _runMissionScreen()
{
mission.runScreen(
{
title: "Exit Screen Example",
exitScreen: "GUI_SCREEN_MARKET", // <-- The first way
choices: {
"01_INTERFACES": "Do nothing",
"02_CHART": "Set mission.exitScreen to \"GUI_SCREEN_SHORT_RANGE_CHART\"",
"03_SYSDATA": "Set mission.exitScreen to \"GUI_SCREEN_SYSTEM_DATA\"",
"04_INVALID": "Set mission.exitScreen to \"INVALID VALUE\"",
}
},
this._missionScreenCallback.bind(this)
);
// The mission.exitScreen variable is set to the value
// of the exitScreen parameter of the function call above
mission.addMessageText("Current exit screen is " + mission.exitScreen + ".");
};

this._missionScreenCallback = function _missionScreenCallback(choice)
{
// The choice is null when player interrupts the mission screen (e.g., presses F1 )
if (choice === "01_INTERFACES" || choice === null) {
// Do nothing - the exit screen will be as specified in runScreen call
}
else if (choice === "02_CHART") {
mission.exitScreen = "GUI_SCREEN_SHORT_RANGE_CHART"; // <-- The second way
}
else if (choice === "03_SYSDATA") {
mission.exitScreen = "GUI_SCREEN_SYSTEM_DATA";
}
else if (choice === "04_INVALID") {
mission.exitScreen = "INVALID VALUE"; // The exit screen will be reset to default
}
};

// Add interface to F4 page for docked station
this.startUpComplete = function startUpComplete()
{
player.ship.dockedStation.setInterface("example_exit_screen",
{
title: "Show exitScreen example screen",
summary: "This is an example interface definition.",
category: "AAA",
callback: this._runMissionScreen.bind(this)
}
);
};
</pre>
</div>

[[Image:Lib_Starmap02.png|320px|thumb|right|Library OXP Demos: Starmap (animated)]]
== Visual Mission screens ==
It is possible to have animations or cutscenes instead. These require either Library.oxp or the deprecated CCL.

These two oxp's allow for more complex interractions. See [[Library OXP]]'s "Music" and the two "Demos" (Starmap & Animator). And see also the deprecated [[CCL]]'s never-used [[Cutscene]].

== Links ==
*[http://aegidian.org/bb/viewtopic.php?p=276448#p276448 Creating a mission screen] for textual messages (2021)
*[http://www.aegidian.org/bb/viewtopic.php?p=283395#p283395 Changing text colour] (2022)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18713 New Line in mission.runScreen?] (2017)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18414 Tabular text output for MFDs/mission screens] (2016)
=== Useful OXPs ===
*[[HDBG]] - High Definition BackGrounds - provides background pictures for Mission Screens
*HDBG Image Pack A (alas, Image Pack B never emerged...)
*[[Library OXP]] - enables animated Mission Screens

[[Category:Oolite scripting]]

Mission screen

2023-02-12T12:35:07Z

Alnivel: /* Tab stops */ Added code of padText functions

{{OXPNote|This Page is a WIP aimed at dumb pilots like myself!}}

[[File:Hints.png|right|320px]]
Mission screens started off as screens which allow the player to interface with NPCs in a mission.oxp. They also allow other sorts of "communication" as in the conversation overheard in the bar in the [[Hints]] OXP.

They can have backdrops, changes in text and allow choices for the player.

The text can be placed in a descriptions.plist, details about it in a script.js (but everything can go in the script.js if so desired).

== Text ==
:Several special spatial characters can be used in determining the layout of the text, just as in this Wiki.
\" Enables the use of colons.
\\n Insert a hard Enter.

In XML:
\n Inserts a hard Enter.

:See [[Missiontext.plist]] for more complexity (''eg'' random names, naming current system ''etc'')

:Character '31' (hex:1F, octal:037) is a narrow 'hair-space'. Custom font OXPs should ensure that this character is blank and has the same narrow width as the core font definition, as it is used to allow an equivalent to 'tab stops' in mission text.

=== % codes ===
Here are the % codes that can be used inside description strings and what each one does:

Code:
* %H is replaced with <planetName>. If systemName is nil, a planet name is retrieved through -[Universe getSystemName:], treating <seed> as a system seed. <br>
* %I is equivalent to "%H[planetname-derivative-suffix]".<br>
* %N is replaced with a random "alien" name using the planet name digraphs. If used more than once in the same string, it will produce the same name on each occurence.
* %R is like %N but, due to a bug, misses some possibilities. Deprecated.
* %JNNN, where NNN is a three-digit integer, is replaced with the name of system ID NNN in the current galaxy.
* %GNNNNNN, where NNNNNN is a six-digit integer, is replaced with the name of system ID NNN (first triplet) in the specified galaxy (second triplet).
* %% is replaced with %.
* %[ is replaced with [.
* %] is replaced with ].
:From [[String expansion]]

== Colour ==
:Choices can be non-yellow (have a look at the various contracts interfaces in 1.77) but there is a more fundamental limitation of the current UI code that all text on a particular line has to be the same colour. [http://www.aegidian.org/bb/viewtopic.php?p=203777#p203777 Cim (2013)]

:Code for [http://www.aegidian.org/bb/viewtopic.php?p=283402#p283402 Colour change]

[[File:First Finance Loan Management.png|right|300px]]
== Alignment ==
There is no obvious way to do this, but [[User:Ocz|Ocz]] managed some version of right alignment for his [[First Finance OXP]]

=== Tab stops ===
Although there are no built-in tabs, this behavior can be mimicked using helper functions. Below will be placed are just one of the implementations of the most basic and atomic functions - _limitText and _padTextLeft/Right/Around, but in various OXPs you can find them under other names, as well as others that can be a way more complex and specialized.
However, their core principle remains the same - they add invisible characters to the string passed to them up to the desired width - just as you can do it in a text editor, by adding spaces you can get (almost) any kind of text tabulation. The functions, however, don't use a rather wide regular space, but a narrow hair space, which allows text to align more accurately.

Text width is measured in ems and may vary depending on the font. To measure the length of text in a default forn, you can use <code>defaultFont.measureString</code>. The width of mission screen row equals to 32 ems.

Here you can see one of the implementations of these functions. Inside the code there are comments that should help better understand how the functions work.
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
/**
* The function cuts text to limitWidth if necessary, and adds an ellipsis in this case.
* It's useful when you want to display text that may be larger than the available space, such as ship names.
* Large text, if left unprocessed, can make the rest of the formatting go haywire.
*
* text - the string to make sure that it won't be longer than limitWidth
* limitWidth - the maximum width of the result, in ems
* result - the limited string
*/
this._limitText = function _limitText(text, limitWidth) {
const ellipsis = "…";

var tmp = text;

while (defaultFont.measureString(tmp) > limitWidth) { // until text in wider than limit
// remove from the text two last characters and add an ellipsis
// two because we need to remove an ellipsis from previous iteration
tmp = tmp.substring(0, tmp.length - 2) + ellipsis;
}

return tmp;
}

/**
* The functions below add hair spaces to the text to make it have a desiredWidth,
* but in case if text is too wide, the function do the _limitText instead.
*
* To reduce the duplication of code they all just shorcuts for more generic _padText
*
* text - the string that we want to have a desiredWidth
* desiredWidth - the width of the result, in ems
* result - the padded string
*/
this._padTextLeft = function _padTextLeft(text, desiredWidth) {
return this._padText(text, desiredWidth, "left");
}

this._padTextRight = function _padTextRight(text, desiredWidth) {
return this._padText(text, desiredWidth, "right");
}

this._padTextAround = function _padTextAround(text, desiredWidth) {
return this._padText(text, desiredWidth, "both");
}

/**
* The function add hair spaces to the text to make it have a desiredWidth.
* But in case if text is too wide, the function do _limitText instead.
*
* text - the string that we want to have a desiredWidth
* desiredWidth - the width of the result, in ems
* padSide:
* "left" - add pads before the text
* "right" - add pads after the text
* "both" - add pads both before and after the text
* result - the padded string
*/
this._padText = function _padText(text, desiredWidth, padSide) {
// Keep character and it's width it variables for sake of optimization and clarity
const hairSpace = String.fromCharCode(31);
const hairSpaceWidth = defaultFont.measureString(hairSpace);

// Find out the width of text in ems
const textWidth = defaultFont.measureString(text);

const padsNeeded = Math.floor((desiredWidth - textWidth) / hairSpaceWidth);

var resultText;
if (padsNeeded > 1) {
// new Array(n).join(someString) - the compact way to say "repeat the someString n times"
if (padSide == "left") {
resultText = new Array(padsNeeded).join(hairSpace) + text;
}
else if (padSide == "right") {
resultText = text + new Array(padsNeeded).join(hairSpace);
}
else if (padSide == "both") {
const leftPadsNumber = Math.floor(padsNeeded / 2);
const leftPadding = new Array(leftPadsNumber).join(hairSpace);
const rightPadding = new Array(padsNeeded - leftPadsNumber).join(hairSpace);

resultText = leftPadding + text + rightPadding;
}
}
else {
resultText = this.$limitText(text, desiredWidth);
}

return resultText;
}
</pre>

=== Tabular layout ===
When you need to get something in the form of a table or columns, you can use padText-like functions to adjust the padding of the desired width to labels and data, and then concatenate them into one line, just keep in mind that max row length is 32 em.
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
var pad1em = this._padTextLeft("", 1);
var tableHeader = this._padTextLeft("#", 3) + pad1em +
this._padTextRight("Item", 11) + pad1em +
this._padTextAround("Remaining, pcs.", 7) + pad1em +
this._padTextAround("Price, ₢ ", 7) + pad1em;

var tableRows = Array(this.$items.length);
for(var i = 0; i < this.$items.length; i++) {
var item = this.$items[i];
tableRows[i] = this._padTextLeft(i + 1, 3) + pad1em +
this._padTextRight(item.name, 11) + pad1em +
this._padTextAround(item.quantity, 7) + pad1em +
this._padTextLeft(formatCredits(item.price), 7) + pad1em;
}

// Concatenate them in one string if you want to display
// the table as "message" on the mission screen
var table = tableHeader + "\n" + tableRows.join("\n") + "\n\n";
</pre>

[[User:Alaric/KV-16 Owners Manual|Alaric's unfinished Torus-field-monitor OXZ]] contains handy function to help format text in tabular layout for use in mission screens/MFDs. See his alaric-oxp-utilities.js file:
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
"use strict";

this.name = "alaric-oxp-utilities";
this.author = "Alaric";
this.copyright = "2016 Alaric";
this.description = "General helper functions for OXPs";
this.licence = "CC BY-NC-SA 3.0 AU";
this.version = "1.0";

/**
* Trims a length of text to fit in the available width. If the text is truncated,
* an ellipse (U+2026) will be appended unless <ellipses> is false. If <ellipses>
* is omitted from the call, it defaults to true.
*
* text - The text to trim
* emDisplayWidth - The available width, in Em, to display the text
* ellipses - optional (default: true)
*
* Returns the new, trimmed, string.
*/
this._trimTextToFitWidth = function(text, emDisplayWidth, ellipses)
{
var font = defaultFont;
var chPadding = String.fromCharCode(31);
var ellipsesText = "\u2026";
var emEllipsesText = font.measureString(ellipsesText);
var emPaddingText = font.measureString(chPadding);

var chWidth = [0, text.length];
var emWidth = [font.measureString(text), 0];

// use default for ellipses if not supplied
if (ellipses === null || ellipses === undefined) ellipses = true;

// if the text already fits, just return it.
if (emWidth[0] <= emDisplayWidth) return text;

// if the display width is too short for ellipses, disable ellipses
if (emEllipsesText >= emDisplayWidth) ellipses = false;

// subtract ellipses with from display width if ellipses is true
emDisplayWidth -= (ellipses) ? emEllipsesText : 0;

while (chWidth[0] != chWidth[1])
{
// get Em width of text at length midway between chWidth[0] and chWidth[1]
var chPivot = Math.ceil((chWidth[0] + chWidth[1]) / 2);
var emPivot = font.measureString(text.substring(0, chPivot));

// update for next split point based on the text being too long or too short
var flagDirection = (emPivot <= emDisplayWidth) ? 0 : 1;

chWidth[flagDirection] = chPivot - flagDirection;
emWidth[flagDirection] = emPivot;
}

// At this point, chWidth[0] and emWidth[0] contain the trimmed width in
// characters and Em respectively. Return the text, appending ellipses if
// <ellipses> is true. The space for ellipses has already been accounted
// for.

return (ellipses)
? text.substring(0, chWidth[0]) + ellipsesText
: text.substring(0, chWidth[0])
;
}

/*
* Builds tabular (columns aligned) text for use in mission screens/MFDs.
*
* Input to the function is provided by an array of 'rows'. Each row is, itself, an array of
* objects with the following properties:
*
* Required properties:
* text: The text to display in this column
* width: The width of the column in em. Text will be truncated if too long.
*
* Optional properties:
* alignment: LEFT, RIGHT or CENTER. Default: LEFT
* elipses: Display elipses for truncated text? Default: true.
* blink:
*
* Multiple rows are deliniated by '\n'. No '\n' is appended to the last row.
*
*/
this._buildTabularText = function(rows)
{
var padCharacter = String.fromCharCode(31);
var padWidth = defaultFont.measureString(padCharacter);
var tabularText = "";
var row;

for (row = 0; row < rows.length; ++row)
{
if (row > 0) tabularText += "\n";

var i;

var currentEm0 = 0;
var currentEm1 = 0;
var columns = rows[row];
var rowText = "";

for (i = 0; i < columns.length; ++i)
{

currentEm0 = defaultFont.measureString(rowText);
var leading = (currentEm1 - currentEm0);
currentEm1 = currentEm1 + columns[i].width;

var text = this._trimTextToFitWidth(columns[i].text, currentEm1 - currentEm0, columns[i].ellipses);
var width = defaultFont.measureString(text);

var padding = (currentEm1 - currentEm0) - width;

switch ((columns[i].alignment !== undefined) ? columns[i].alignment : "LEFT")
{

case "LEFT" : padding = 0; break;
case "RIGHT" : leading = 0; break;
case "CENTER" : padding = padding / 2; break;

default:
log(this.name, "invalid alignment '" + columns[i].alignment + "'");
padding = 0; break;

}

padding = Math.floor((leading + padding) / padWidth);

rowText += (padding >= 1)
? new Array(padding).join(padCharacter) + text
: text
;
}

tabularText += rowText;
}

return tabularText;
}
</pre>

You can use it like this:
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
var rows = [
[ /* header */
{ width: 32, alignment: "CENTER", text: "Fleet status" }
],

[ /* line spacer */
],

[ /* row 1 */

{ width: 1.5, text: "" }, // spacer
{ width: 20.5, alignment: "LEFT", text: "Ship" },
{ width: 10, alignment: "RIGHT", text: "Maintenance" }
],
[ /* row 2 */
{ width: 1, alignment: "RIGHT", text: "1" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Cobra Mk III" },
{ width: 2.5, alignment: "RIGHT", text: "10%" }
],

[ /* row 3 */
{ width: 1, alignment: "RIGHT", text: "2" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, text: "Krait" },
{ width: 2.5, alignment: "RIGHT", text: "7%" }
],

[ /* row 4 */
{ width: 1, alignment: "RIGHT", text: "3" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Unrealisticly long ship class name that happens to be not so long for mission screen" },
{ width: 2.5, alignment: "RIGHT", text: "100%" }
],

[ /* row 5 */
{ width: 1, alignment: "RIGHT", text: "4" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Unrealisticly long name without ellipses that happens to be not so long for mission screen", ellipses: false },
{ width: 2.5, alignment: "RIGHT", text: "100%" }
],

[
],

[
{ width: 32, alignment: "CENTER", text: "Next enemy group encounter in 4 hours" }
]
]

);

var utils = worldScripts["alaric-oxp-utilities"]; // Get world script object if you copied entire file to your OXP
var messageText = utils._buildTabularText(rows); // or use this._buildTabularText(rows), if you copied just that funtions in your world script

mission.runScreen({
title: "Statistics",
screenID: "oxpname-stats-fleet"
message: messageText
});
</pre>



== Backdrop ==
: This is managed from within the script.js file:
background: ""the_file_name_of_the_image_you_want_to_display_must_be_in_the_images_folder.png",
or you can use ''overlay'' instead of ''background'' (less conflicts with other oxp's such as XenonUI which also tend to specify a background)

=== Problems with Backdrop ===
These can be prevented from appearing by other oxp's such as [[XenonUI]] which also create backdrops for the docked screens.

Using ''overlay'' helps, but also see Phkb's comments [http://aegidian.org/bb/viewtopic.php?p=282180#p282180 here] (for Dark Side solutions) and [http://aegidian.org/bb/viewtopic.php?p=278857#p278857 here] (using Library config).

== Exit Screen ==
By default, when the mission screen ends, the game returns to the status screen (F5), but this behavior can be changed.
In most cases you can just provide the <code>exitScreen</code> parameter to the <code>[[Oolite JavaScript Reference: Mission#runScreen|mission.runScreen]]</code> call, but if
if the exit screen depends on the player's choice, you need change the exit screen in the mission screen callback by setting <code>[[Oolite JavaScript Reference: Mission#exitScreen|mission.exitScreen]]</code>. Outside of a callback function, the value of this is almost meaningless, and setting it has no useful effect.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show example" data-collapsetext="Hide example" style="max-width:max-content">
The example below uses both ways: <span style="visibility: hidden">    Show Example</span>
<pre style="width:max-content" class="mw-collapsible-content">
this._runMissionScreen = function _runMissionScreen()
{
mission.runScreen(
{
title: "Exit Screen Example",
exitScreen: "GUI_SCREEN_MARKET", // <-- The first way
choices: {
"01_INTERFACES": "Do nothing",
"02_CHART": "Set mission.exitScreen to \"GUI_SCREEN_SHORT_RANGE_CHART\"",
"03_SYSDATA": "Set mission.exitScreen to \"GUI_SCREEN_SYSTEM_DATA\"",
"04_INVALID": "Set mission.exitScreen to \"INVALID VALUE\"",
}
},
this._missionScreenCallback.bind(this)
);
// The mission.exitScreen variable is set to the value
// of the exitScreen parameter of the function call above
mission.addMessageText("Current exit screen is " + mission.exitScreen + ".");
};

this._missionScreenCallback = function _missionScreenCallback(choice)
{
// The choice is null when player interrupts the mission screen (e.g., presses F1 )
if (choice === "01_INTERFACES" || choice === null) {
// Do nothing - the exit screen will be as specified in runScreen call
}
else if (choice === "02_CHART") {
mission.exitScreen = "GUI_SCREEN_SHORT_RANGE_CHART"; // <-- The second way
}
else if (choice === "03_SYSDATA") {
mission.exitScreen = "GUI_SCREEN_SYSTEM_DATA";
}
else if (choice === "04_INVALID") {
mission.exitScreen = "INVALID VALUE"; // The exit screen will be reset to default
}
};

// Add interface to F4 page for docked station
this.startUpComplete = function startUpComplete()
{
player.ship.dockedStation.setInterface("example_exit_screen",
{
title: "Show exitScreen example screen",
summary: "This is an example interface definition.",
category: "AAA",
callback: this._runMissionScreen.bind(this)
}
);
};
</pre>
</div>

[[Image:Lib_Starmap02.png|320px|thumb|right|Library OXP Demos: Starmap (animated)]]
== Visual Mission screens ==
It is possible to have animations or cutscenes instead. These require either Library.oxp or the deprecated CCL.

These two oxp's allow for more complex interractions. See [[Library OXP]]'s "Music" and the two "Demos" (Starmap & Animator). And see also the deprecated [[CCL]]'s never-used [[Cutscene]].

== Links ==
*[http://aegidian.org/bb/viewtopic.php?p=276448#p276448 Creating a mission screen] for textual messages (2021)
*[http://www.aegidian.org/bb/viewtopic.php?p=283395#p283395 Changing text colour] (2022)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18713 New Line in mission.runScreen?] (2017)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18414 Tabular text output for MFDs/mission screens] (2016)
=== Useful OXPs ===
*[[HDBG]] - High Definition BackGrounds - provides background pictures for Mission Screens
*HDBG Image Pack A (alas, Image Pack B never emerged...)
*[[Library OXP]] - enables animated Mission Screens

[[Category:Oolite scripting]]

Mission screen

2023-02-12T10:54:40Z

Alnivel: /* Alignment */ Added about padText- functions, no code yet

{{OXPNote|This Page is a WIP aimed at dumb pilots like myself!}}

[[File:Hints.png|right|320px]]
Mission screens started off as screens which allow the player to interface with NPCs in a mission.oxp. They also allow other sorts of "communication" as in the conversation overheard in the bar in the [[Hints]] OXP.

They can have backdrops, changes in text and allow choices for the player.

The text can be placed in a descriptions.plist, details about it in a script.js (but everything can go in the script.js if so desired).

== Text ==
:Several special spatial characters can be used in determining the layout of the text, just as in this Wiki.
\" Enables the use of colons.
\\n Insert a hard Enter.

In XML:
\n Inserts a hard Enter.

:See [[Missiontext.plist]] for more complexity (''eg'' random names, naming current system ''etc'')

:Character '31' (hex:1F, octal:037) is a narrow 'hair-space'. Custom font OXPs should ensure that this character is blank and has the same narrow width as the core font definition, as it is used to allow an equivalent to 'tab stops' in mission text.

=== % codes ===
Here are the % codes that can be used inside description strings and what each one does:

Code:
* %H is replaced with <planetName>. If systemName is nil, a planet name is retrieved through -[Universe getSystemName:], treating <seed> as a system seed. <br>
* %I is equivalent to "%H[planetname-derivative-suffix]".<br>
* %N is replaced with a random "alien" name using the planet name digraphs. If used more than once in the same string, it will produce the same name on each occurence.
* %R is like %N but, due to a bug, misses some possibilities. Deprecated.
* %JNNN, where NNN is a three-digit integer, is replaced with the name of system ID NNN in the current galaxy.
* %GNNNNNN, where NNNNNN is a six-digit integer, is replaced with the name of system ID NNN (first triplet) in the specified galaxy (second triplet).
* %% is replaced with %.
* %[ is replaced with [.
* %] is replaced with ].
:From [[String expansion]]

== Colour ==
:Choices can be non-yellow (have a look at the various contracts interfaces in 1.77) but there is a more fundamental limitation of the current UI code that all text on a particular line has to be the same colour. [http://www.aegidian.org/bb/viewtopic.php?p=203777#p203777 Cim (2013)]

:Code for [http://www.aegidian.org/bb/viewtopic.php?p=283402#p283402 Colour change]

[[File:First Finance Loan Management.png|right|300px]]
== Alignment ==
There is no obvious way to do this, but [[User:Ocz|Ocz]] managed some version of right alignment for his [[First Finance OXP]]

=== Tab stops ===
Although there are no built-in tabs, this behavior can be mimicked using helper functions. Below will be placed are just one of the implementations of the most basic and atomic functions - _limitText and _padTextLeft/Right/Around, but in various OXPs you can find them under other names, as well as others that can be a way more complex and specialized.
However, their core principle remains the same - they add invisible characters to the string passed to them up to the desired width - just as you can do it in a text editor, by adding spaces you can get (almost) any kind of text tabulation. The functions, however, don't use a rather wide regular space, but a narrow hair space, which allows text to align more accurately.

=== Tabular layout ===
When you need to get something in the form of a table or columns, you can use padText-like functions to adjust the padding of the desired width to labels and data, and then concatenate them into one line, just keep in mind that max row length is 32 em.
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
var pad1em = this._padTextLeft("", 1);
var tableHeader = this._padTextLeft("#", 3) + pad1em +
this._padTextRight("Item", 11) + pad1em +
this._padTextAround("Remaining, pcs.", 7) + pad1em +
this._padTextAround("Price, ₢ ", 7) + pad1em;

var tableRows = Array(this.$items.length);
for(var i = 0; i < this.$items.length; i++) {
var item = this.$items[i];
tableRows[i] = this._padTextLeft(i + 1, 3) + pad1em +
this._padTextRight(item.name, 11) + pad1em +
this._padTextAround(item.quantity, 7) + pad1em +
this._padTextLeft(formatCredits(item.price), 7) + pad1em;
}

// Concatenate them in one string if you want to display
// the table as "message" on the mission screen
var table = tableHeader + "\n" + tableRows.join("\n") + "\n\n";
</pre>

[[User:Alaric/KV-16 Owners Manual|Alaric's unfinished Torus-field-monitor OXZ]] contains handy function to help format text in tabular layout for use in mission screens/MFDs. See his alaric-oxp-utilities.js file:
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
"use strict";

this.name = "alaric-oxp-utilities";
this.author = "Alaric";
this.copyright = "2016 Alaric";
this.description = "General helper functions for OXPs";
this.licence = "CC BY-NC-SA 3.0 AU";
this.version = "1.0";

/**
* Trims a length of text to fit in the available width. If the text is truncated,
* an ellipse (U+2026) will be appended unless <ellipses> is false. If <ellipses>
* is omitted from the call, it defaults to true.
*
* text - The text to trim
* emDisplayWidth - The available width, in Em, to display the text
* ellipses - optional (default: true)
*
* Returns the new, trimmed, string.
*/
this._trimTextToFitWidth = function(text, emDisplayWidth, ellipses)
{
var font = defaultFont;
var chPadding = String.fromCharCode(31);
var ellipsesText = "\u2026";
var emEllipsesText = font.measureString(ellipsesText);
var emPaddingText = font.measureString(chPadding);

var chWidth = [0, text.length];
var emWidth = [font.measureString(text), 0];

// use default for ellipses if not supplied
if (ellipses === null || ellipses === undefined) ellipses = true;

// if the text already fits, just return it.
if (emWidth[0] <= emDisplayWidth) return text;

// if the display width is too short for ellipses, disable ellipses
if (emEllipsesText >= emDisplayWidth) ellipses = false;

// subtract ellipses with from display width if ellipses is true
emDisplayWidth -= (ellipses) ? emEllipsesText : 0;

while (chWidth[0] != chWidth[1])
{
// get Em width of text at length midway between chWidth[0] and chWidth[1]
var chPivot = Math.ceil((chWidth[0] + chWidth[1]) / 2);
var emPivot = font.measureString(text.substring(0, chPivot));

// update for next split point based on the text being too long or too short
var flagDirection = (emPivot <= emDisplayWidth) ? 0 : 1;

chWidth[flagDirection] = chPivot - flagDirection;
emWidth[flagDirection] = emPivot;
}

// At this point, chWidth[0] and emWidth[0] contain the trimmed width in
// characters and Em respectively. Return the text, appending ellipses if
// <ellipses> is true. The space for ellipses has already been accounted
// for.

return (ellipses)
? text.substring(0, chWidth[0]) + ellipsesText
: text.substring(0, chWidth[0])
;
}

/*
* Builds tabular (columns aligned) text for use in mission screens/MFDs.
*
* Input to the function is provided by an array of 'rows'. Each row is, itself, an array of
* objects with the following properties:
*
* Required properties:
* text: The text to display in this column
* width: The width of the column in em. Text will be truncated if too long.
*
* Optional properties:
* alignment: LEFT, RIGHT or CENTER. Default: LEFT
* elipses: Display elipses for truncated text? Default: true.
* blink:
*
* Multiple rows are deliniated by '\n'. No '\n' is appended to the last row.
*
*/
this._buildTabularText = function(rows)
{
var padCharacter = String.fromCharCode(31);
var padWidth = defaultFont.measureString(padCharacter);
var tabularText = "";
var row;

for (row = 0; row < rows.length; ++row)
{
if (row > 0) tabularText += "\n";

var i;

var currentEm0 = 0;
var currentEm1 = 0;
var columns = rows[row];
var rowText = "";

for (i = 0; i < columns.length; ++i)
{

currentEm0 = defaultFont.measureString(rowText);
var leading = (currentEm1 - currentEm0);
currentEm1 = currentEm1 + columns[i].width;

var text = this._trimTextToFitWidth(columns[i].text, currentEm1 - currentEm0, columns[i].ellipses);
var width = defaultFont.measureString(text);

var padding = (currentEm1 - currentEm0) - width;

switch ((columns[i].alignment !== undefined) ? columns[i].alignment : "LEFT")
{

case "LEFT" : padding = 0; break;
case "RIGHT" : leading = 0; break;
case "CENTER" : padding = padding / 2; break;

default:
log(this.name, "invalid alignment '" + columns[i].alignment + "'");
padding = 0; break;

}

padding = Math.floor((leading + padding) / padWidth);

rowText += (padding >= 1)
? new Array(padding).join(padCharacter) + text
: text
;
}

tabularText += rowText;
}

return tabularText;
}
</pre>

You can use it like this:
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
var rows = [
[ /* header */
{ width: 32, alignment: "CENTER", text: "Fleet status" }
],

[ /* line spacer */
],

[ /* row 1 */

{ width: 1.5, text: "" }, // spacer
{ width: 20.5, alignment: "LEFT", text: "Ship" },
{ width: 10, alignment: "RIGHT", text: "Maintenance" }
],
[ /* row 2 */
{ width: 1, alignment: "RIGHT", text: "1" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Cobra Mk III" },
{ width: 2.5, alignment: "RIGHT", text: "10%" }
],

[ /* row 3 */
{ width: 1, alignment: "RIGHT", text: "2" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, text: "Krait" },
{ width: 2.5, alignment: "RIGHT", text: "7%" }
],

[ /* row 4 */
{ width: 1, alignment: "RIGHT", text: "3" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Unrealisticly long ship class name that happens to be not so long for mission screen" },
{ width: 2.5, alignment: "RIGHT", text: "100%" }
],

[ /* row 5 */
{ width: 1, alignment: "RIGHT", text: "4" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Unrealisticly long name without ellipses that happens to be not so long for mission screen", ellipses: false },
{ width: 2.5, alignment: "RIGHT", text: "100%" }
],

[
],

[
{ width: 32, alignment: "CENTER", text: "Next enemy group encounter in 4 hours" }
]
]

);

var utils = worldScripts["alaric-oxp-utilities"]; // Get world script object if you copied entire file to your OXP
var messageText = utils._buildTabularText(rows); // or use this._buildTabularText(rows), if you copied just that funtions in your world script

mission.runScreen({
title: "Statistics",
screenID: "oxpname-stats-fleet"
message: messageText
});
</pre>



== Backdrop ==
: This is managed from within the script.js file:
background: ""the_file_name_of_the_image_you_want_to_display_must_be_in_the_images_folder.png",
or you can use ''overlay'' instead of ''background'' (less conflicts with other oxp's such as XenonUI which also tend to specify a background)

=== Problems with Backdrop ===
These can be prevented from appearing by other oxp's such as [[XenonUI]] which also create backdrops for the docked screens.

Using ''overlay'' helps, but also see Phkb's comments [http://aegidian.org/bb/viewtopic.php?p=282180#p282180 here] (for Dark Side solutions) and [http://aegidian.org/bb/viewtopic.php?p=278857#p278857 here] (using Library config).

== Exit Screen ==
By default, when the mission screen ends, the game returns to the status screen (F5), but this behavior can be changed.
In most cases you can just provide the <code>exitScreen</code> parameter to the <code>[[Oolite JavaScript Reference: Mission#runScreen|mission.runScreen]]</code> call, but if
if the exit screen depends on the player's choice, you need change the exit screen in the mission screen callback by setting <code>[[Oolite JavaScript Reference: Mission#exitScreen|mission.exitScreen]]</code>. Outside of a callback function, the value of this is almost meaningless, and setting it has no useful effect.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show example" data-collapsetext="Hide example" style="max-width:max-content">
The example below uses both ways: <span style="visibility: hidden">    Show Example</span>
<pre style="width:max-content" class="mw-collapsible-content">
this._runMissionScreen = function _runMissionScreen()
{
mission.runScreen(
{
title: "Exit Screen Example",
exitScreen: "GUI_SCREEN_MARKET", // <-- The first way
choices: {
"01_INTERFACES": "Do nothing",
"02_CHART": "Set mission.exitScreen to \"GUI_SCREEN_SHORT_RANGE_CHART\"",
"03_SYSDATA": "Set mission.exitScreen to \"GUI_SCREEN_SYSTEM_DATA\"",
"04_INVALID": "Set mission.exitScreen to \"INVALID VALUE\"",
}
},
this._missionScreenCallback.bind(this)
);
// The mission.exitScreen variable is set to the value
// of the exitScreen parameter of the function call above
mission.addMessageText("Current exit screen is " + mission.exitScreen + ".");
};

this._missionScreenCallback = function _missionScreenCallback(choice)
{
// The choice is null when player interrupts the mission screen (e.g., presses F1 )
if (choice === "01_INTERFACES" || choice === null) {
// Do nothing - the exit screen will be as specified in runScreen call
}
else if (choice === "02_CHART") {
mission.exitScreen = "GUI_SCREEN_SHORT_RANGE_CHART"; // <-- The second way
}
else if (choice === "03_SYSDATA") {
mission.exitScreen = "GUI_SCREEN_SYSTEM_DATA";
}
else if (choice === "04_INVALID") {
mission.exitScreen = "INVALID VALUE"; // The exit screen will be reset to default
}
};

// Add interface to F4 page for docked station
this.startUpComplete = function startUpComplete()
{
player.ship.dockedStation.setInterface("example_exit_screen",
{
title: "Show exitScreen example screen",
summary: "This is an example interface definition.",
category: "AAA",
callback: this._runMissionScreen.bind(this)
}
);
};
</pre>
</div>

[[Image:Lib_Starmap02.png|320px|thumb|right|Library OXP Demos: Starmap (animated)]]
== Visual Mission screens ==
It is possible to have animations or cutscenes instead. These require either Library.oxp or the deprecated CCL.

These two oxp's allow for more complex interractions. See [[Library OXP]]'s "Music" and the two "Demos" (Starmap & Animator). And see also the deprecated [[CCL]]'s never-used [[Cutscene]].

== Links ==
*[http://aegidian.org/bb/viewtopic.php?p=276448#p276448 Creating a mission screen] for textual messages (2021)
*[http://www.aegidian.org/bb/viewtopic.php?p=283395#p283395 Changing text colour] (2022)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18713 New Line in mission.runScreen?] (2017)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18414 Tabular text output for MFDs/mission screens] (2016)
=== Useful OXPs ===
*[[HDBG]] - High Definition BackGrounds - provides background pictures for Mission Screens
*HDBG Image Pack A (alas, Image Pack B never emerged...)
*[[Library OXP]] - enables animated Mission Screens

[[Category:Oolite scripting]]

Mission screen

2023-02-08T23:19:39Z

Alnivel: /* Alignment */ Changed appearance of code blocks

{{OXPNote|This Page is a WIP aimed at dumb pilots like myself!}}

[[File:Hints.png|right|320px]]
Mission screens started off as screens which allow the player to interface with NPCs in a mission.oxp but also allow other sorts of "communication" as in the conversation overheard in the bar in the [[Hints]] OXP.

They can have backdrops, changes in text and allow choices for the player.

The text can be placed in a descriptions.plist, details about it in a script.js

== Text ==
:Several spacial characters are used in determining the layout of the text, just as in Wiki.
\" Enables the use of colons.
\\n Insert a hard Enter.

In XML:
\n Inserts a hard Enter.

:See [[Missiontext.plist]] for more complexity (''eg'' random names, naming current system ''etc'')

:Character '31' (hex:1F, octal:037) is a narrow 'hair-space'. Custom font OXPs should ensure that this character is blank and has the same narrow width as the core font definition, as it is used to allow an equivalent to 'tab stops' in mission text.

=== % codes ===
Here are the % codes that can be used inside description strings and what each one does:

Code:
* %H is replaced with <planetName>. If systemName is nil, a planet name is retrieved through -[Universe getSystemName:], treating <seed> as a system seed. <br>
* %I is equivalent to "%H[planetname-derivative-suffix]".<br>
* %N is replaced with a random "alien" name using the planet name digraphs. If used more than once in the same string, it will produce the same name on each occurence.
* %R is like %N but, due to a bug, misses some possibilities. Deprecated.
* %JNNN, where NNN is a three-digit integer, is replaced with the name of system ID NNN in the current galaxy.
* %GNNNNNN, where NNNNNN is a six-digit integer, is replaced with the name of system ID NNN (first triplet) in the specified galaxy (second triplet).
* %% is replaced with %.
* %[ is replaced with [.
* %] is replaced with ].
:From [[String expansion]]

== Colour ==
:Choices can be non-yellow (have a look at the various contracts interfaces in 1.77) but there is a more fundamental limitation of the current UI code that all text on a particular line has to be the same colour. [http://www.aegidian.org/bb/viewtopic.php?p=203777#p203777 Cim (2013)]

:Code for [http://www.aegidian.org/bb/viewtopic.php?p=283402#p283402 Colour change]

[[File:First Finance Loan Management.png|right|200px]]
== Alignment ==
There is no obvious way to do this, but [[User:Ocz|Ocz]] managed some version of right alignment for his [[First Finance OXP]]

=== Tabular layout ===
When you need to get something in the form of a table or columns, you can use padText-like functions to adjust the padding of the desired width to labels and data, and then concatenate them into one line, just keep in mind that max row length is 32 em.
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
var pad1em = this._padTextLeft("", 1);
var tableHeader = this._padTextLeft("#", 3) + pad1em +
this._padTextRight("Item", 11) + pad1em +
this._padTextAround("Remaining, pcs.", 7) + pad1em +
this._padTextAround("Price, ₢ ", 7) + pad1em;

var tableRows = Array(this.$items.length);
for(var i = 0; i < this.$items.length; i++) {
var item = this.$items[i];
tableRows[i] = this._padTextLeft(i + 1, 3) + pad1em +
this._padTextRight(item.name, 11) + pad1em +
this._padTextAround(item.quantity, 7) + pad1em +
this._padTextLeft(formatCredits(item.price), 7) + pad1em;
}

// Concatenate them in one string if you want to display
// the table as "message" on the mission screen
var table = tableHeader + "\n" + tableRows.join("\n") + "\n\n";
</pre>

[[User:Alaric/KV-16 Owners Manual|Alaric's unfinished Torus-field-monitor OXZ]] contains handy function to help format text in tabular layout for use in mission screens/MFDs. See his alaric-oxp-utilities.js file:
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
"use strict";

this.name = "alaric-oxp-utilities";
this.author = "Alaric";
this.copyright = "2016 Alaric";
this.description = "General helper functions for OXPs";
this.licence = "CC BY-NC-SA 3.0 AU";
this.version = "1.0";

/**
* Trims a length of text to fit in the available width. If the text is truncated,
* an ellipse (U+2026) will be appended unless <ellipses> is false. If <ellipses>
* is omitted from the call, it defaults to true.
*
* text - The text to trim
* emDisplayWidth - The available width, in Em, to display the text
* ellipses - optional (default: true)
*
* Returns the new, trimmed, string.
*/
this._trimTextToFitWidth = function(text, emDisplayWidth, ellipses)
{
var font = defaultFont;
var chPadding = String.fromCharCode(31);
var ellipsesText = "\u2026";
var emEllipsesText = font.measureString(ellipsesText);
var emPaddingText = font.measureString(chPadding);

var chWidth = [0, text.length];
var emWidth = [font.measureString(text), 0];

// use default for ellipses if not supplied
if (ellipses === null || ellipses === undefined) ellipses = true;

// if the text already fits, just return it.
if (emWidth[0] <= emDisplayWidth) return text;

// if the display width is too short for ellipses, disable ellipses
if (emEllipsesText >= emDisplayWidth) ellipses = false;

// subtract ellipses with from display width if ellipses is true
emDisplayWidth -= (ellipses) ? emEllipsesText : 0;

while (chWidth[0] != chWidth[1])
{
// get Em width of text at length midway between chWidth[0] and chWidth[1]
var chPivot = Math.ceil((chWidth[0] + chWidth[1]) / 2);
var emPivot = font.measureString(text.substring(0, chPivot));

// update for next split point based on the text being too long or too short
var flagDirection = (emPivot <= emDisplayWidth) ? 0 : 1;

chWidth[flagDirection] = chPivot - flagDirection;
emWidth[flagDirection] = emPivot;
}

// At this point, chWidth[0] and emWidth[0] contain the trimmed width in
// characters and Em respectively. Return the text, appending ellipses if
// <ellipses> is true. The space for ellipses has already been accounted
// for.

return (ellipses)
? text.substring(0, chWidth[0]) + ellipsesText
: text.substring(0, chWidth[0])
;
}

/*
* Builds tabular (columns aligned) text for use in mission screens/MFDs.
*
* Input to the function is provided by an array of 'rows'. Each row is, itself, an array of
* objects with the following properties:
*
* Required properties:
* text: The text to display in this column
* width: The width of the column in em. Text will be truncated if too long.
*
* Optional properties:
* alignment: LEFT, RIGHT or CENTER. Default: LEFT
* elipses: Display elipses for truncated text? Default: true.
* blink:
*
* Multiple rows are deliniated by '\n'. No '\n' is appended to the last row.
*
*/
this._buildTabularText = function(rows)
{
var padCharacter = String.fromCharCode(31);
var padWidth = defaultFont.measureString(padCharacter);
var tabularText = "";
var row;

for (row = 0; row < rows.length; ++row)
{
if (row > 0) tabularText += "\n";

var i;

var currentEm0 = 0;
var currentEm1 = 0;
var columns = rows[row];
var rowText = "";

for (i = 0; i < columns.length; ++i)
{

currentEm0 = defaultFont.measureString(rowText);
var leading = (currentEm1 - currentEm0);
currentEm1 = currentEm1 + columns[i].width;

var text = this._trimTextToFitWidth(columns[i].text, currentEm1 - currentEm0, columns[i].ellipses);
var width = defaultFont.measureString(text);

var padding = (currentEm1 - currentEm0) - width;

switch ((columns[i].alignment !== undefined) ? columns[i].alignment : "LEFT")
{

case "LEFT" : padding = 0; break;
case "RIGHT" : leading = 0; break;
case "CENTER" : padding = padding / 2; break;

default:
log(this.name, "invalid alignment '" + columns[i].alignment + "'");
padding = 0; break;

}

padding = Math.floor((leading + padding) / padWidth);

rowText += (padding >= 1)
? new Array(padding).join(padCharacter) + text
: text
;
}

tabularText += rowText;
}

return tabularText;
}
</pre>

You can use it like this:
<pre style="max-width: max-content; max-height: 40vh; overflow-y: auto;">
var rows = [
[ /* header */
{ width: 32, alignment: "CENTER", text: "Fleet status" }
],

[ /* line spacer */
],

[ /* row 1 */

{ width: 1.5, text: "" }, // spacer
{ width: 20.5, alignment: "LEFT", text: "Ship" },
{ width: 10, alignment: "RIGHT", text: "Maintenance" }
],
[ /* row 2 */
{ width: 1, alignment: "RIGHT", text: "1" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Cobra Mk III" },
{ width: 2.5, alignment: "RIGHT", text: "10%" }
],

[ /* row 3 */
{ width: 1, alignment: "RIGHT", text: "2" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, text: "Krait" },
{ width: 2.5, alignment: "RIGHT", text: "7%" }
],

[ /* row 4 */
{ width: 1, alignment: "RIGHT", text: "3" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Unrealisticly long ship class name that happens to be not so long for mission screen" },
{ width: 2.5, alignment: "RIGHT", text: "100%" }
],

[ /* row 5 */
{ width: 1, alignment: "RIGHT", text: "4" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Unrealisticly long name without ellipses that happens to be not so long for mission screen", ellipses: false },
{ width: 2.5, alignment: "RIGHT", text: "100%" }
],

[
],

[
{ width: 32, alignment: "CENTER", text: "Next enemy group encounter in 4 hours" }
]
]

);

var utils = worldScripts["alaric-oxp-utilities"]; // Get world script object if you copied entire file to your OXP
var messageText = utils._buildTabularText(rows); // or use this._buildTabularText(rows), if you copied just that funtions in your world script

mission.runScreen({
title: "Statistics",
screenID: "oxpname-stats-fleet"
message: messageText
});
</pre>



== Backdrop ==
: This is managed from within the script.js file:
background: ""the_file_name_of_the_image_you_want_to_display_must_be_in_the_images_folder.png",
or you can use ''overlay'' instead of ''background'' (less conflicts with other oxp's such as XenonUI which also tend to specify a background)

=== Problems with Backdrop ===
These can be prevented from appearing by other oxp's such as [[XenonUI]] which also create backdrops for the docked screens.

Using ''overlay'' helps, but also see Phkb's comments [http://aegidian.org/bb/viewtopic.php?p=282180#p282180 here] (for Dark Side solutions) and [http://aegidian.org/bb/viewtopic.php?p=278857#p278857 here] (using Library config).

== Exit Screen ==
By default, when the mission screen ends, the game returns to the status screen (F5), but this behavior can be changed.
In most cases you can just provide the <code>exitScreen</code> parameter to the <code>[[Oolite JavaScript Reference: Mission#runScreen|mission.runScreen]]</code> call, but if
if the exit screen depends on the player's choice, you need change the exit screen in the mission screen callback by setting <code>[[Oolite JavaScript Reference: Mission#exitScreen|mission.exitScreen]]</code>. Outside of a callback function, the value of this is almost meaningless, and setting it has no useful effect.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show example" data-collapsetext="Hide example" style="max-width:max-content">
The example below uses both ways: <span style="visibility: hidden">    Show Example</span>
<pre style="width:max-content" class="mw-collapsible-content">
this._runMissionScreen = function _runMissionScreen()
{
mission.runScreen(
{
title: "Exit Screen Example",
exitScreen: "GUI_SCREEN_MARKET", // <-- The first way
choices: {
"01_INTERFACES": "Do nothing",
"02_CHART": "Set mission.exitScreen to \"GUI_SCREEN_SHORT_RANGE_CHART\"",
"03_SYSDATA": "Set mission.exitScreen to \"GUI_SCREEN_SYSTEM_DATA\"",
"04_INVALID": "Set mission.exitScreen to \"INVALID VALUE\"",
}
},
this._missionScreenCallback.bind(this)
);
// The mission.exitScreen variable is set to the value
// of the exitScreen parameter of the function call above
mission.addMessageText("Current exit screen is " + mission.exitScreen + ".");
};

this._missionScreenCallback = function _missionScreenCallback(choice)
{
// The choice is null when player interrupts the mission screen (e.g., presses F1 )
if (choice === "01_INTERFACES" || choice === null) {
// Do nothing - the exit screen will be as specified in runScreen call
}
else if (choice === "02_CHART") {
mission.exitScreen = "GUI_SCREEN_SHORT_RANGE_CHART"; // <-- The second way
}
else if (choice === "03_SYSDATA") {
mission.exitScreen = "GUI_SCREEN_SYSTEM_DATA";
}
else if (choice === "04_INVALID") {
mission.exitScreen = "INVALID VALUE"; // The exit screen will be reset to default
}
};

// Add interface to F4 page for docked station
this.startUpComplete = function startUpComplete()
{
player.ship.dockedStation.setInterface("example_exit_screen",
{
title: "Show exitScreen example screen",
summary: "This is an example interface definition.",
category: "AAA",
callback: this._runMissionScreen.bind(this)
}
);
};
</pre>
</div>

== Svengali's Library & CCL ==
These two oxp's allow for more complex interractions. See the deprecated [[CCL]]'s never used [[Cutscene]], as well as the current [[Library OXP]]'s "Music" and "Demos".

== Links ==
*[http://aegidian.org/bb/viewtopic.php?p=276448#p276448 Creating a mission screen] for textual messages (2021)
*[http://www.aegidian.org/bb/viewtopic.php?p=283395#p283395 Changing text colour] (2022)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18713 New Line in mission.runScreen?] (2017)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18414 Tabular text output for MFDs/mission screens] (2016)

[[Category:Oolite scripting]]

Mission screen

2023-02-08T22:12:57Z

Alnivel: /* Alignment */ Added examples how to use pad function for tables and how to use Alaric's code

{{OXPNote|This Page is a WIP aimed at dumb pilots like myself!}}

[[File:Hints.png|right|320px]]
Mission screens started off as screens which allow the player to interface with NPCs in a mission.oxp but also allow other sorts of "communication" as in the conversation overheard in the bar in the [[Hints]] OXP.

They can have backdrops, changes in text and allow choices for the player.

The text can be placed in a descriptions.plist, details about it in a script.js

== Text ==
:Several spacial characters are used in determining the layout of the text, just as in Wiki.
\" Enables the use of colons.
\\n Insert a hard Enter.

In XML:
\n Inserts a hard Enter.

:See [[Missiontext.plist]] for more complexity (''eg'' random names, naming current system ''etc'')

:Character '31' (hex:1F, octal:037) is a narrow 'hair-space'. Custom font OXPs should ensure that this character is blank and has the same narrow width as the core font definition, as it is used to allow an equivalent to 'tab stops' in mission text.

=== % codes ===
Here are the % codes that can be used inside description strings and what each one does:

Code:
* %H is replaced with <planetName>. If systemName is nil, a planet name is retrieved through -[Universe getSystemName:], treating <seed> as a system seed. <br>
* %I is equivalent to "%H[planetname-derivative-suffix]".<br>
* %N is replaced with a random "alien" name using the planet name digraphs. If used more than once in the same string, it will produce the same name on each occurence.
* %R is like %N but, due to a bug, misses some possibilities. Deprecated.
* %JNNN, where NNN is a three-digit integer, is replaced with the name of system ID NNN in the current galaxy.
* %GNNNNNN, where NNNNNN is a six-digit integer, is replaced with the name of system ID NNN (first triplet) in the specified galaxy (second triplet).
* %% is replaced with %.
* %[ is replaced with [.
* %] is replaced with ].
:From [[String expansion]]

== Colour ==
:Choices can be non-yellow (have a look at the various contracts interfaces in 1.77) but there is a more fundamental limitation of the current UI code that all text on a particular line has to be the same colour. [http://www.aegidian.org/bb/viewtopic.php?p=203777#p203777 Cim (2013)]

:Code for [http://www.aegidian.org/bb/viewtopic.php?p=283402#p283402 Colour change]

[[File:First Finance Loan Management.png|right|200px]]
== Alignment ==
There is no obvious way to do this, but [[User:Ocz|Ocz]] managed some version of right alignment for his [[First Finance OXP]]

=== Tabular layout ===
When you need to get something in the form of a table or columns, you can use padText-like functions to adjust the padding of the desired width to labels and data, and then concatenate them into one line, just keep in mind that max row length is 32 em.
<pre style="max-width:max-content">
var pad1em = this._padTextLeft("", 1);
var tableHeader = this._padTextLeft("#", 3) + pad1em +
this._padTextRight("Item", 11) + pad1em +
this._padTextAround("Remaining, pcs.", 7) + pad1em +
this._padTextAround("Price, ₢ ", 7) + pad1em;

var tableRows = Array(this.$items.length);
for(var i = 0; i < this.$items.length; i++) {
var item = this.$items[i];
tableRows[i] = this._padTextLeft(i + 1, 3) + pad1em +
this._padTextRight(item.name, 11) + pad1em +
this._padTextAround(item.quantity, 7) + pad1em +
this._padTextLeft(formatCredits(item.price), 7) + pad1em;
}

// Concatenate them in one string if you want to display
// the table as "message" on the mission screen
var table = tableHeader + "\n" + tableRows.join("\n") + "\n\n";
</pre>

[[User:Alaric/KV-16 Owners Manual|Alaric's unfinished Torus-field-monitor OXZ]] contains handy function to help format text in tabular layout for use in mission screens/MFDs.
<div class="mw-collapsible mw-collapsed" data-expandtext="Show code" data-collapsetext="Hide code" style="max-width:max-content">
See his alaric-oxp-utilities.js file: <span style="visibility: hidden">    Show code</span>
<pre style="width:max-content" class="mw-collapsible-content">
"use strict";

this.name = "alaric-oxp-utilities";
this.author = "Alaric";
this.copyright = "2016 Alaric";
this.description = "General helper functions for OXPs";
this.licence = "CC BY-NC-SA 3.0 AU";
this.version = "1.0";

/**
* Trims a length of text to fit in the available width. If the text is truncated,
* an ellipse (U+2026) will be appended unless <ellipses> is false. If <ellipses>
* is omitted from the call, it defaults to true.
*
* text - The text to trim
* emDisplayWidth - The available width, in Em, to display the text
* ellipses - optional (default: true)
*
* Returns the new, trimmed, string.
*/
this._trimTextToFitWidth = function(text, emDisplayWidth, ellipses)
{
var font = defaultFont;
var chPadding = String.fromCharCode(31);
var ellipsesText = "\u2026";
var emEllipsesText = font.measureString(ellipsesText);
var emPaddingText = font.measureString(chPadding);

var chWidth = [0, text.length];
var emWidth = [font.measureString(text), 0];

// use default for ellipses if not supplied
if (ellipses === null || ellipses === undefined) ellipses = true;

// if the text already fits, just return it.
if (emWidth[0] <= emDisplayWidth) return text;

// if the display width is too short for ellipses, disable ellipses
if (emEllipsesText >= emDisplayWidth) ellipses = false;

// subtract ellipses with from display width if ellipses is true
emDisplayWidth -= (ellipses) ? emEllipsesText : 0;

while (chWidth[0] != chWidth[1])
{
// get Em width of text at length midway between chWidth[0] and chWidth[1]
var chPivot = Math.ceil((chWidth[0] + chWidth[1]) / 2);
var emPivot = font.measureString(text.substring(0, chPivot));

// update for next split point based on the text being too long or too short
var flagDirection = (emPivot <= emDisplayWidth) ? 0 : 1;

chWidth[flagDirection] = chPivot - flagDirection;
emWidth[flagDirection] = emPivot;
}

// At this point, chWidth[0] and emWidth[0] contain the trimmed width in
// characters and Em respectively. Return the text, appending ellipses if
// <ellipses> is true. The space for ellipses has already been accounted
// for.

return (ellipses)
? text.substring(0, chWidth[0]) + ellipsesText
: text.substring(0, chWidth[0])
;
}

/*
* Builds tabular (columns aligned) text for use in mission screens/MFDs.
*
* Input to the function is provided by an array of 'rows'. Each row is, itself, an array of
* objects with the following properties:
*
* Required properties:
* text: The text to display in this column
* width: The width of the column in em. Text will be truncated if too long.
*
* Optional properties:
* alignment: LEFT, RIGHT or CENTER. Default: LEFT
* elipses: Display elipses for truncated text? Default: true.
* blink:
*
* Multiple rows are deliniated by '\n'. No '\n' is appended to the last row.
*
*/
this._buildTabularText = function(rows)
{
var padCharacter = String.fromCharCode(31);
var padWidth = defaultFont.measureString(padCharacter);
var tabularText = "";
var row;

for (row = 0; row < rows.length; ++row)
{
if (row > 0) tabularText += "\n";

var i;

var currentEm0 = 0;
var currentEm1 = 0;
var columns = rows[row];
var rowText = "";

for (i = 0; i < columns.length; ++i)
{

currentEm0 = defaultFont.measureString(rowText);
var leading = (currentEm1 - currentEm0);
currentEm1 = currentEm1 + columns[i].width;

var text = this._trimTextToFitWidth(columns[i].text, currentEm1 - currentEm0, columns[i].ellipses);
var width = defaultFont.measureString(text);

var padding = (currentEm1 - currentEm0) - width;

switch ((columns[i].alignment !== undefined) ? columns[i].alignment : "LEFT")
{

case "LEFT" : padding = 0; break;
case "RIGHT" : leading = 0; break;
case "CENTER" : padding = padding / 2; break;

default:
log(this.name, "invalid alignment '" + columns[i].alignment + "'");
padding = 0; break;

}

padding = Math.floor((leading + padding) / padWidth);

rowText += (padding >= 1)
? new Array(padding).join(padCharacter) + text
: text
;
}

tabularText += rowText;
}

return tabularText;
}
</pre>
</div>
<div class="mw-collapsible mw-collapsed" data-expandtext="Show example" data-collapsetext="Hide example" style="max-width:max-content">
You can use it like this: <span style="visibility: hidden">    Show example</span>
<div style="width:max-content" class="mw-collapsible-content">
<pre>
var rows = [
[ /* header */
{ width: 32, alignment: "CENTER", text: "Fleet status" }
],

[ /* line spacer */
],

[ /* row 1 */

{ width: 1.5, text: "" }, // spacer
{ width: 20.5, alignment: "LEFT", text: "Ship" },
{ width: 10, alignment: "RIGHT", text: "Maintenance" }
],
[ /* row 2 */
{ width: 1, alignment: "RIGHT", text: "1" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Cobra Mk III" },
{ width: 2.5, alignment: "RIGHT", text: "10%" }
],

[ /* row 3 */
{ width: 1, alignment: "RIGHT", text: "2" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, text: "Krait" },
{ width: 2.5, alignment: "RIGHT", text: "7%" }
],

[ /* row 4 */
{ width: 1, alignment: "RIGHT", text: "3" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Unrealisticly long ship class name that happens to be not so long for mission screen" },
{ width: 2.5, alignment: "RIGHT", text: "100%" }
],

[ /* row 5 */
{ width: 1, alignment: "RIGHT", text: "4" },
{ width: 0.5, alignment: "RIGHT", text: "" }, // spacer
{ width: 28, alignment: "LEFT", text: "Unrealisticly long name without ellipses that happens to be not so long for mission screen", ellipses: false },
{ width: 2.5, alignment: "RIGHT", text: "100%" }
],

[
],

[
{ width: 32, alignment: "CENTER", text: "Next enemy grooup encounter in 4 hours" }
]
]

);

var utils = worldScripts["alaric-oxp-utilities"]; // Get world script object if you copied entire file to your OXP
var messageText = utils._buildTabularText(rows); // or use this._buildTabularText(rows), if you copied just that funtions in your world script

mission.runScreen({
title: "Statistics",
screenID: "oxpname-stats-fleet"
message: messageText
});
</pre>



</div>
</div>

== Backdrop ==
: This is managed from within the script.js file:
background: ""the_file_name_of_the_image_you_want_to_display_must_be_in_the_images_folder.png",
or you can use ''overlay'' instead of ''background'' (less conflicts with other oxp's such as XenonUI which also tend to specify a background)

=== Problems with Backdrop ===
These can be prevented from appearing by other oxp's such as [[XenonUI]] which also create backdrops for the docked screens.

Using ''overlay'' helps, but also see Phkb's comments [http://aegidian.org/bb/viewtopic.php?p=282180#p282180 here] (for Dark Side solutions) and [http://aegidian.org/bb/viewtopic.php?p=278857#p278857 here] (using Library config).

== Exit Screen ==
By default, when the mission screen ends, the game returns to the status screen (F5), but this behavior can be changed.
In most cases you can just provide the <code>exitScreen</code> parameter to the <code>[[Oolite JavaScript Reference: Mission#runScreen|mission.runScreen]]</code> call, but if
if the exit screen depends on the player's choice, you need change the exit screen in the mission screen callback by setting <code>[[Oolite JavaScript Reference: Mission#exitScreen|mission.exitScreen]]</code>. Outside of a callback function, the value of this is almost meaningless, and setting it has no useful effect.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show example" data-collapsetext="Hide example" style="max-width:max-content">
The example below uses both ways: <span style="visibility: hidden">    Show Example</span>
<pre style="width:max-content" class="mw-collapsible-content">
this._runMissionScreen = function _runMissionScreen()
{
mission.runScreen(
{
title: "Exit Screen Example",
exitScreen: "GUI_SCREEN_MARKET", // <-- The first way
choices: {
"01_INTERFACES": "Do nothing",
"02_CHART": "Set mission.exitScreen to \"GUI_SCREEN_SHORT_RANGE_CHART\"",
"03_SYSDATA": "Set mission.exitScreen to \"GUI_SCREEN_SYSTEM_DATA\"",
"04_INVALID": "Set mission.exitScreen to \"INVALID VALUE\"",
}
},
this._missionScreenCallback.bind(this)
);
// The mission.exitScreen variable is set to the value
// of the exitScreen parameter of the function call above
mission.addMessageText("Current exit screen is " + mission.exitScreen + ".");
};

this._missionScreenCallback = function _missionScreenCallback(choice)
{
// The choice is null when player interrupts the mission screen (e.g., presses F1 )
if (choice === "01_INTERFACES" || choice === null) {
// Do nothing - the exit screen will be as specified in runScreen call
}
else if (choice === "02_CHART") {
mission.exitScreen = "GUI_SCREEN_SHORT_RANGE_CHART"; // <-- The second way
}
else if (choice === "03_SYSDATA") {
mission.exitScreen = "GUI_SCREEN_SYSTEM_DATA";
}
else if (choice === "04_INVALID") {
mission.exitScreen = "INVALID VALUE"; // The exit screen will be reset to default
}
};

// Add interface to F4 page for docked station
this.startUpComplete = function startUpComplete()
{
player.ship.dockedStation.setInterface("example_exit_screen",
{
title: "Show exitScreen example screen",
summary: "This is an example interface definition.",
category: "AAA",
callback: this._runMissionScreen.bind(this)
}
);
};
</pre>
</div>

== Svengali's Library & CCL ==
These two oxp's allow for more complex interractions. See the deprecated [[CCL]]'s never used [[Cutscene]], as well as the current [[Library OXP]]'s "Music" and "Demos".

== Links ==
*[http://aegidian.org/bb/viewtopic.php?p=276448#p276448 Creating a mission screen] for textual messages (2021)
*[http://www.aegidian.org/bb/viewtopic.php?p=283395#p283395 Changing text colour] (2022)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18713 New Line in mission.runScreen?] (2017)
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=18414 Tabular text output for MFDs/mission screens] (2016)

[[Category:Oolite scripting]]

Mission screen

2023-02-08T18:58:46Z

Alnivel: Moved Alaric's code for tabular layout to Alignment section

Mission screen

2023-02-08T15:04:00Z

Alnivel: Fixed an accidentally removed section header

Mission screen

2023-02-08T14:56:34Z

Alnivel: /* Exit Screen */ Added about mission.exitScreen and an example

Personalities OXP

2022-11-28T09:18:13Z

Alnivel: /* Notes on original version 0.9 (2009) */ Moved instructions to a new section & added some styling

Adds Oolite community personalities to your game
[[File:Lestradae.png|right|400px]]
== Overview ==
This [[OXP]] adds characters we all know and love from the [http://www.aegidian.org/bb Oolite Bulletin Boards] to the Ooniverse. Each personality has some specific behaviour and communication patterns.

== Notable Features ==
There is a 65% chance that you will meet one well-known personality when you either jump into a new system or launch from a main station. Some of them are traders or engage in asteroid mining, some of them are bounty hunters and will protect you in case a pirate attacks you—or attack you in case you are the pirate. Some will only engage Thargoids. And some greet you friendly first, but may try to make you one more step on their ELITE ladder if nobody else is looking. Their behaviour in combat varies, but expect all of them to be a little tougher than your average adversary.

A list of the personalities contained in the basic OXP can be found at the very bottom of its ReadMe, separated by enough whitespace. If you like to be surprised, don't scroll down.

== Notes on Alnivel's update version 0.91 (2022) ==
Update of the original 10 personalities to work with newer versions of Oolite. Adds more options.

== Notes on original version 0.9 (2009)==
=== DISCLAIMER ===
Personalities.oxp is a '''work in progress''', and this version 0.9 is meant as a sneak preview, to give you a feeling what it looks like. It works as it is, but the final release may be different. Please help improving it by reporting bugs and strange or unexpected behaviour in [http://aegidian.org/bb/viewtopic.php?t=6806 its thread on the Oolite Bulletin Boards]. Thanks very much!

== Instructions ==

=== How do I add myself as a character? ===
<span id="Adding_yourself_as_a_character"></span> 

'''Note:''' Take this instruction not as a “do it all yourself”, but rather as a reference in case you want to tweak something for yourself (or, well, do everything all yourself). You can always ask for help in the [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or even just leave a request there to be added.

You can do this either by modifying this OXP or by creating a separate one, but in any case, you will need at least basic knowledge of how to work on them. It is still preferable to be separate, but still choose as you like or can! A good starting point and reference would be [[OXP_howto|OXP howto]].

<div class="mw-collapsible mw-collapsed custom-collapsible-left-toggle" data-expandtext="Expand Instruction" data-collapsetext="Collapse Instruction" style="overflow:auto;">
'''Make an entry about your ship in [[shipdata.plist|shipdata.plist]]'''
#As a base you can take a entry from the game files or OXP or, if your ship is from OXP, from its files.
#Adjust the parameters so that they correspond to the specs of your ship in the game. Pay special attention to:
#* [[shipdata.plist#max_flight_speed|max_flight_speed]],
#* [[shipdata.plist#max_flight_pitch|max_flight_pitch]],
#* [[shipdata.plist#max_flight_roll|max_flight_roll]],
#* [[shipdata.plist#thrust|thrust]],
#* [[shipdata.plist#max_energy|max_energy]],
#* [[shipdata.plist#energy_recharge_rate|energy_recharge_rate]],
#* laser types (only [[shipdata.plist#forward_weapon_type|forward]] and [[shipdata.plist#aft_weapon_type|aft]] laser available),
#* [[shipdata.plist#laser_color|laser_color]],
#* the number of [[shipdata.plist#missiles|missiles]] you carry and their [[shipdata.plist#missile_role|main type]],
#* [[shipdata.plist#frangible|frangibility]] of your ship (if applicable),
#* installed equipment extras:
#** [[shipdata.plist#has_ecm|ECM]],
#** [[shipdata.plist#has_escape_pod|Escape Capsule]],
#** [[shipdata.plist#has_fuel_injection|Fuel Injectors]],
#** [[shipdata.plist#has_scoop|Fuel Scoops]],
#** [[shipdata.plist#has_shield_booster|Shield Boosters]],
#** [[shipdata.plist#has_shield_enhancer|Shield Enhancers]],
#** an Extra Energy Unit or Naval Energy Unit (will influence the [[shipdata.plist#max_energy|max_energy]]),
#** [[shipdata.plist#heat_insulation|Heat Shields]],
#** [[shipdata.plist#has_cloaking_device|Cloaking Device]],
#** [[shipdata.plist#has_energy_bomb|Q-bomb]]

'''Make sure that models, textures and shaders used be ship will be available not only for you'''

# Copy them to the appropriate folder of OXP.
# (Optional) It would be great if you change resource names, both filenames and references inside the models (.dat) and shipdata.plist, as this will help avoid conflicts.
::Model files are just regular text files, same as shipdata.plist, so they can be opened in a any decent text editor. It might be a good idea to use search and replace - one Griff's Cobra model has more than 800 lines with the name of the texture.

'''(Optional) Add a character entry in [[characters.plist|characters.plist]]'''

If you're carrying an escape capsule with you, you should create this entry, or one day a complete stranger will escape the ship instead of you!

Example of such a entry:
<pre>
"personalities-hesperus" = {
bounty = 150;
name = "Captain Jack Hesperus";
"random_seed" = "0 0 0 0 0 0";
"short_description" = "a notorious, feline trumble dealer from Orrira";
};
</pre>

'''Give your ship a personality (shipdata.plist)'''
:*'''[[shipdata.plist#name|name]]''' - <code>shipname: charactername</code>.
:*'''[[shipdata.plist#pilot|pilot]]''' - key of entry in characters.plist, for example,<code>personalities-hesperus</code>.
:*'''[[shipdata.plist#roles|roles]]''':
::: general role: <code>personalities</code>
::: occupation: <code>personalities_cruiser</code> (trader), <code>personalities_privateer</code> (pirate) or <code>personalities_hunter</code> (bounty hunter)
::: spawn options (several or even none may be specified):
::::<code>personalities_galaxy_any</code> - can appear in space or near main station in any galaxy
::::<code>personalities_launcher_galaxy_any</code> - can apear launching from main station in any galaxy (some ships are too big for that)
::::<code>personalities_galaxy_0</code>, <code>personalities_launcher_galaxy_0</code> - similar to 'any' variant but limited only to the Galaxy '''One'''.
::::<code>personalities_yourCharacterName</code> - opional but useful for testing
::::'''Examples:'''
::::# <code>personalities personalities_privateer personalities_galaxy_any personalities_launcher_galaxy_any personalities_aodhan</code> - pirate by name "Aodhan" that can appear in any galaxy both in space and via launch from main station,
::::# <code>personalities personalities_hunter personalities_galaxy_7 personalities_launcher_galaxy_7 personalities_cwydion</code> - bounty hunter by name "Gwydion" that can appear only in Galaxy Eight both in space and via launch from main station,
::::# <code>personalities personalities_cruiser personalities_galaxy_0 ppersonalities_galaxy_1 personalities_galaxy_2 personalities_jameson</code> - trader by name "Jameson" that can appear only in Galaxy One, Two and Three and only in space

:*'''[[shipdata.plist#ai_type|ai_type]]''' and '''[[shipdata.plist#script|script]]''' - there are two options here: plist AI or priority AI
::''Plist AI'' - relatively obsolete, but more straightforward for making your own tweaks:
::: '''ai_type''' - <code>personalitiesCruiserAI.plist</code>, <code>personalitiesHunterAI.plist</code> or <code>personalitiesPrivateerAI.plist</code>
::: '''script''' - <code>personalities-ship-script.js</code>
::''Priority AI'' - available more communications and slightly better interaction with the environment:
::: '''ai_type''' - <code>personalities-cruiserAI.js</code>, <code>personalities-hunterAI.js</code> or <code>personalities-privateerAI.js</code>
::: '''script''' - <code>personalities-priorityai-ship-script.js</code>
::''You can also put in your own AI scripts, but then OXP will only decide when to add your personality, and you have to implement everything else yourself.''

'''Customize behavior via [[shipdata.plist#Format|script_info]] (shipdata.plist)''' 

{| class="wikitable" style="vertical-align:middle;"
|+ Plist AI
|-
! Key
! Key meaning / commentary
! Value
! Value meaning / commentary
|-
| name
| internal identifier, required
|
|
|-
| displayName
| the character's human readable name
|
|
|-
| attacked
| what to do when attacked
| "flee"
| lets the ship flee with injectors immediatly if attacked
|-
| attackProbability
| chance of finding the ship's prey (see below) with each scan
| number in range [0; 1]
|
|-
| cargoType
| special cargo carried by the ship (e.g. "missilepod")
| role
|
|-
| rowspan="3" | energyDown
| what to do in combat when energy is less than 1/2 (shield down)
| "flee"
| lets the ship flee with injectors
|-
|
| "jump"
| lets the ship jump out
|-
|
| "cloak"
| lets the ship only use its cloak if its shields depleted
|-
| rowspan="2" | energyLow
| rowspan="2" | what to do in combat when energy is less than 1/4
| "flee"
| lets the ship flee with injectors
|-
| "jump"
| lets the ship jump out
|-
| rowspan="2" | launch
| rowspan="2" | what to do after launch from the main station
| "jump"
| jump to another system
|-
| "stay"
| keep in this system
|-
| maxCargo
| the maximum number of cargopods spawned if the ship dies
| integer
|
|-
| miningProbability
| chance of finding asteroids with each scan (only if no prey found) and mining them
| rowspan="3" | number in range [0; 1]
|
|-
| fuelstationProbability
| chance of using the fuel station (if any), if spawned at witchpoint
|
|-
| sunskimProbability
| chance of going to the sun first, if spawned at witchpoint
|
|-
| rowspan="4" | prey
| rowspan="4" | who to hunt
| "traders"
| (privateers only) will only attack ships which are victims
|-
| "everybody"
| (privateers only) will attack any ship
|-
| "offenders"
| (hunters only) will attack any ship with a bounty above a certain treshold
|-
| "thargoids"
| (hunters only) will only attack Thargoids, not pirates
|-
| preyLimit
| (hunters only) bounty treshold for offenders (or fugitives) to be attacked
| integer
|
|}

{| class="wikitable" style="vertical-align:middle;"
|+Priority AI
|-
! Key
! Key meaning / commentary
! Value
! Value meaning / commentary
|-
| name
| internal identifier, required
|
|
|-
| displayName
| the character's human readable name, required
|
|
|-
| rowspan="3" | attacked
| rowspan="3" | what to do when attacked
| "flee"
| flee away from the fight
|-
| "destroy"
| destroy the attacker, even if they no longer wants to fight
|-
| "repel"
| repel the attacker
|-
| rowspan="3" | energyDown
| rowspan="3" | what to do in combat when energy is less than 1/2 (shield down)
| "flee"
| flee away from the fight
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | energyLow
| rowspan="3" | what to do in combat when energy is less than 1/4
| "flee"
| flee away from the fight (default)
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | launch
| rowspan="3" | what to do after launch from the main station
| "jump"
| jump to another system
|-
| "stay"
| keep in this system
|-
| "random"
| 50 / 50 (default)
|-
| rowspan="6" | prey
| rowspan="6" | who to hunt
| "everybody"
| (privateer only) any clean or not ship (but not police)
|-
| "loneVictim"
| (privateer only) lone pirate victims
|-
| "traders"
| (privateer only) pirate victim ships
|-
| "offenders"
| (hunter only) any offender with sufficient bounty
|-
| "thargoids"
| (hunter only) only thargoids
|-
| "nobody"
| (default) but logicale suitable only for cruisers
|-
| preyLimit
| the minimum bounty that is worth attacking prey
| positive number
| if not specified, the standard fine threshold / 2 is used
|-
| rowspan="6" | preyCombatOdds
| rowspan="6" | what combat odds are sufficient to attack, "good" is default
| "none"
| rowspan="6" | Note that the standard oolite hunters are happy with the (not) bad outcome: <br \>"if we require bounty hunters to have actual *good* odds they'll never shoot anything" <br \>(from oolite-bountyHunterAI.js)
|-
| "excelent"
|-
| "good"
|-
| "bad"
|-
| "terrible"
|-
| "any"
|-
| rowspan="3" | distressCallReaction
| rowspan="3" | what to do if you hear a distress call if combat odds good enough
| "ignore"
| (default) do distressCallInsufficientOddsReaction
|-
| "help"
| intervene on the side of the victim (this is not necessarily who sent the call)
|-
| "finishOff"
| attack the sender of the call
|-
| distressCallCombatOdds
| what combat odds are sufficient to intervene
|
| same as for preyCombatOdds
|-
| rowspan="3" | distressCallInsufficientOddsReaction
| rowspan="3" | what to do if it's too dangerous to intervene
| "ignore"
| (default) do nothing, just fly by
|-
| "leaveVicinity"
| leave vicinity of the sender of distress call
|-
| "jumpOut"
| preventively try to witchspace out
|-
| miningProbability
| chance to start mining if nothing to do more and it posible
| rowspan="3" | number in range [0; 1]
|
|-
| fuelstationProbability
| chance to to refuel at fuelstation after witchspace jump if posible and need
|
|-
| sunskimProbability
| chance to sunskim after witchspace jump if posible and need
|
|}

'''Add communication messages into [[Misc_plists#descriptions.plist|description.plist]]'''
<div style="display: flex; flex-flow: row wrap; max-width: fit-content;"> 
<div>
# Add entry of what types of messages are used, ''name'' below must be same as in '''script_info''':
::<code>"personalities-''name''-messageTypes" = "attack attacked captured chatter dead flee jump kill launch witchspace"</code>
# Add the comms themselves:
::<code>"personalities-''name''-attack" = ("Phrase to be sent when attack");</code>
::<code>"personalities-''name''-attacked" = ("Either this phrase will be sent..", "or this one when ship attacked");</code>
::<code>"personalities-''name''-chatter" = ("Also you can add...{pause: 5} some dramatic pauses!");</code>
</div>
<div style="flex-grow: 1; margin-left: 20px">
{| class="wikitable" style="vertical-align:middle; margin: auto"
|+ List of available message types
|-
! Comms key
! Full form (PriorityAI scripts)
! Notes
|-
| attack
| oolite_beginningAttack
| Commencing an attack, repetitive
|-
| flee
| oolite_startFleeing
| Ship begins fleeing combat
|-
| jump
| oolite_engageWitchspaceDriveFlee
| Ship to escape from a fight via witchspace jump
|-
| kill
| oolite_killedTarget
| Current fight target destroyed
|-
| witchspace
| oolite_engageWitchspaceDrive
| Preparing to witchspace jump
|-
| greet
| personalitiesOXP_greet
| (Only with PriorityAI) First chatter
|-
| chatter
| personalitiesOXP_chatter
| Player nearby, repetitive
|-
| launch
| personalitiesOXP_launch
| Launched from a main station
|-
| attacked
| personalitiesOXP_attacked
| Someone hits the ship, repetitive
|-
| dead
| personalitiesOXP_dead
| Killed or ejected escape pod
|-
| captured
| personalitiesOXP_captured
| Escape pod unloaded at station
|}
</div>
</div>

'''Note:''' With PriorityAI scripts you can also use any [[Oolite_Javascript_Reference:_PriorityAI_Documentation#Standard_Communications_Keys PriorityAI|standart comms key]] with or without <code>oolite_</code> prefix:
"personalities-''name''-messageTypes" = "dockingWait oolite_selectedStation"; // In messageTypes entry types must be writen same as in descriptions key!
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_dockingWait|dockingWait]]" = ("Complaints about tedious waiting for docking");
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_selectedStation|oolite_selectedStation]]" = ("Phrase about going to check local ConStore");

If you have any questions or suggestions, don't hesitate to ask them in [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or send a PM to Alnivel.
</div>
---------------

*[http://oolite.aegidian.org/bb/viewtopic.php?p=286858#p286858 Alnivel's 2022 instructions & comments]

*[http://oolite.aegidian.org/bb/viewtopic.php?p=287046#p287046 Post to Lestradae] with some suggestions for updating his character

=== How do I remove my own character? ===
# Open the shipdata.plist inside the "Config" folder.
# Look for the entry "personalities-<yourname>".
# Remove it completely '''OR''' Go to its "roles" key, and delete the roles with "personalities" and "personalities_launcher".

== Minimum Requirements ==
Personalities 0.95 was updated for Oolite 1.90. The AI's are still in .plist form, but can now be located in a specific system/galaxy.
Personalities 0.9 was written and tested on [[Oolite]] 1.73.4. It should run on Oolite 1.73 and above. Some of its features will only be available and enabled from Oolite 1.74 onwards.

== Download Location ==
[[Media:PersonalitiesOXP.zip|Personalities.oxp v 0.9.2]] (2022) 

[http://app.box.com/shared/4h1n4j1dvy Personalities.oxp v 0.9] (2009) is available for download via Box.com.

== Installation ==
Move or copy the file Personalities.oxp from the main download folder into your AddOns folder. Where this resides, depends on your OS and your personal preferences. Restart Oolite.

[[File:IconLib.png|right]]
== Tweaking ==
This oxp is customisable through [[Library OXP]] - via the '''Config for AddOns''' option on the docked F4 screen

== Version History ==
*version 0.9.2 (October, 2022)
:new AI scripts, most personalities now use them
:with new scripts [[Oolite_Javascript_Reference:_PriorityAI_Documentation#Standard_Communications_Keys|standard communications keys]] can be used (however, it makes sense to use only those that are used by AI), old comms keys still works
:fixed a bug in plistAI scripts that caused the ships themselves to never attack
:pauses can be added to comms messages: "The message will be split{pause: 12}and the second half will be sent with specified delay"
:appearance can be limited through the list of roles:
::1) "personalities personalities_privateer personalities_galaxy_any personalities_launcher_galaxy_any personalities_aodhan" -
:::pirate by name "Aodhan" that can appear in any galaxy both in space and via launch from main station
::2) "personalities personalities_cruiser personalities_galaxy_0 ppersonalities_galaxy_1 personalities_galaxy_2 personalities_jameson" -
:::trader by name "Jameson" that can appear only in Galaxy One, Two and Three and only in space
:added methods for setting callbacks at escape pod scooping and unloading
:added method to adjust spawn weight (for galaxies) in case if someone suddenly decides to use 100 ship variants with a weight of (0.01) each

*version 0.9.1 (September, 2022) by Alnivel
:requires Oolite 1.90 (probably can work even on versions 1.82+, but not tested)
:fixed several broken function calls
:changed names of internal variables and resources to avoid conflicts
:changed comms message using method, it now requires a description.plist entry to be defined in this format:
::"personalities-<personality name>-messageTypes" = "<list of space separated message types>";
:rewritten methods for the spawn of special ships, changing a probability of this spawns now easier
:added method for adding role to appear on a specified condition, such as system id, after some event ''etc''

*version 0.9 (November 5th, 2009) by Commander McLane
:functional version for testing and feedback purposes
:script may still get worked over
:requires Oolite 1.73

== Links ==
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 Personalities.oxp] (2009 - date)
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6736 Forum Denizen OXPs] This seems to be the fons et origo of this oxp (2009)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=569 How would you like to appear as a Cameo in OOLite?] (2005)

[[Category:Oolite]]
{{ambience-OXP}}

Personalities OXP

2022-11-27T21:40:52Z

Alnivel: /* Download Location */ Hid broken (I hope) download counter

Adds Oolite community personalities to your game
[[File:Lestradae.png|right|400px]]
== Overview ==
This [[OXP]] adds characters we all know and love from the [http://www.aegidian.org/bb Oolite Bulletin Boards] to the Ooniverse. Each personality has some specific behaviour and communication patterns.

== Notable Features ==
There is a 65% chance that you will meet one well-known personality when you either jump into a new system or launch from a main station. Some of them are traders or engage in asteroid mining, some of them are bounty hunters and will protect you in case a pirate attacks you—or attack you in case you are the pirate. Some will only engage Thargoids. And some greet you friendly first, but may try to make you one more step on their ELITE ladder if nobody else is looking. Their behaviour in combat varies, but expect all of them to be a little tougher than your average adversary.

A list of the personalities contained in the basic OXP can be found at the very bottom of its ReadMe, separated by enough whitespace. If you like to be surprised, don't scroll down.

== Notes on Alnivel's update version 0.91 (2022) ==
Update of the original 10 personalities to work with newer versions of Oolite. Adds more options.

== Notes on original version 0.9 (2009)==
=== DISCLAIMER ===
Personalities.oxp is a '''work in progress''', and this version 0.9 is meant as a sneak preview, to give you a feeling what it looks like. It works as it is, but the final release may be different. Please help improving it by reporting bugs and strange or unexpected behaviour in [http://aegidian.org/bb/viewtopic.php?t=6806 its thread on the Oolite Bulletin Boards]. Thanks very much!

=== How do I remove my own character? ===
1) Open the shipdata.plist inside the "Config" folder.
2) Look for the entry "personalities-<yourname>".
3a) Remove it completely.
or
3b) Go to its "roles" key, and delete the roles "personalities" and "personalities_launcher".

=== Adding yourself as a character ===

'''Note:''' Take this instruction not as a “do it all yourself”, but rather as a reference in case you want to tweak something for yourself (or, well, do everything all yourself). You can always ask for help in the [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or even just leave a request there to be added.

You can do this either by modifying this OXP or by creating a separate one, but in any case, you will need at least basic knowledge of how to work on them. It is still preferable to be separate, but still choose as you like or can! A good starting point and reference would be [[OXP_howto|OXP howto]].

<div class="mw-collapsible mw-collapsed custom-collapsible-left-toggle" data-expandtext="Expand Instruction" data-collapsetext="Collapse Instruction" style="overflow:auto;">
'''Make an entry about your ship in [[shipdata.plist|shipdata.plist]]'''
#As a base you can take a entry from the game files or OXP or, if your ship is from OXP, from its files.
#Adjust the parameters so that they correspond to the specs of your ship in the game. Pay special attention to:
#* [[shipdata.plist#max_flight_speed|max_flight_speed]],
#* [[shipdata.plist#max_flight_pitch|max_flight_pitch]],
#* [[shipdata.plist#max_flight_roll|max_flight_roll]],
#* [[shipdata.plist#thrust|thrust]],
#* [[shipdata.plist#max_energy|max_energy]],
#* [[shipdata.plist#energy_recharge_rate|energy_recharge_rate]],
#* laser types (only [[shipdata.plist#forward_weapon_type|forward]] and [[shipdata.plist#aft_weapon_type|aft]] laser available),
#* [[shipdata.plist#laser_color|laser_color]],
#* the number of [[shipdata.plist#missiles|missiles]] you carry and their [[shipdata.plist#missile_role|main type]],
#* [[shipdata.plist#frangible|frangibility]] of your ship (if applicable),
#* installed equipment extras:
#** [[shipdata.plist#has_ecm|ECM]],
#** [[shipdata.plist#has_escape_pod|Escape Capsule]],
#** [[shipdata.plist#has_fuel_injection|Fuel Injectors]],
#** [[shipdata.plist#has_scoop|Fuel Scoops]],
#** [[shipdata.plist#has_shield_booster|Shield Boosters]],
#** [[shipdata.plist#has_shield_enhancer|Shield Enhancers]],
#** an Extra Energy Unit or Naval Energy Unit (will influence the [[shipdata.plist#max_energy|max_energy]]),
#** [[shipdata.plist#heat_insulation|Heat Shields]],
#** [[shipdata.plist#has_cloaking_device|Cloaking Device]],
#** [[shipdata.plist#has_energy_bomb|Q-bomb]]

'''Make sure that models, textures and shaders used be ship will be available not only for you'''

# Copy them to the appropriate folder of OXP.
# (Optional) It would be great if you change resource names, both filenames and references inside the models (.dat) and shipdata.plist, as this will help avoid conflicts.
::Model files are just regular text files, same as shipdata.plist, so they can be opened in a any decent text editor. It might be a good idea to use search and replace - one Griff's Cobra model has more than 800 lines with the name of the texture.

'''(Optional) Add a character entry in [[characters.plist|characters.plist]]'''

If you're carrying an escape capsule with you, you should create this entry, or one day a complete stranger will escape the ship instead of you!

Example of such a entry:
<pre>
"personalities-hesperus" = {
bounty = 150;
name = "Captain Jack Hesperus";
"random_seed" = "0 0 0 0 0 0";
"short_description" = "a notorious, feline trumble dealer from Orrira";
};
</pre>

'''Give your ship a personality (shipdata.plist)'''
:*'''[[shipdata.plist#name|name]]''' - <code>shipname: charactername</code>.
:*'''[[shipdata.plist#pilot|pilot]]''' - key of entry in characters.plist, for example,<code>personalities-hesperus</code>.
:*'''[[shipdata.plist#roles|roles]]''':
::: general role: <code>personalities</code>
::: occupation: <code>personalities_cruiser</code> (trader), <code>personalities_privateer</code> (pirate) or <code>personalities_hunter</code> (bounty hunter)
::: spawn options (several or even none may be specified):
::::<code>personalities_galaxy_any</code> - can appear in space or near main station in any galaxy
::::<code>personalities_launcher_galaxy_any</code> - can apear launching from main station in any galaxy (some ships are too big for that)
::::<code>personalities_galaxy_0</code>, <code>personalities_launcher_galaxy_0</code> - similar to 'any' variant but limited only to the Galaxy '''One'''.
::::<code>personalities_yourCharacterName</code> - opional but useful for testing
::::'''Examples:'''
::::# <code>personalities personalities_privateer personalities_galaxy_any personalities_launcher_galaxy_any personalities_aodhan</code> - pirate by name "Aodhan" that can appear in any galaxy both in space and via launch from main station,
::::# <code>personalities personalities_hunter personalities_galaxy_7 personalities_launcher_galaxy_7 personalities_cwydion</code> - bounty hunter by name "Gwydion" that can appear only in Galaxy Eight both in space and via launch from main station,
::::# <code>personalities personalities_cruiser personalities_galaxy_0 ppersonalities_galaxy_1 personalities_galaxy_2 personalities_jameson</code> - trader by name "Jameson" that can appear only in Galaxy One, Two and Three and only in space

:*'''[[shipdata.plist#ai_type|ai_type]]''' and '''[[shipdata.plist#script|script]]''' - there are two options here: plist AI or priority AI
::''Plist AI'' - relatively obsolete, but more straightforward for making your own tweaks:
::: '''ai_type''' - <code>personalitiesCruiserAI.plist</code>, <code>personalitiesHunterAI.plist</code> or <code>personalitiesPrivateerAI.plist</code>
::: '''script''' - <code>personalities-ship-script.js</code>
::''Priority AI'' - available more communications and slightly better interaction with the environment:
::: '''ai_type''' - <code>personalities-cruiserAI.js</code>, <code>personalities-hunterAI.js</code> or <code>personalities-privateerAI.js</code>
::: '''script''' - <code>personalities-priorityai-ship-script.js</code>
::''You can also put in your own AI scripts, but then OXP will only decide when to add your personality, and you have to implement everything else yourself.''

'''Customize behavior via [[shipdata.plist#Format|script_info]] (shipdata.plist)''' 

{| class="wikitable" style="vertical-align:middle;"
|+ Plist AI
|-
! Key
! Key meaning / commentary
! Value
! Value meaning / commentary
|-
| name
| internal identifier, required
|
|
|-
| displayName
| the character's human readable name
|
|
|-
| attacked
| what to do when attacked
| "flee"
| lets the ship flee with injectors immediatly if attacked
|-
| attackProbability
| chance of finding the ship's prey (see below) with each scan
| number in range [0; 1]
|
|-
| cargoType
| special cargo carried by the ship (e.g. "missilepod")
| role
|
|-
| rowspan="3" | energyDown
| what to do in combat when energy is less than 1/2 (shield down)
| "flee"
| lets the ship flee with injectors
|-
|
| "jump"
| lets the ship jump out
|-
|
| "cloak"
| lets the ship only use its cloak if its shields depleted
|-
| rowspan="2" | energyLow
| rowspan="2" | what to do in combat when energy is less than 1/4
| "flee"
| lets the ship flee with injectors
|-
| "jump"
| lets the ship jump out
|-
| rowspan="2" | launch
| rowspan="2" | what to do after launch from the main station
| "jump"
| jump to another system
|-
| "stay"
| keep in this system
|-
| maxCargo
| the maximum number of cargopods spawned if the ship dies
| integer
|
|-
| miningProbability
| chance of finding asteroids with each scan (only if no prey found) and mining them
| rowspan="3" | number in range [0; 1]
|
|-
| fuelstationProbability
| chance of using the fuel station (if any), if spawned at witchpoint
|
|-
| sunskimProbability
| chance of going to the sun first, if spawned at witchpoint
|
|-
| rowspan="4" | prey
| rowspan="4" | who to hunt
| "traders"
| (privateers only) will only attack ships which are victims
|-
| "everybody"
| (privateers only) will attack any ship
|-
| "offenders"
| (hunters only) will attack any ship with a bounty above a certain treshold
|-
| "thargoids"
| (hunters only) will only attack Thargoids, not pirates
|-
| preyLimit
| (hunters only) bounty treshold for offenders (or fugitives) to be attacked
| integer
|
|}

{| class="wikitable" style="vertical-align:middle;"
|+Priority AI
|-
! Key
! Key meaning / commentary
! Value
! Value meaning / commentary
|-
| name
| internal identifier, required
|
|
|-
| displayName
| the character's human readable name, required
|
|
|-
| rowspan="3" | attacked
| rowspan="3" | what to do when attacked
| "flee"
| flee away from the fight
|-
| "destroy"
| destroy the attacker, even if they no longer wants to fight
|-
| "repel"
| repel the attacker
|-
| rowspan="3" | energyDown
| rowspan="3" | what to do in combat when energy is less than 1/2 (shield down)
| "flee"
| flee away from the fight
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | energyLow
| rowspan="3" | what to do in combat when energy is less than 1/4
| "flee"
| flee away from the fight (default)
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | launch
| rowspan="3" | what to do after launch from the main station
| "jump"
| jump to another system
|-
| "stay"
| keep in this system
|-
| "random"
| 50 / 50 (default)
|-
| rowspan="6" | prey
| rowspan="6" | who to hunt
| "everybody"
| (privateer only) any clean or not ship (but not police)
|-
| "loneVictim"
| (privateer only) lone pirate victims
|-
| "traders"
| (privateer only) pirate victim ships
|-
| "offenders"
| (hunter only) any offender with sufficient bounty
|-
| "thargoids"
| (hunter only) only thargoids
|-
| "nobody"
| (default) but logicale suitable only for cruisers
|-
| preyLimit
| the minimum bounty that is worth attacking prey
| positive number
| if not specified, the standard fine threshold / 2 is used
|-
| rowspan="6" | preyCombatOdds
| rowspan="6" | what combat odds are sufficient to attack, "good" is default
| "none"
| rowspan="6" | Note that the standard oolite hunters are happy with the (not) bad outcome: <br \>"if we require bounty hunters to have actual *good* odds they'll never shoot anything" <br \>(from oolite-bountyHunterAI.js)
|-
| "excelent"
|-
| "good"
|-
| "bad"
|-
| "terrible"
|-
| "any"
|-
| rowspan="3" | distressCallReaction
| rowspan="3" | what to do if you hear a distress call if combat odds good enough
| "ignore"
| (default) do distressCallInsufficientOddsReaction
|-
| "help"
| intervene on the side of the victim (this is not necessarily who sent the call)
|-
| "finishOff"
| attack the sender of the call
|-
| distressCallCombatOdds
| what combat odds are sufficient to intervene
|
| same as for preyCombatOdds
|-
| rowspan="3" | distressCallInsufficientOddsReaction
| rowspan="3" | what to do if it's too dangerous to intervene
| "ignore"
| (default) do nothing, just fly by
|-
| "leaveVicinity"
| leave vicinity of the sender of distress call
|-
| "jumpOut"
| preventively try to witchspace out
|-
| miningProbability
| chance to start mining if nothing to do more and it posible
| rowspan="3" | number in range [0; 1]
|
|-
| fuelstationProbability
| chance to to refuel at fuelstation after witchspace jump if posible and need
|
|-
| sunskimProbability
| chance to sunskim after witchspace jump if posible and need
|
|}

'''Add communication messages into [[Misc_plists#descriptions.plist|description.plist]]'''
# Add entry of what types of messages are used, ''name'' below must be same as in '''script_info''':
::<code>"personalities-''name''-messageTypes" = "attack attacked captured chatter dead flee jump kill launch witchspace"</code>
# Add the comms themselves:
::<code>"personalities-''name''-attack" = ("Phrase to be sent when attack");</code>
::<code>"personalities-''name''-attacked" = ("Either this phrase will be sent..", "or this one when ship attacked");</code>
::<code>"personalities-''name''-chatter" = ("Also you can add...{pause: 5} some dramatic pauses!");</code>
{| class="wikitable" style="vertical-align:middle;"
|+ List of available message types
|-
! Comms key
! Full form (PriorityAI scripts)
! Notes
|-
| attack
| oolite_beginningAttack
| Commencing an attack, repetitive
|-
| flee
| oolite_startFleeing
| Ship begins fleeing combat
|-
| jump
| oolite_engageWitchspaceDriveFlee
| Ship to escape from a fight via witchspace jump
|-
| kill
| oolite_killedTarget
| Current fight target destroyed
|-
| witchspace
| oolite_engageWitchspaceDrive
| Preparing to witchspace jump
|-
| greet
| personalitiesOXP_greet
| (Only with PriorityAI) First chatter
|-
| chatter
| personalitiesOXP_chatter
| Player nearby, repetitive
|-
| launch
| personalitiesOXP_launch
| Launched from a main station
|-
| attacked
| personalitiesOXP_attacked
| Someone hits the ship, repetitive
|-
| dead
| personalitiesOXP_dead
| Killed or ejected escape pod
|-
| captured
| personalitiesOXP_captured
| Escape pod unloaded at station
|}

'''Note:''' With PriorityAI scripts you can also use any [[Oolite_Javascript_Reference:_PriorityAI_Documentation#Standard_Communications_Keys PriorityAI|standart comms key]] with or without <code>oolite_</code> prefix:
"personalities-''name''-messageTypes" = "dockingWait oolite_selectedStation"; // In messageTypes entry types must be writen same as in descriptions key!
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_dockingWait|dockingWait]]" = ("Complaints about tedious waiting for docking");
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_selectedStation|oolite_selectedStation]]" = ("Phrase about going to check local ConStore");

If you have any questions or suggestions, don't hesitate to ask them in [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or send a PM to Alnivel.
</div>
---------------

*[http://oolite.aegidian.org/bb/viewtopic.php?p=286858#p286858 Alnivel's 2022 instructions & comments]

*[http://oolite.aegidian.org/bb/viewtopic.php?p=287046#p287046 Post to Lestradae] with some suggestions for updating his character

== Minimum Requirements ==
Personalities 0.95 was updated for Oolite 1.90. The AI's are still in .plist form, but can now be located in a specific system/galaxy.
Personalities 0.9 was written and tested on [[Oolite]] 1.73.4. It should run on Oolite 1.73 and above. Some of its features will only be available and enabled from Oolite 1.74 onwards.

== Download Location ==
[[Media:PersonalitiesOXP.zip|Personalities.oxp v 0.9.2]] (2022) 

[http://app.box.com/shared/4h1n4j1dvy Personalities.oxp v 0.9] (2009) is available for download via Box.com.

== Installation ==
Move or copy the file Personalities.oxp from the main download folder into your AddOns folder. Where this resides, depends on your OS and your personal preferences. Restart Oolite.

[[File:IconLib.png|right]]
== Tweaking ==
This oxp is customisable through [[Library OXP]] - via the '''Config for AddOns''' option on the docked F4 screen

== Version History ==
*version 0.9.2 (October, 2022)
:new AI scripts, most personalities now use them
:with new scripts [[Oolite_Javascript_Reference:_PriorityAI_Documentation#Standard_Communications_Keys|standard communications keys]] can be used (however, it makes sense to use only those that are used by AI), old comms keys still works
:fixed a bug in plistAI scripts that caused the ships themselves to never attack
:pauses can be added to comms messages: "The message will be split{pause: 12}and the second half will be sent with specified delay"
:appearance can be limited through the list of roles:
::1) "personalities personalities_privateer personalities_galaxy_any personalities_launcher_galaxy_any personalities_aodhan" -
:::pirate by name "Aodhan" that can appear in any galaxy both in space and via launch from main station
::2) "personalities personalities_cruiser personalities_galaxy_0 ppersonalities_galaxy_1 personalities_galaxy_2 personalities_jameson" -
:::trader by name "Jameson" that can appear only in Galaxy One, Two and Three and only in space
:added methods for setting callbacks at escape pod scooping and unloading
:added method to adjust spawn weight (for galaxies) in case if someone suddenly decides to use 100 ship variants with a weight of (0.01) each

*version 0.9.1 (September, 2022) by Alnivel
:requires Oolite 1.90 (probably can work even on versions 1.82+, but not tested)
:fixed several broken function calls
:changed names of internal variables and resources to avoid conflicts
:changed comms message using method, it now requires a description.plist entry to be defined in this format:
::"personalities-<personality name>-messageTypes" = "<list of space separated message types>";
:rewritten methods for the spawn of special ships, changing a probability of this spawns now easier
:added method for adding role to appear on a specified condition, such as system id, after some event ''etc''

*version 0.9 (November 5th, 2009) by Commander McLane
:functional version for testing and feedback purposes
:script may still get worked over
:requires Oolite 1.73

== Links ==
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 Personalities.oxp] (2009 - date)
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6736 Forum Denizen OXPs] This seems to be the fons et origo of this oxp (2009)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=569 How would you like to appear as a Cameo in OOLite?] (2005)

[[Category:Oolite]]
{{ambience-OXP}}

Personalities OXP

2022-11-27T17:59:25Z

Alnivel: /* Adding yourself as a character */ Slightly unified tables with available behavior options

Adds Oolite community personalities to your game
[[File:Lestradae.png|right|400px]]
== Overview ==
This [[OXP]] adds characters we all know and love from the [http://www.aegidian.org/bb Oolite Bulletin Boards] to the Ooniverse. Each personality has some specific behaviour and communication patterns.

== Notable Features ==
There is a 65% chance that you will meet one well-known personality when you either jump into a new system or launch from a main station. Some of them are traders or engage in asteroid mining, some of them are bounty hunters and will protect you in case a pirate attacks you—or attack you in case you are the pirate. Some will only engage Thargoids. And some greet you friendly first, but may try to make you one more step on their ELITE ladder if nobody else is looking. Their behaviour in combat varies, but expect all of them to be a little tougher than your average adversary.

A list of the personalities contained in the basic OXP can be found at the very bottom of its ReadMe, separated by enough whitespace. If you like to be surprised, don't scroll down.

== Notes on Alnivel's update version 0.91 (2022) ==
Update of the original 10 personalities to work with newer versions of Oolite. Adds more options.

== Notes on original version 0.9 (2009)==
=== DISCLAIMER ===
Personalities.oxp is a '''work in progress''', and this version 0.9 is meant as a sneak preview, to give you a feeling what it looks like. It works as it is, but the final release may be different. Please help improving it by reporting bugs and strange or unexpected behaviour in [http://aegidian.org/bb/viewtopic.php?t=6806 its thread on the Oolite Bulletin Boards]. Thanks very much!

=== How do I remove my own character? ===
1) Open the shipdata.plist inside the "Config" folder.
2) Look for the entry "personalities-<yourname>".
3a) Remove it completely.
or
3b) Go to its "roles" key, and delete the roles "personalities" and "personalities_launcher".

=== Adding yourself as a character ===

'''Note:''' Take this instruction not as a “do it all yourself”, but rather as a reference in case you want to tweak something for yourself (or, well, do everything all yourself). You can always ask for help in the [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or even just leave a request there to be added.

You can do this either by modifying this OXP or by creating a separate one, but in any case, you will need at least basic knowledge of how to work on them. It is still preferable to be separate, but still choose as you like or can! A good starting point and reference would be [[OXP_howto|OXP howto]].

<div class="mw-collapsible mw-collapsed custom-collapsible-left-toggle" data-expandtext="Expand Instruction" data-collapsetext="Collapse Instruction" style="overflow:auto;">
'''Make an entry about your ship in [[shipdata.plist|shipdata.plist]]'''
#As a base you can take a entry from the game files or OXP or, if your ship is from OXP, from its files.
#Adjust the parameters so that they correspond to the specs of your ship in the game. Pay special attention to:
#* [[shipdata.plist#max_flight_speed|max_flight_speed]],
#* [[shipdata.plist#max_flight_pitch|max_flight_pitch]],
#* [[shipdata.plist#max_flight_roll|max_flight_roll]],
#* [[shipdata.plist#thrust|thrust]],
#* [[shipdata.plist#max_energy|max_energy]],
#* [[shipdata.plist#energy_recharge_rate|energy_recharge_rate]],
#* laser types (only [[shipdata.plist#forward_weapon_type|forward]] and [[shipdata.plist#aft_weapon_type|aft]] laser available),
#* [[shipdata.plist#laser_color|laser_color]],
#* the number of [[shipdata.plist#missiles|missiles]] you carry and their [[shipdata.plist#missile_role|main type]],
#* [[shipdata.plist#frangible|frangibility]] of your ship (if applicable),
#* installed equipment extras:
#** [[shipdata.plist#has_ecm|ECM]],
#** [[shipdata.plist#has_escape_pod|Escape Capsule]],
#** [[shipdata.plist#has_fuel_injection|Fuel Injectors]],
#** [[shipdata.plist#has_scoop|Fuel Scoops]],
#** [[shipdata.plist#has_shield_booster|Shield Boosters]],
#** [[shipdata.plist#has_shield_enhancer|Shield Enhancers]],
#** an Extra Energy Unit or Naval Energy Unit (will influence the [[shipdata.plist#max_energy|max_energy]]),
#** [[shipdata.plist#heat_insulation|Heat Shields]],
#** [[shipdata.plist#has_cloaking_device|Cloaking Device]],
#** [[shipdata.plist#has_energy_bomb|Q-bomb]]

'''Make sure that models, textures and shaders used be ship will be available not only for you'''

# Copy them to the appropriate folder of OXP.
# (Optional) It would be great if you change resource names, both filenames and references inside the models (.dat) and shipdata.plist, as this will help avoid conflicts.
::Model files are just regular text files, same as shipdata.plist, so they can be opened in a any decent text editor. It might be a good idea to use search and replace - one Griff's Cobra model has more than 800 lines with the name of the texture.

'''(Optional) Add a character entry in [[characters.plist|characters.plist]]'''

If you're carrying an escape capsule with you, you should create this entry, or one day a complete stranger will escape the ship instead of you!

Example of such a entry:
<pre>
"personalities-hesperus" = {
bounty = 150;
name = "Captain Jack Hesperus";
"random_seed" = "0 0 0 0 0 0";
"short_description" = "a notorious, feline trumble dealer from Orrira";
};
</pre>

'''Give your ship a personality (shipdata.plist)'''
:*'''[[shipdata.plist#name|name]]''' - <code>shipname: charactername</code>.
:*'''[[shipdata.plist#pilot|pilot]]''' - key of entry in characters.plist, for example,<code>personalities-hesperus</code>.
:*'''[[shipdata.plist#roles|roles]]''':
::: general role: <code>personalities</code>
::: occupation: <code>personalities_cruiser</code> (trader), <code>personalities_privateer</code> (pirate) or <code>personalities_hunter</code> (bounty hunter)
::: spawn options (several or even none may be specified):
::::<code>personalities_galaxy_any</code> - can appear in space or near main station in any galaxy
::::<code>personalities_launcher_galaxy_any</code> - can apear launching from main station in any galaxy (some ships are too big for that)
::::<code>personalities_galaxy_0</code>, <code>personalities_launcher_galaxy_0</code> - similar to 'any' variant but limited only to the Galaxy '''One'''.
::::<code>personalities_yourCharacterName</code> - opional but useful for testing
::::'''Examples:'''
::::# <code>personalities personalities_privateer personalities_galaxy_any personalities_launcher_galaxy_any personalities_aodhan</code> - pirate by name "Aodhan" that can appear in any galaxy both in space and via launch from main station,
::::# <code>personalities personalities_hunter personalities_galaxy_7 personalities_launcher_galaxy_7 personalities_cwydion</code> - bounty hunter by name "Gwydion" that can appear only in Galaxy Eight both in space and via launch from main station,
::::# <code>personalities personalities_cruiser personalities_galaxy_0 ppersonalities_galaxy_1 personalities_galaxy_2 personalities_jameson</code> - trader by name "Jameson" that can appear only in Galaxy One, Two and Three and only in space

:*'''[[shipdata.plist#ai_type|ai_type]]''' and '''[[shipdata.plist#script|script]]''' - there are two options here: plist AI or priority AI
::''Plist AI'' - relatively obsolete, but more straightforward for making your own tweaks:
::: '''ai_type''' - <code>personalitiesCruiserAI.plist</code>, <code>personalitiesHunterAI.plist</code> or <code>personalitiesPrivateerAI.plist</code>
::: '''script''' - <code>personalities-ship-script.js</code>
::''Priority AI'' - available more communications and slightly better interaction with the environment:
::: '''ai_type''' - <code>personalities-cruiserAI.js</code>, <code>personalities-hunterAI.js</code> or <code>personalities-privateerAI.js</code>
::: '''script''' - <code>personalities-priorityai-ship-script.js</code>
::''You can also put in your own AI scripts, but then OXP will only decide when to add your personality, and you have to implement everything else yourself.''

'''Customize behavior via [[shipdata.plist#Format|script_info]] (shipdata.plist)''' 

{| class="wikitable" style="vertical-align:middle;"
|+ Plist AI
|-
! Key
! Key meaning / commentary
! Value
! Value meaning / commentary
|-
| name
| internal identifier, required
|
|
|-
| displayName
| the character's human readable name
|
|
|-
| attacked
| what to do when attacked
| "flee"
| lets the ship flee with injectors immediatly if attacked
|-
| attackProbability
| chance of finding the ship's prey (see below) with each scan
| number in range [0; 1]
|
|-
| cargoType
| special cargo carried by the ship (e.g. "missilepod")
| role
|
|-
| rowspan="3" | energyDown
| what to do in combat when energy is less than 1/2 (shield down)
| "flee"
| lets the ship flee with injectors
|-
|
| "jump"
| lets the ship jump out
|-
|
| "cloak"
| lets the ship only use its cloak if its shields depleted
|-
| rowspan="2" | energyLow
| rowspan="2" | what to do in combat when energy is less than 1/4
| "flee"
| lets the ship flee with injectors
|-
| "jump"
| lets the ship jump out
|-
| rowspan="2" | launch
| rowspan="2" | what to do after launch from the main station
| "jump"
| jump to another system
|-
| "stay"
| keep in this system
|-
| maxCargo
| the maximum number of cargopods spawned if the ship dies
| integer
|
|-
| miningProbability
| chance of finding asteroids with each scan (only if no prey found) and mining them
| rowspan="3" | number in range [0; 1]
|
|-
| fuelstationProbability
| chance of using the fuel station (if any), if spawned at witchpoint
|
|-
| sunskimProbability
| chance of going to the sun first, if spawned at witchpoint
|
|-
| rowspan="4" | prey
| rowspan="4" | who to hunt
| "traders"
| (privateers only) will only attack ships which are victims
|-
| "everybody"
| (privateers only) will attack any ship
|-
| "offenders"
| (hunters only) will attack any ship with a bounty above a certain treshold
|-
| "thargoids"
| (hunters only) will only attack Thargoids, not pirates
|-
| preyLimit
| (hunters only) bounty treshold for offenders (or fugitives) to be attacked
| integer
|
|}

{| class="wikitable" style="vertical-align:middle;"
|+Priority AI
|-
! Key
! Key meaning / commentary
! Value
! Value meaning / commentary
|-
| name
| internal identifier, required
|
|
|-
| displayName
| the character's human readable name, required
|
|
|-
| rowspan="3" | attacked
| rowspan="3" | what to do when attacked
| "flee"
| flee away from the fight
|-
| "destroy"
| destroy the attacker, even if they no longer wants to fight
|-
| "repel"
| repel the attacker
|-
| rowspan="3" | energyDown
| rowspan="3" | what to do in combat when energy is less than 1/2 (shield down)
| "flee"
| flee away from the fight
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | energyLow
| rowspan="3" | what to do in combat when energy is less than 1/4
| "flee"
| flee away from the fight (default)
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | launch
| rowspan="3" | what to do after launch from the main station
| "jump"
| jump to another system
|-
| "stay"
| keep in this system
|-
| "random"
| 50 / 50 (default)
|-
| rowspan="6" | prey
| rowspan="6" | who to hunt
| "everybody"
| (privateer only) any clean or not ship (but not police)
|-
| "loneVictim"
| (privateer only) lone pirate victims
|-
| "traders"
| (privateer only) pirate victim ships
|-
| "offenders"
| (hunter only) any offender with sufficient bounty
|-
| "thargoids"
| (hunter only) only thargoids
|-
| "nobody"
| (default) but logicale suitable only for cruisers
|-
| preyLimit
| the minimum bounty that is worth attacking prey
| positive number
| if not specified, the standard fine threshold / 2 is used
|-
| rowspan="6" | preyCombatOdds
| rowspan="6" | what combat odds are sufficient to attack, "good" is default
| "none"
| rowspan="6" | Note that the standard oolite hunters are happy with the (not) bad outcome: <br \>"if we require bounty hunters to have actual *good* odds they'll never shoot anything" <br \>(from oolite-bountyHunterAI.js)
|-
| "excelent"
|-
| "good"
|-
| "bad"
|-
| "terrible"
|-
| "any"
|-
| rowspan="3" | distressCallReaction
| rowspan="3" | what to do if you hear a distress call if combat odds good enough
| "ignore"
| (default) do distressCallInsufficientOddsReaction
|-
| "help"
| intervene on the side of the victim (this is not necessarily who sent the call)
|-
| "finishOff"
| attack the sender of the call
|-
| distressCallCombatOdds
| what combat odds are sufficient to intervene
|
| same as for preyCombatOdds
|-
| rowspan="3" | distressCallInsufficientOddsReaction
| rowspan="3" | what to do if it's too dangerous to intervene
| "ignore"
| (default) do nothing, just fly by
|-
| "leaveVicinity"
| leave vicinity of the sender of distress call
|-
| "jumpOut"
| preventively try to witchspace out
|-
| miningProbability
| chance to start mining if nothing to do more and it posible
| rowspan="3" | number in range [0; 1]
|
|-
| fuelstationProbability
| chance to to refuel at fuelstation after witchspace jump if posible and need
|
|-
| sunskimProbability
| chance to sunskim after witchspace jump if posible and need
|
|}

'''Add communication messages into [[Misc_plists#descriptions.plist|description.plist]]'''
# Add entry of what types of messages are used, ''name'' below must be same as in '''script_info''':
::<code>"personalities-''name''-messageTypes" = "attack attacked captured chatter dead flee jump kill launch witchspace"</code>
# Add the comms themselves:
::<code>"personalities-''name''-attack" = ("Phrase to be sent when attack");</code>
::<code>"personalities-''name''-attacked" = ("Either this phrase will be sent..", "or this one when ship attacked");</code>
::<code>"personalities-''name''-chatter" = ("Also you can add...{pause: 5} some dramatic pauses!");</code>
{| class="wikitable" style="vertical-align:middle;"
|+ List of available message types
|-
! Comms key
! Full form (PriorityAI scripts)
! Notes
|-
| attack
| oolite_beginningAttack
| Commencing an attack, repetitive
|-
| flee
| oolite_startFleeing
| Ship begins fleeing combat
|-
| jump
| oolite_engageWitchspaceDriveFlee
| Ship to escape from a fight via witchspace jump
|-
| kill
| oolite_killedTarget
| Current fight target destroyed
|-
| witchspace
| oolite_engageWitchspaceDrive
| Preparing to witchspace jump
|-
| greet
| personalitiesOXP_greet
| (Only with PriorityAI) First chatter
|-
| chatter
| personalitiesOXP_chatter
| Player nearby, repetitive
|-
| launch
| personalitiesOXP_launch
| Launched from a main station
|-
| attacked
| personalitiesOXP_attacked
| Someone hits the ship, repetitive
|-
| dead
| personalitiesOXP_dead
| Killed or ejected escape pod
|-
| captured
| personalitiesOXP_captured
| Escape pod unloaded at station
|}

'''Note:''' With PriorityAI scripts you can also use any [[Oolite_Javascript_Reference:_PriorityAI_Documentation#Standard_Communications_Keys PriorityAI|standart comms key]] with or without <code>oolite_</code> prefix:
"personalities-''name''-messageTypes" = "dockingWait oolite_selectedStation"; // In messageTypes entry types must be writen same as in descriptions key!
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_dockingWait|dockingWait]]" = ("Complaints about tedious waiting for docking");
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_selectedStation|oolite_selectedStation]]" = ("Phrase about going to check local ConStore");

If you have any questions or suggestions, don't hesitate to ask them in [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or send a PM to Alnivel.
</div>
---------------

*[http://oolite.aegidian.org/bb/viewtopic.php?p=286858#p286858 Alnivel's 2022 instructions & comments]

*[http://oolite.aegidian.org/bb/viewtopic.php?p=287046#p287046 Post to Lestradae] with some suggestions for updating his character

== Minimum Requirements ==
Personalities 0.95 was updated for Oolite 1.90. The AI's are still in .plist form, but can now be located in a specific system/galaxy.
Personalities 0.9 was written and tested on [[Oolite]] 1.73.4. It should run on Oolite 1.73 and above. Some of its features will only be available and enabled from Oolite 1.74 onwards.

== Download Location ==
[[Media:PersonalitiesOXP.zip|Personalities.oxp v 0.9.2]] (2022) (downloaded {{#downloads:PersonalitiesOXP.zip}} times)

[http://app.box.com/shared/4h1n4j1dvy Personalities.oxp v 0.9] (2009) is available for download via Box.com.

== Installation ==
Move or copy the file Personalities.oxp from the main download folder into your AddOns folder. Where this resides, depends on your OS and your personal preferences. Restart Oolite.

[[File:IconLib.png|right]]
== Tweaking ==
This oxp is customisable through [[Library OXP]] - via the '''Config for AddOns''' option on the docked F4 screen

== Version History ==
*version 0.9.2 (October, 2022)
:new AI scripts, most personalities now use them
:with new scripts [[Oolite_Javascript_Reference:_PriorityAI_Documentation#Standard_Communications_Keys|standard communications keys]] can be used (however, it makes sense to use only those that are used by AI), old comms keys still works
:fixed a bug in plistAI scripts that caused the ships themselves to never attack
:pauses can be added to comms messages: "The message will be split{pause: 12}and the second half will be sent with specified delay"
:appearance can be limited through the list of roles:
::1) "personalities personalities_privateer personalities_galaxy_any personalities_launcher_galaxy_any personalities_aodhan" -
:::pirate by name "Aodhan" that can appear in any galaxy both in space and via launch from main station
::2) "personalities personalities_cruiser personalities_galaxy_0 ppersonalities_galaxy_1 personalities_galaxy_2 personalities_jameson" -
:::trader by name "Jameson" that can appear only in Galaxy One, Two and Three and only in space
:added methods for setting callbacks at escape pod scooping and unloading
:added method to adjust spawn weight (for galaxies) in case if someone suddenly decides to use 100 ship variants with a weight of (0.01) each

*version 0.9.1 (September, 2022) by Alnivel
:requires Oolite 1.90 (probably can work even on versions 1.82+, but not tested)
:fixed several broken function calls
:changed names of internal variables and resources to avoid conflicts
:changed comms message using method, it now requires a description.plist entry to be defined in this format:
::"personalities-<personality name>-messageTypes" = "<list of space separated message types>";
:rewritten methods for the spawn of special ships, changing a probability of this spawns now easier
:added method for adding role to appear on a specified condition, such as system id, after some event ''etc''

*version 0.9 (November 5th, 2009) by Commander McLane
:functional version for testing and feedback purposes
:script may still get worked over
:requires Oolite 1.73

== Links ==
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 Personalities.oxp] (2009 - date)
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6736 Forum Denizen OXPs] This seems to be the fons et origo of this oxp (2009)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=569 How would you like to appear as a Cameo in OOLite?] (2005)

[[Category:Oolite]]
{{ambience-OXP}}

Personalities OXP

2022-10-23T10:05:10Z

Alnivel: /* Version History */ Added info about version 0.9.2

Adds Oolite community personalities to your game
[[File:Lestradae.png|right|400px]]
== Overview ==
This [[OXP]] adds characters we all know and love from the [http://www.aegidian.org/bb Oolite Bulletin Boards] to the Ooniverse. Each personality has some specific behaviour and communication patterns.

== Notable Features ==
There is a 65% chance that you will meet one well-known personality when you either jump into a new system or launch from a main station. Some of them are traders or engage in asteroid mining, some of them are bounty hunters and will protect you in case a pirate attacks you—or attack you in case you are the pirate. Some will only engage Thargoids. And some greet you friendly first, but may try to make you one more step on their ELITE ladder if nobody else is looking. Their behaviour in combat varies, but expect all of them to be a little tougher than your average adversary.

A list of the personalities contained in the basic OXP can be found at the very bottom of its ReadMe, separated by enough whitespace. If you like to be surprised, don't scroll down.

== Notes on Alnivel's update version 0.91 (2022) ==
Update of the original 10 personalities to work with newer versions of Oolite. Adds more options.

== Notes on original version 0.9 (2009)==
=== DISCLAIMER ===
Personalities.oxp is a '''work in progress''', and this version 0.9 is meant as a sneak preview, to give you a feeling what it looks like. It works as it is, but the final release may be different. Please help improving it by reporting bugs and strange or unexpected behaviour in [http://aegidian.org/bb/viewtopic.php?t=6806 its thread on the Oolite Bulletin Boards]. Thanks very much!

=== How do I remove my own character? ===
1) Open the shipdata.plist inside the "Config" folder.
2) Look for the entry "personalities-<yourname>".
3a) Remove it completely.
or
3b) Go to its "roles" key, and delete the roles "personalities" and "personalities_launcher".

=== Adding yourself as a character ===

'''Note:''' Take this instruction not as a “do it all yourself”, but rather as a reference in case you want to tweak something for yourself (or, well, do everything all yourself). You can always ask for help in the [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or even just leave a request there to be added.

You can do this either by modifying this OXP or by creating a separate one, but in any case, you will need at least basic knowledge of how to work on them. It is still preferable to be separate, but still choose as you like or can! A good starting point and reference would be [[OXP_howto|OXP howto]].

<div class="mw-collapsible mw-collapsed" data-expandtext="Expand Instruction" data-collapsetext="Collapse Instruction" style="overflow:auto;">

'''Make an entry about your ship in [[shipdata.plist|shipdata.plist]]'''
#As a base you can take a entry from the game files or OXP or, if your ship is from OXP, from its files.
#Adjust the parameters so that they correspond to the specs of your ship in the game. Pay special attention to:
#* [[shipdata.plist#max_flight_speed|max_flight_speed]],
#* [[shipdata.plist#max_flight_pitch|max_flight_pitch]],
#* [[shipdata.plist#max_flight_roll|max_flight_roll]],
#* [[shipdata.plist#thrust|thrust]],
#* [[shipdata.plist#max_energy|max_energy]],
#* [[shipdata.plist#energy_recharge_rate|energy_recharge_rate]],
#* laser types (only [[shipdata.plist#forward_weapon_type|forward]] and [[shipdata.plist#aft_weapon_type|aft]] laser available),
#* [[shipdata.plist#laser_color|laser_color]],
#* the number of [[shipdata.plist#missiles|missiles]] you carry and their [[shipdata.plist#missile_role|main type]],
#* [[shipdata.plist#frangible|frangibility]] of your ship (if applicable),
#* installed equipment extras:
#** [[shipdata.plist#has_ecm|ECM]],
#** [[shipdata.plist#has_escape_pod|Escape Capsule]],
#** [[shipdata.plist#has_fuel_injection|Fuel Injectors]],
#** [[shipdata.plist#has_scoop|Fuel Scoops]],
#** [[shipdata.plist#has_shield_booster|Shield Boosters]],
#** [[shipdata.plist#has_shield_enhancer|Shield Enhancers]],
#** an Extra Energy Unit or Naval Energy Unit (will influence the [[shipdata.plist#max_energy|max_energy]]),
#** [[shipdata.plist#heat_insulation|Heat Shields]],
#** [[shipdata.plist#has_cloaking_device|Cloaking Device]],
#** [[shipdata.plist#has_energy_bomb|Q-bomb]]

'''Make sure that models, textures and shaders used be ship will be available not only for you'''

# Copy them to the appropriate folder of OXP.
# (Optional) It would be great if you change resource names, both filenames and references inside the models (.dat) and shipdata.plist, as this will help avoid conflicts.
::Model files are just regular text files, same as shipdata.plist, so they can be opened in a any decent text editor. It might be a good idea to use search and replace - one Griff's Cobra model has more than 800 lines with the name of the texture.

'''(Optional) Add a character entry in [[characters.plist|characters.plist]]'''

If you're carrying an escape capsule with you, you should create this entry, or one day a complete stranger will escape the ship instead of you!

Example of such a entry:
<pre>
"personalities-hesperus" = {
bounty = 150;
name = "Captain Jack Hesperus";
"random_seed" = "0 0 0 0 0 0";
"short_description" = "a notorious, feline trumble dealer from Orrira";
};
</pre>

'''Give your ship a personality (shipdata.plist)'''
:*'''[[shipdata.plist#name|name]]''' - <code>shipname: charactername</code>.
:*'''[[shipdata.plist#pilot|pilot]]''' - key of entry in characters.plist, for example,<code>personalities-hesperus</code>.
:*'''[[shipdata.plist#roles|roles]]''':
::: general role: <code>personalities</code>
::: occupation: <code>personalities_cruiser</code> (trader), <code>personalities_privateer</code> (pirate) or <code>personalities_hunter</code> (bounty hunter)
::: spawn options (several or even none may be specified):
::::<code>personalities_galaxy_any</code> - can appear in space or near main station in any galaxy
::::<code>personalities_launcher_galaxy_any</code> - can apear launching from main station in any galaxy (some ships are too big for that)
::::<code>personalities_galaxy_0</code>, <code>personalities_launcher_galaxy_0</code> - similar to 'any' variant but limited only to the Galaxy '''One'''.
::::<code>personalities_yourCharacterName</code> - opional but useful for testing
::::'''Examples:'''
::::# <code>personalities personalities_privateer personalities_galaxy_any personalities_launcher_galaxy_any personalities_aodhan</code> - pirate by name "Aodhan" that can appear in any galaxy both in space and via launch from main station,
::::# <code>personalities personalities_hunter personalities_galaxy_7 personalities_launcher_galaxy_7 personalities_cwydion</code> - bounty hunter by name "Gwydion" that can appear only in Galaxy Eight both in space and via launch from main station,
::::# <code>personalities personalities_cruiser personalities_galaxy_0 ppersonalities_galaxy_1 personalities_galaxy_2 personalities_jameson</code> - trader by name "Jameson" that can appear only in Galaxy One, Two and Three and only in space

:*'''[[shipdata.plist#ai_type|ai_type]]''' and '''[[shipdata.plist#script|script]]''' - there are two options here: plist AI or priority AI
::''Plist AI'' - relatively obsolete, but more straightforward for making your own tweaks:
::: '''ai_type''' - <code>personalitiesCruiserAI.plist</code>, <code>personalitiesHunterAI.plist</code> or <code>personalitiesPrivateerAI.plist</code>
::: '''script''' - <code>personalities-ship-script.js</code>
::''Priority AI'' - available more communications and slightly better interaction with the environment:
::: '''ai_type''' - <code>personalities-cruiserAI.js</code>, <code>personalities-hunterAI.js</code> or <code>personalities-privateerAI.js</code>
::: '''script''' - <code>personalities-priorityai-ship-script.js</code>
::''You can also put in your own AI scripts, but then OXP will only decide when to add your personality, and you have to implement everything else yourself.''

'''Customize behavior via [[shipdata.plist#Format|script_info]] (shipdata.plist)''' 

{| class="wikitable" style="vertical-align:middle;"
|+ Plist AI
|-
! Key
! Value
! Meaning
|-
| name
|
| internal identifier for the character's chatter
|-
| displayName
|
| the character's human readable name
|-
| attacked
| "flee"
| lets the ship flee with injectors immediatly if attacked
|-
| attackProbability
| number in range [0; 1]
| chance of finding the ship's prey (see below) with each scan
|-
| cargoType
| role
| special cargo carried by the ship (e.g. "missilepod")
|-
| rowspan="3" | energyDown
| "flee"
| lets the ship flee with injectors, if its energy is down to 1/2 (= shields depleted)
|-
| "jump"
| lets the ship jump out, if its energy is down to 1/2 (= shields depleted)
|-
| "cloak"
| lets the ship only use its cloak if its energy is down to 1/2 (= shields depleted)
|-
| rowspan="2" | energyLow
| "flee"
| lets the ship flee with injectors, if its energy is down to 1/4
|-
| "jump"
| lets the ship jump out, if its energy is down to 1/4
|-
| rowspan="2" | launch
| "jump"
| lets the ship jump out of the system, after launching from the main station
|-
| "stay"
| lets the ship set course to the witchpoint, after launching from the main
|-
| maxCargo
| integer
| the maximum number of cargopods spawned if the ship dies
|-
| miningProbability
| rowspan="3" | number in range [0; 1]
| chance of finding asteroids with each scan (only if no prey found) and mining them
|-
| fuelstationProbability
| chance of using the fuel station (if any), if spawned at witchpoint
|-
| sunskimProbability
| chance of going to the sun first, if spawned at witchpoint
|-
| rowspan="4" | prey
| "traders"
| (privateers only) will only attack ships which are victims
|-
| "everybody"
| (privateers only) will attack any ship
|-
| "offenders"
| (hunters only) will attack any ship with a bounty above a certain treshold
|-
| "thargoids"
| (hunters only) will only attack Thargoids, not pirates
|-
| preyLimit
| integer
| (hunters only) bounty treshold for offenders (or fugitives) to be attacked
|}

{| class="wikitable" style="vertical-align:middle;"
|+Priority AI
|-
! Key
! Key meaning / commentary
! Value
! Value meaning / commentary
|-
| name
| internal identifier, required
|
|
|-
| displayName
| the character's human readable name, required
|
|
|-
| rowspan="3" | attacked
| rowspan="3" | what to do when attacked
| "flee"
| flee away from the fight
|-
| "destroy"
| destroy the attacker, even if he no longer wants to fight
|-
| "repel"
| repel the attacker
|-
| rowspan="3" | energyDown
| rowspan="3" | what to do in combat when energy is less than 1/2 (shield down)
| "flee"
| flee away from the fight
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | energyLow
| rowspan="3" | what to do in combat when energy is less than 1/4
| "flee"
| flee away from the fight (default)
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | launch
| rowspan="3" | what to do after launch from the main station
| "jump"
| jump to another system
|-
| "stay"
| keep in this system
|-
| "random"
| 50 / 50 (default)
|-
| rowspan="6" | prey
| rowspan="6" | who to hunt
| "everybody"
| (privateer only) any clean or not ship (but not police)
|-
| "loneVictim"
| (privateer only) lone pirate victims
|-
| "traders"
| (privateer only) pirate victim ships
|-
| "offenders"
| (hunter only) any offender with sufficient bounty
|-
| "thargoids"
| (hunter only) only thargoids
|-
| "nobody"
| (default) but logicale suitable only for cruisers
|-
| preyLimit
| the minimum bounty that is worth attacking prey
| positive number
| if not specified, the standard fine threshold / 2 is used
|-
| rowspan="6" | preyCombatOdds
| rowspan="6" | what combat odds are sufficient to attack, "good" is default
| "none"
| rowspan="6" | Note that the standard oolite hunters are happy with the (not) bad outcome: <br \>"if we require bounty hunters to have actual *good* odds they'll never shoot anything" <br \>(from oolite-bountyHunterAI.js)
|-
| "excelent"
|-
| "good"
|-
| "bad"
|-
| "terrible"
|-
| "any"
|-
| rowspan="3" | distressCallReaction
| rowspan="3" | what to do if you hear a distress call if combat odds good enough
| "ignore"
| (default) do distressCallInsufficientOddsReaction
|-
| "help"
| intervene on the side of the victim (this is not necessarily who sent the call)
|-
| "finishOff"
| attack the sender of the call
|-
| distressCallCombatOdds
| what combat odds are sufficient to intervene
|
| same as for preyCombatOdds
|-
| rowspan="3" | distressCallInsufficientOddsReaction
| rowspan="3" | what to do if it's too dangerous to intervene
| "ignore"
| (default) do nothing, just fly by
|-
| "leaveVicinity"
| leave vicinity of the sender of distress call
|-
| "jumpOut"
| preventively try to witchspace out
|-
| miningProbability
| chance to start mining if nothing to do more and it posible
| rowspan="3" | number in range [0; 1]
|
|-
| fuelstationProbability
| chance to to refuel at fuelstation after witchspace jump if posible and need
|
|-
| sunskimProbability
| chance to sunskim after witchspace jump if posible and need
|
|}

'''Add communication messages into [[Misc_plists#descriptions.plist|description.plist]]'''
# Add entry of what types of messages are used, ''name'' below must be same as in '''script_info''':
::<code>"personalities-''name''-messageTypes" = "attack attacked captured chatter dead flee jump kill launch witchspace"</code>
# Add the comms themselves:
::<code>"personalities-''name''-attack" = ("Phrase to be sent when attack");</code>
::<code>"personalities-''name''-attacked" = ("Either this phrase will be sent..", "or this one when ship attacked");</code>
::<code>"personalities-''name''-chatter" = ("Also you can add...{pause: 5} some dramatic pauses!");</code>
{| class="wikitable" style="vertical-align:middle;"
|+ List of available message types
|-
! Comms key
! Full form (PriorityAI scripts)
! Notes
|-
| attack
| oolite_beginningAttack
| Commencing an attack, repetitive
|-
| flee
| oolite_startFleeing
| Ship begins fleeing combat
|-
| jump
| oolite_engageWitchspaceDriveFlee
| Ship to escape from a fight via witchspace jump
|-
| kill
| oolite_killedTarget
| Current fight target destroyed
|-
| witchspace
| oolite_engageWitchspaceDrive
| Preparing to witchspace jump
|-
| greet
| personalitiesOXP_greet
| (Only with PriorityAI) First chatter
|-
| chatter
| personalitiesOXP_chatter
| Player nearby, repetitive
|-
| launch
| personalitiesOXP_launch
| Launched from a main station
|-
| attacked
| personalitiesOXP_attacked
| Someone hits the ship, repetitive
|-
| dead
| personalitiesOXP_dead
| Killed or ejected escape pod
|-
| captured
| personalitiesOXP_captured
| Escape pod unloaded at station
|}

'''Note:''' With PriorityAI scripts you can also use any [[Oolite_Javascript_Reference:_PriorityAI_Documentation#Standard_Communications_Keys PriorityAI|standart comms key]] with or without <code>oolite_</code> prefix:
"personalities-''name''-messageTypes" = "dockingWait oolite_selectedStation"; // In messageTypes entry types must be writen same as in descriptions key!
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_dockingWait|dockingWait]]" = ("Complaints about tedious waiting for docking");
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_selectedStation|oolite_selectedStation]]" = ("Phrase about going to check local ConStore");

If you have any questions or suggestions, don't hesitate to ask them in [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or send a PM to Alnivel.
</div>
---------------

*[http://oolite.aegidian.org/bb/viewtopic.php?p=286858#p286858 Alnivel's 2022 instructions & comments]

*[http://oolite.aegidian.org/bb/viewtopic.php?p=287046#p287046 Post to Lestradae] with some suggestions for updating his character

== Minimum Requirements ==
Personalities 0.95 was updated for Oolite 1.90. The AI's are still in .plist form, but can now be located in a specific system/galaxy.
Personalities 0.9 was written and tested on [[Oolite]] 1.73.4. It should run on Oolite 1.73 and above. Some of its features will only be available and enabled from Oolite 1.74 onwards.

== Download Location ==
[[Media:PersonalitiesOXP.zip|Personalities.oxp v 0.9.2]] (2022) (downloaded {{#downloads:PersonalitiesOXP.zip}} times)

[http://app.box.com/shared/4h1n4j1dvy Personalities.oxp v 0.9] (2009) is available for download via Box.com.

== Installation ==
Move or copy the file Personalities.oxp from the main download folder into your AddOns folder. Where this resides, depends on your OS and your personal preferences. Restart Oolite.

[[File:IconLib.png|right]]
== Tweaking ==
This oxp is customisable through [[Library OXP]] - via the '''Config for AddOns''' option on the docked F4 screen

== Version History ==
*version 0.9.2 (October, 2022)
:new AI scripts, most personalities now use them
:with new scripts [[Oolite_Javascript_Reference:_PriorityAI_Documentation#Standard_Communications_Keys|standard communications keys]] can be used (however, it makes sense to use only those that are used by AI), old comms keys still works
:fixed a bug in plistAI scripts that caused the ships themselves to never attack
:pauses can be added to comms messages: "The message will be split{pause: 12}and the second half will be sent with specified delay"
:appearance can be limited through the list of roles:
::1) "personalities personalities_privateer personalities_galaxy_any personalities_launcher_galaxy_any personalities_aodhan" -
:::pirate by name "Aodhan" that can appear in any galaxy both in space and via launch from main station
::2) "personalities personalities_cruiser personalities_galaxy_0 ppersonalities_galaxy_1 personalities_galaxy_2 personalities_jameson" -
:::trader by name "Jameson" that can appear only in Galaxy One, Two and Three and only in space
:added methods for setting callbacks at escape pod scooping and unloading
:added method to adjust spawn weight (for galaxies) in case if someone suddenly decides to use 100 ship variants with a weight of (0.01) each

*version 0.9.1 (September, 2022) by Alnivel
:requires Oolite 1.90 (probably can work even on versions 1.82+, but not tested)
:fixed several broken function calls
:changed names of internal variables and resources to avoid conflicts
:changed comms message using method, it now requires a description.plist entry to be defined in this format:
::"personalities-<personality name>-messageTypes" = "<list of space separated message types>";
:rewritten methods for the spawn of special ships, changing a probability of this spawns now easier
:added method for adding role to appear on a specified condition, such as system id, after some event ''etc''

*version 0.9 (November 5th, 2009) by Commander McLane
:functional version for testing and feedback purposes
:script may still get worked over
:requires Oolite 1.73

== Links ==
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 Personalities.oxp] (2009 - date)
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6736 Forum Denizen OXPs] This seems to be the fons et origo of this oxp (2009)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=569 How would you like to appear as a Cameo in OOLite?] (2005)

[[Category:Oolite]]
{{ambience-OXP}}

Personalities OXP

2022-10-23T10:01:57Z

Alnivel: /* Download Location */ Updated download link for new version

Adds Oolite community personalities to your game
[[File:Lestradae.png|right|400px]]
== Overview ==
This [[OXP]] adds characters we all know and love from the [http://www.aegidian.org/bb Oolite Bulletin Boards] to the Ooniverse. Each personality has some specific behaviour and communication patterns.

== Notable Features ==
There is a 65% chance that you will meet one well-known personality when you either jump into a new system or launch from a main station. Some of them are traders or engage in asteroid mining, some of them are bounty hunters and will protect you in case a pirate attacks you—or attack you in case you are the pirate. Some will only engage Thargoids. And some greet you friendly first, but may try to make you one more step on their ELITE ladder if nobody else is looking. Their behaviour in combat varies, but expect all of them to be a little tougher than your average adversary.

A list of the personalities contained in the basic OXP can be found at the very bottom of its ReadMe, separated by enough whitespace. If you like to be surprised, don't scroll down.

== Notes on Alnivel's update version 0.91 (2022) ==
Update of the original 10 personalities to work with newer versions of Oolite. Adds more options.

== Notes on original version 0.9 (2009)==
=== DISCLAIMER ===
Personalities.oxp is a '''work in progress''', and this version 0.9 is meant as a sneak preview, to give you a feeling what it looks like. It works as it is, but the final release may be different. Please help improving it by reporting bugs and strange or unexpected behaviour in [http://aegidian.org/bb/viewtopic.php?t=6806 its thread on the Oolite Bulletin Boards]. Thanks very much!

=== How do I remove my own character? ===
1) Open the shipdata.plist inside the "Config" folder.
2) Look for the entry "personalities-<yourname>".
3a) Remove it completely.
or
3b) Go to its "roles" key, and delete the roles "personalities" and "personalities_launcher".

=== Adding yourself as a character ===

'''Note:''' Take this instruction not as a “do it all yourself”, but rather as a reference in case you want to tweak something for yourself (or, well, do everything all yourself). You can always ask for help in the [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or even just leave a request there to be added.

You can do this either by modifying this OXP or by creating a separate one, but in any case, you will need at least basic knowledge of how to work on them. It is still preferable to be separate, but still choose as you like or can! A good starting point and reference would be [[OXP_howto|OXP howto]].

<div class="mw-collapsible mw-collapsed" data-expandtext="Expand Instruction" data-collapsetext="Collapse Instruction" style="overflow:auto;">

'''Make an entry about your ship in [[shipdata.plist|shipdata.plist]]'''
#As a base you can take a entry from the game files or OXP or, if your ship is from OXP, from its files.
#Adjust the parameters so that they correspond to the specs of your ship in the game. Pay special attention to:
#* [[shipdata.plist#max_flight_speed|max_flight_speed]],
#* [[shipdata.plist#max_flight_pitch|max_flight_pitch]],
#* [[shipdata.plist#max_flight_roll|max_flight_roll]],
#* [[shipdata.plist#thrust|thrust]],
#* [[shipdata.plist#max_energy|max_energy]],
#* [[shipdata.plist#energy_recharge_rate|energy_recharge_rate]],
#* laser types (only [[shipdata.plist#forward_weapon_type|forward]] and [[shipdata.plist#aft_weapon_type|aft]] laser available),
#* [[shipdata.plist#laser_color|laser_color]],
#* the number of [[shipdata.plist#missiles|missiles]] you carry and their [[shipdata.plist#missile_role|main type]],
#* [[shipdata.plist#frangible|frangibility]] of your ship (if applicable),
#* installed equipment extras:
#** [[shipdata.plist#has_ecm|ECM]],
#** [[shipdata.plist#has_escape_pod|Escape Capsule]],
#** [[shipdata.plist#has_fuel_injection|Fuel Injectors]],
#** [[shipdata.plist#has_scoop|Fuel Scoops]],
#** [[shipdata.plist#has_shield_booster|Shield Boosters]],
#** [[shipdata.plist#has_shield_enhancer|Shield Enhancers]],
#** an Extra Energy Unit or Naval Energy Unit (will influence the [[shipdata.plist#max_energy|max_energy]]),
#** [[shipdata.plist#heat_insulation|Heat Shields]],
#** [[shipdata.plist#has_cloaking_device|Cloaking Device]],
#** [[shipdata.plist#has_energy_bomb|Q-bomb]]

'''Make sure that models, textures and shaders used be ship will be available not only for you'''

# Copy them to the appropriate folder of OXP.
# (Optional) It would be great if you change resource names, both filenames and references inside the models (.dat) and shipdata.plist, as this will help avoid conflicts.
::Model files are just regular text files, same as shipdata.plist, so they can be opened in a any decent text editor. It might be a good idea to use search and replace - one Griff's Cobra model has more than 800 lines with the name of the texture.

'''(Optional) Add a character entry in [[characters.plist|characters.plist]]'''

If you're carrying an escape capsule with you, you should create this entry, or one day a complete stranger will escape the ship instead of you!

Example of such a entry:
<pre>
"personalities-hesperus" = {
bounty = 150;
name = "Captain Jack Hesperus";
"random_seed" = "0 0 0 0 0 0";
"short_description" = "a notorious, feline trumble dealer from Orrira";
};
</pre>

'''Give your ship a personality (shipdata.plist)'''
:*'''[[shipdata.plist#name|name]]''' - <code>shipname: charactername</code>.
:*'''[[shipdata.plist#pilot|pilot]]''' - key of entry in characters.plist, for example,<code>personalities-hesperus</code>.
:*'''[[shipdata.plist#roles|roles]]''':
::: general role: <code>personalities</code>
::: occupation: <code>personalities_cruiser</code> (trader), <code>personalities_privateer</code> (pirate) or <code>personalities_hunter</code> (bounty hunter)
::: spawn options (several or even none may be specified):
::::<code>personalities_galaxy_any</code> - can appear in space or near main station in any galaxy
::::<code>personalities_launcher_galaxy_any</code> - can apear launching from main station in any galaxy (some ships are too big for that)
::::<code>personalities_galaxy_0</code>, <code>personalities_launcher_galaxy_0</code> - similar to 'any' variant but limited only to the Galaxy '''One'''.
::::<code>personalities_yourCharacterName</code> - opional but useful for testing
::::'''Examples:'''
::::# <code>personalities personalities_privateer personalities_galaxy_any personalities_launcher_galaxy_any personalities_aodhan</code> - pirate by name "Aodhan" that can appear in any galaxy both in space and via launch from main station,
::::# <code>personalities personalities_hunter personalities_galaxy_7 personalities_launcher_galaxy_7 personalities_cwydion</code> - bounty hunter by name "Gwydion" that can appear only in Galaxy Eight both in space and via launch from main station,
::::# <code>personalities personalities_cruiser personalities_galaxy_0 ppersonalities_galaxy_1 personalities_galaxy_2 personalities_jameson</code> - trader by name "Jameson" that can appear only in Galaxy One, Two and Three and only in space

:*'''[[shipdata.plist#ai_type|ai_type]]''' and '''[[shipdata.plist#script|script]]''' - there are two options here: plist AI or priority AI
::''Plist AI'' - relatively obsolete, but more straightforward for making your own tweaks:
::: '''ai_type''' - <code>personalitiesCruiserAI.plist</code>, <code>personalitiesHunterAI.plist</code> or <code>personalitiesPrivateerAI.plist</code>
::: '''script''' - <code>personalities-ship-script.js</code>
::''Priority AI'' - available more communications and slightly better interaction with the environment:
::: '''ai_type''' - <code>personalities-cruiserAI.js</code>, <code>personalities-hunterAI.js</code> or <code>personalities-privateerAI.js</code>
::: '''script''' - <code>personalities-priorityai-ship-script.js</code>
::''You can also put in your own AI scripts, but then OXP will only decide when to add your personality, and you have to implement everything else yourself.''

'''Customize behavior via [[shipdata.plist#Format|script_info]] (shipdata.plist)''' 

{| class="wikitable" style="vertical-align:middle;"
|+ Plist AI
|-
! Key
! Value
! Meaning
|-
| name
|
| internal identifier for the character's chatter
|-
| displayName
|
| the character's human readable name
|-
| attacked
| "flee"
| lets the ship flee with injectors immediatly if attacked
|-
| attackProbability
| number in range [0; 1]
| chance of finding the ship's prey (see below) with each scan
|-
| cargoType
| role
| special cargo carried by the ship (e.g. "missilepod")
|-
| rowspan="3" | energyDown
| "flee"
| lets the ship flee with injectors, if its energy is down to 1/2 (= shields depleted)
|-
| "jump"
| lets the ship jump out, if its energy is down to 1/2 (= shields depleted)
|-
| "cloak"
| lets the ship only use its cloak if its energy is down to 1/2 (= shields depleted)
|-
| rowspan="2" | energyLow
| "flee"
| lets the ship flee with injectors, if its energy is down to 1/4
|-
| "jump"
| lets the ship jump out, if its energy is down to 1/4
|-
| rowspan="2" | launch
| "jump"
| lets the ship jump out of the system, after launching from the main station
|-
| "stay"
| lets the ship set course to the witchpoint, after launching from the main
|-
| maxCargo
| integer
| the maximum number of cargopods spawned if the ship dies
|-
| miningProbability
| rowspan="3" | number in range [0; 1]
| chance of finding asteroids with each scan (only if no prey found) and mining them
|-
| fuelstationProbability
| chance of using the fuel station (if any), if spawned at witchpoint
|-
| sunskimProbability
| chance of going to the sun first, if spawned at witchpoint
|-
| rowspan="4" | prey
| "traders"
| (privateers only) will only attack ships which are victims
|-
| "everybody"
| (privateers only) will attack any ship
|-
| "offenders"
| (hunters only) will attack any ship with a bounty above a certain treshold
|-
| "thargoids"
| (hunters only) will only attack Thargoids, not pirates
|-
| preyLimit
| integer
| (hunters only) bounty treshold for offenders (or fugitives) to be attacked
|}

{| class="wikitable" style="vertical-align:middle;"
|+Priority AI
|-
! Key
! Key meaning / commentary
! Value
! Value meaning / commentary
|-
| name
| internal identifier, required
|
|
|-
| displayName
| the character's human readable name, required
|
|
|-
| rowspan="3" | attacked
| rowspan="3" | what to do when attacked
| "flee"
| flee away from the fight
|-
| "destroy"
| destroy the attacker, even if he no longer wants to fight
|-
| "repel"
| repel the attacker
|-
| rowspan="3" | energyDown
| rowspan="3" | what to do in combat when energy is less than 1/2 (shield down)
| "flee"
| flee away from the fight
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | energyLow
| rowspan="3" | what to do in combat when energy is less than 1/4
| "flee"
| flee away from the fight (default)
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | launch
| rowspan="3" | what to do after launch from the main station
| "jump"
| jump to another system
|-
| "stay"
| keep in this system
|-
| "random"
| 50 / 50 (default)
|-
| rowspan="6" | prey
| rowspan="6" | who to hunt
| "everybody"
| (privateer only) any clean or not ship (but not police)
|-
| "loneVictim"
| (privateer only) lone pirate victims
|-
| "traders"
| (privateer only) pirate victim ships
|-
| "offenders"
| (hunter only) any offender with sufficient bounty
|-
| "thargoids"
| (hunter only) only thargoids
|-
| "nobody"
| (default) but logicale suitable only for cruisers
|-
| preyLimit
| the minimum bounty that is worth attacking prey
| positive number
| if not specified, the standard fine threshold / 2 is used
|-
| rowspan="6" | preyCombatOdds
| rowspan="6" | what combat odds are sufficient to attack, "good" is default
| "none"
| rowspan="6" | Note that the standard oolite hunters are happy with the (not) bad outcome: <br \>"if we require bounty hunters to have actual *good* odds they'll never shoot anything" <br \>(from oolite-bountyHunterAI.js)
|-
| "excelent"
|-
| "good"
|-
| "bad"
|-
| "terrible"
|-
| "any"
|-
| rowspan="3" | distressCallReaction
| rowspan="3" | what to do if you hear a distress call if combat odds good enough
| "ignore"
| (default) do distressCallInsufficientOddsReaction
|-
| "help"
| intervene on the side of the victim (this is not necessarily who sent the call)
|-
| "finishOff"
| attack the sender of the call
|-
| distressCallCombatOdds
| what combat odds are sufficient to intervene
|
| same as for preyCombatOdds
|-
| rowspan="3" | distressCallInsufficientOddsReaction
| rowspan="3" | what to do if it's too dangerous to intervene
| "ignore"
| (default) do nothing, just fly by
|-
| "leaveVicinity"
| leave vicinity of the sender of distress call
|-
| "jumpOut"
| preventively try to witchspace out
|-
| miningProbability
| chance to start mining if nothing to do more and it posible
| rowspan="3" | number in range [0; 1]
|
|-
| fuelstationProbability
| chance to to refuel at fuelstation after witchspace jump if posible and need
|
|-
| sunskimProbability
| chance to sunskim after witchspace jump if posible and need
|
|}

'''Add communication messages into [[Misc_plists#descriptions.plist|description.plist]]'''
# Add entry of what types of messages are used, ''name'' below must be same as in '''script_info''':
::<code>"personalities-''name''-messageTypes" = "attack attacked captured chatter dead flee jump kill launch witchspace"</code>
# Add the comms themselves:
::<code>"personalities-''name''-attack" = ("Phrase to be sent when attack");</code>
::<code>"personalities-''name''-attacked" = ("Either this phrase will be sent..", "or this one when ship attacked");</code>
::<code>"personalities-''name''-chatter" = ("Also you can add...{pause: 5} some dramatic pauses!");</code>
{| class="wikitable" style="vertical-align:middle;"
|+ List of available message types
|-
! Comms key
! Full form (PriorityAI scripts)
! Notes
|-
| attack
| oolite_beginningAttack
| Commencing an attack, repetitive
|-
| flee
| oolite_startFleeing
| Ship begins fleeing combat
|-
| jump
| oolite_engageWitchspaceDriveFlee
| Ship to escape from a fight via witchspace jump
|-
| kill
| oolite_killedTarget
| Current fight target destroyed
|-
| witchspace
| oolite_engageWitchspaceDrive
| Preparing to witchspace jump
|-
| greet
| personalitiesOXP_greet
| (Only with PriorityAI) First chatter
|-
| chatter
| personalitiesOXP_chatter
| Player nearby, repetitive
|-
| launch
| personalitiesOXP_launch
| Launched from a main station
|-
| attacked
| personalitiesOXP_attacked
| Someone hits the ship, repetitive
|-
| dead
| personalitiesOXP_dead
| Killed or ejected escape pod
|-
| captured
| personalitiesOXP_captured
| Escape pod unloaded at station
|}

'''Note:''' With PriorityAI scripts you can also use any [[Oolite_Javascript_Reference:_PriorityAI_Documentation#Standard_Communications_Keys PriorityAI|standart comms key]] with or without <code>oolite_</code> prefix:
"personalities-''name''-messageTypes" = "dockingWait oolite_selectedStation"; // In messageTypes entry types must be writen same as in descriptions key!
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_dockingWait|dockingWait]]" = ("Complaints about tedious waiting for docking");
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_selectedStation|oolite_selectedStation]]" = ("Phrase about going to check local ConStore");

If you have any questions or suggestions, don't hesitate to ask them in [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or send a PM to Alnivel.
</div>
---------------

*[http://oolite.aegidian.org/bb/viewtopic.php?p=286858#p286858 Alnivel's 2022 instructions & comments]

*[http://oolite.aegidian.org/bb/viewtopic.php?p=287046#p287046 Post to Lestradae] with some suggestions for updating his character

== Minimum Requirements ==
Personalities 0.95 was updated for Oolite 1.90. The AI's are still in .plist form, but can now be located in a specific system/galaxy.
Personalities 0.9 was written and tested on [[Oolite]] 1.73.4. It should run on Oolite 1.73 and above. Some of its features will only be available and enabled from Oolite 1.74 onwards.

== Download Location ==
[[Media:PersonalitiesOXP.zip|Personalities.oxp v 0.9.2]] (2022) (downloaded {{#downloads:PersonalitiesOXP.zip}} times)

[http://app.box.com/shared/4h1n4j1dvy Personalities.oxp v 0.9] (2009) is available for download via Box.com.

== Installation ==
Move or copy the file Personalities.oxp from the main download folder into your AddOns folder. Where this resides, depends on your OS and your personal preferences. Restart Oolite.

[[File:IconLib.png|right]]
== Tweaking ==
This oxp is customisable through [[Library OXP]] - via the '''Config for AddOns''' option on the docked F4 screen

== Version History ==
*version 0.9.1 (September, 2022) by Alnivel
:requires Oolite 1.9 (probably can work even on versions 1.82+, but not tested)
:fixed several broken function calls
:changed names of internal variables and resources to avoid conflicts
:changed comms message using method, it now requires a description.plist entry to be defined in this format:
::"personalities-<personality name>-messageTypes" = "<list of space separated message types>";
:rewritten methods for the spawn of special ships, changing a probability of this spawns now easier
:added method for adding role to appear on a specified condition, such as system id, after some event ''etc''

*version 0.9 (November 5th, 2009) by Commander McLane
:functional version for testing and feedback purposes
:script may still get worked over
:requires Oolite 1.73

== Links ==
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 Personalities.oxp] (2009 - date)
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6736 Forum Denizen OXPs] This seems to be the fons et origo of this oxp (2009)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=569 How would you like to appear as a Cameo in OOLite?] (2005)

[[Category:Oolite]]
{{ambience-OXP}}

File:PersonalitiesOXP.zip

2022-10-23T09:54:47Z

Alnivel: Personalities OXP 0.9.2

== Summary ==
Personalities OXP 0.9.2

Personalities OXP

2022-10-23T09:29:10Z

Alnivel: /* Adding yourself as a character */ Hid under the spoiler and added some notes

Adds Oolite community personalities to your game
[[File:Lestradae.png|right|400px]]
== Overview ==
This [[OXP]] adds characters we all know and love from the [http://www.aegidian.org/bb Oolite Bulletin Boards] to the Ooniverse. Each personality has some specific behaviour and communication patterns.

== Notable Features ==
There is a 65% chance that you will meet one well-known personality when you either jump into a new system or launch from a main station. Some of them are traders or engage in asteroid mining, some of them are bounty hunters and will protect you in case a pirate attacks you—or attack you in case you are the pirate. Some will only engage Thargoids. And some greet you friendly first, but may try to make you one more step on their ELITE ladder if nobody else is looking. Their behaviour in combat varies, but expect all of them to be a little tougher than your average adversary.

A list of the personalities contained in the basic OXP can be found at the very bottom of its ReadMe, separated by enough whitespace. If you like to be surprised, don't scroll down.

== Notes on Alnivel's update version 0.91 (2022) ==
Update of the original 10 personalities to work with newer versions of Oolite. Adds more options.

== Notes on original version 0.9 (2009)==
=== DISCLAIMER ===
Personalities.oxp is a '''work in progress''', and this version 0.9 is meant as a sneak preview, to give you a feeling what it looks like. It works as it is, but the final release may be different. Please help improving it by reporting bugs and strange or unexpected behaviour in [http://aegidian.org/bb/viewtopic.php?t=6806 its thread on the Oolite Bulletin Boards]. Thanks very much!

=== How do I remove my own character? ===
1) Open the shipdata.plist inside the "Config" folder.
2) Look for the entry "personalities-<yourname>".
3a) Remove it completely.
or
3b) Go to its "roles" key, and delete the roles "personalities" and "personalities_launcher".

=== Adding yourself as a character ===

'''Note:''' Take this instruction not as a “do it all yourself”, but rather as a reference in case you want to tweak something for yourself (or, well, do everything all yourself). You can always ask for help in the [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or even just leave a request there to be added.

You can do this either by modifying this OXP or by creating a separate one, but in any case, you will need at least basic knowledge of how to work on them. It is still preferable to be separate, but still choose as you like or can! A good starting point and reference would be [[OXP_howto|OXP howto]].

<div class="mw-collapsible mw-collapsed" data-expandtext="Expand Instruction" data-collapsetext="Collapse Instruction" style="overflow:auto;">

'''Make an entry about your ship in [[shipdata.plist|shipdata.plist]]'''
#As a base you can take a entry from the game files or OXP or, if your ship is from OXP, from its files.
#Adjust the parameters so that they correspond to the specs of your ship in the game. Pay special attention to:
#* [[shipdata.plist#max_flight_speed|max_flight_speed]],
#* [[shipdata.plist#max_flight_pitch|max_flight_pitch]],
#* [[shipdata.plist#max_flight_roll|max_flight_roll]],
#* [[shipdata.plist#thrust|thrust]],
#* [[shipdata.plist#max_energy|max_energy]],
#* [[shipdata.plist#energy_recharge_rate|energy_recharge_rate]],
#* laser types (only [[shipdata.plist#forward_weapon_type|forward]] and [[shipdata.plist#aft_weapon_type|aft]] laser available),
#* [[shipdata.plist#laser_color|laser_color]],
#* the number of [[shipdata.plist#missiles|missiles]] you carry and their [[shipdata.plist#missile_role|main type]],
#* [[shipdata.plist#frangible|frangibility]] of your ship (if applicable),
#* installed equipment extras:
#** [[shipdata.plist#has_ecm|ECM]],
#** [[shipdata.plist#has_escape_pod|Escape Capsule]],
#** [[shipdata.plist#has_fuel_injection|Fuel Injectors]],
#** [[shipdata.plist#has_scoop|Fuel Scoops]],
#** [[shipdata.plist#has_shield_booster|Shield Boosters]],
#** [[shipdata.plist#has_shield_enhancer|Shield Enhancers]],
#** an Extra Energy Unit or Naval Energy Unit (will influence the [[shipdata.plist#max_energy|max_energy]]),
#** [[shipdata.plist#heat_insulation|Heat Shields]],
#** [[shipdata.plist#has_cloaking_device|Cloaking Device]],
#** [[shipdata.plist#has_energy_bomb|Q-bomb]]

'''Make sure that models, textures and shaders used be ship will be available not only for you'''

# Copy them to the appropriate folder of OXP.
# (Optional) It would be great if you change resource names, both filenames and references inside the models (.dat) and shipdata.plist, as this will help avoid conflicts.
::Model files are just regular text files, same as shipdata.plist, so they can be opened in a any decent text editor. It might be a good idea to use search and replace - one Griff's Cobra model has more than 800 lines with the name of the texture.

'''(Optional) Add a character entry in [[characters.plist|characters.plist]]'''

If you're carrying an escape capsule with you, you should create this entry, or one day a complete stranger will escape the ship instead of you!

Example of such a entry:
<pre>
"personalities-hesperus" = {
bounty = 150;
name = "Captain Jack Hesperus";
"random_seed" = "0 0 0 0 0 0";
"short_description" = "a notorious, feline trumble dealer from Orrira";
};
</pre>

'''Give your ship a personality (shipdata.plist)'''
:*'''[[shipdata.plist#name|name]]''' - <code>shipname: charactername</code>.
:*'''[[shipdata.plist#pilot|pilot]]''' - key of entry in characters.plist, for example,<code>personalities-hesperus</code>.
:*'''[[shipdata.plist#roles|roles]]''':
::: general role: <code>personalities</code>
::: occupation: <code>personalities_cruiser</code> (trader), <code>personalities_privateer</code> (pirate) or <code>personalities_hunter</code> (bounty hunter)
::: spawn options (several or even none may be specified):
::::<code>personalities_galaxy_any</code> - can appear in space or near main station in any galaxy
::::<code>personalities_launcher_galaxy_any</code> - can apear launching from main station in any galaxy (some ships are too big for that)
::::<code>personalities_galaxy_0</code>, <code>personalities_launcher_galaxy_0</code> - similar to 'any' variant but limited only to the Galaxy '''One'''.
::::<code>personalities_yourCharacterName</code> - opional but useful for testing
::::'''Examples:'''
::::# <code>personalities personalities_privateer personalities_galaxy_any personalities_launcher_galaxy_any personalities_aodhan</code> - pirate by name "Aodhan" that can appear in any galaxy both in space and via launch from main station,
::::# <code>personalities personalities_hunter personalities_galaxy_7 personalities_launcher_galaxy_7 personalities_cwydion</code> - bounty hunter by name "Gwydion" that can appear only in Galaxy Eight both in space and via launch from main station,
::::# <code>personalities personalities_cruiser personalities_galaxy_0 ppersonalities_galaxy_1 personalities_galaxy_2 personalities_jameson</code> - trader by name "Jameson" that can appear only in Galaxy One, Two and Three and only in space

:*'''[[shipdata.plist#ai_type|ai_type]]''' and '''[[shipdata.plist#script|script]]''' - there are two options here: plist AI or priority AI
::''Plist AI'' - relatively obsolete, but more straightforward for making your own tweaks:
::: '''ai_type''' - <code>personalitiesCruiserAI.plist</code>, <code>personalitiesHunterAI.plist</code> or <code>personalitiesPrivateerAI.plist</code>
::: '''script''' - <code>personalities-ship-script.js</code>
::''Priority AI'' - available more communications and slightly better interaction with the environment:
::: '''ai_type''' - <code>personalities-cruiserAI.js</code>, <code>personalities-hunterAI.js</code> or <code>personalities-privateerAI.js</code>
::: '''script''' - <code>personalities-priorityai-ship-script.js</code>
::''You can also put in your own AI scripts, but then OXP will only decide when to add your personality, and you have to implement everything else yourself.''

'''Customize behavior via [[shipdata.plist#Format|script_info]] (shipdata.plist)''' 

{| class="wikitable" style="vertical-align:middle;"
|+ Plist AI
|-
! Key
! Value
! Meaning
|-
| name
|
| internal identifier for the character's chatter
|-
| displayName
|
| the character's human readable name
|-
| attacked
| "flee"
| lets the ship flee with injectors immediatly if attacked
|-
| attackProbability
| number in range [0; 1]
| chance of finding the ship's prey (see below) with each scan
|-
| cargoType
| role
| special cargo carried by the ship (e.g. "missilepod")
|-
| rowspan="3" | energyDown
| "flee"
| lets the ship flee with injectors, if its energy is down to 1/2 (= shields depleted)
|-
| "jump"
| lets the ship jump out, if its energy is down to 1/2 (= shields depleted)
|-
| "cloak"
| lets the ship only use its cloak if its energy is down to 1/2 (= shields depleted)
|-
| rowspan="2" | energyLow
| "flee"
| lets the ship flee with injectors, if its energy is down to 1/4
|-
| "jump"
| lets the ship jump out, if its energy is down to 1/4
|-
| rowspan="2" | launch
| "jump"
| lets the ship jump out of the system, after launching from the main station
|-
| "stay"
| lets the ship set course to the witchpoint, after launching from the main
|-
| maxCargo
| integer
| the maximum number of cargopods spawned if the ship dies
|-
| miningProbability
| rowspan="3" | number in range [0; 1]
| chance of finding asteroids with each scan (only if no prey found) and mining them
|-
| fuelstationProbability
| chance of using the fuel station (if any), if spawned at witchpoint
|-
| sunskimProbability
| chance of going to the sun first, if spawned at witchpoint
|-
| rowspan="4" | prey
| "traders"
| (privateers only) will only attack ships which are victims
|-
| "everybody"
| (privateers only) will attack any ship
|-
| "offenders"
| (hunters only) will attack any ship with a bounty above a certain treshold
|-
| "thargoids"
| (hunters only) will only attack Thargoids, not pirates
|-
| preyLimit
| integer
| (hunters only) bounty treshold for offenders (or fugitives) to be attacked
|}

{| class="wikitable" style="vertical-align:middle;"
|+Priority AI
|-
! Key
! Key meaning / commentary
! Value
! Value meaning / commentary
|-
| name
| internal identifier, required
|
|
|-
| displayName
| the character's human readable name, required
|
|
|-
| rowspan="3" | attacked
| rowspan="3" | what to do when attacked
| "flee"
| flee away from the fight
|-
| "destroy"
| destroy the attacker, even if he no longer wants to fight
|-
| "repel"
| repel the attacker
|-
| rowspan="3" | energyDown
| rowspan="3" | what to do in combat when energy is less than 1/2 (shield down)
| "flee"
| flee away from the fight
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | energyLow
| rowspan="3" | what to do in combat when energy is less than 1/4
| "flee"
| flee away from the fight (default)
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | launch
| rowspan="3" | what to do after launch from the main station
| "jump"
| jump to another system
|-
| "stay"
| keep in this system
|-
| "random"
| 50 / 50 (default)
|-
| rowspan="6" | prey
| rowspan="6" | who to hunt
| "everybody"
| (privateer only) any clean or not ship (but not police)
|-
| "loneVictim"
| (privateer only) lone pirate victims
|-
| "traders"
| (privateer only) pirate victim ships
|-
| "offenders"
| (hunter only) any offender with sufficient bounty
|-
| "thargoids"
| (hunter only) only thargoids
|-
| "nobody"
| (default) but logicale suitable only for cruisers
|-
| preyLimit
| the minimum bounty that is worth attacking prey
| positive number
| if not specified, the standard fine threshold / 2 is used
|-
| rowspan="6" | preyCombatOdds
| rowspan="6" | what combat odds are sufficient to attack, "good" is default
| "none"
| rowspan="6" | Note that the standard oolite hunters are happy with the (not) bad outcome: <br \>"if we require bounty hunters to have actual *good* odds they'll never shoot anything" <br \>(from oolite-bountyHunterAI.js)
|-
| "excelent"
|-
| "good"
|-
| "bad"
|-
| "terrible"
|-
| "any"
|-
| rowspan="3" | distressCallReaction
| rowspan="3" | what to do if you hear a distress call if combat odds good enough
| "ignore"
| (default) do distressCallInsufficientOddsReaction
|-
| "help"
| intervene on the side of the victim (this is not necessarily who sent the call)
|-
| "finishOff"
| attack the sender of the call
|-
| distressCallCombatOdds
| what combat odds are sufficient to intervene
|
| same as for preyCombatOdds
|-
| rowspan="3" | distressCallInsufficientOddsReaction
| rowspan="3" | what to do if it's too dangerous to intervene
| "ignore"
| (default) do nothing, just fly by
|-
| "leaveVicinity"
| leave vicinity of the sender of distress call
|-
| "jumpOut"
| preventively try to witchspace out
|-
| miningProbability
| chance to start mining if nothing to do more and it posible
| rowspan="3" | number in range [0; 1]
|
|-
| fuelstationProbability
| chance to to refuel at fuelstation after witchspace jump if posible and need
|
|-
| sunskimProbability
| chance to sunskim after witchspace jump if posible and need
|
|}

'''Add communication messages into [[Misc_plists#descriptions.plist|description.plist]]'''
# Add entry of what types of messages are used, ''name'' below must be same as in '''script_info''':
::<code>"personalities-''name''-messageTypes" = "attack attacked captured chatter dead flee jump kill launch witchspace"</code>
# Add the comms themselves:
::<code>"personalities-''name''-attack" = ("Phrase to be sent when attack");</code>
::<code>"personalities-''name''-attacked" = ("Either this phrase will be sent..", "or this one when ship attacked");</code>
::<code>"personalities-''name''-chatter" = ("Also you can add...{pause: 5} some dramatic pauses!");</code>
{| class="wikitable" style="vertical-align:middle;"
|+ List of available message types
|-
! Comms key
! Full form (PriorityAI scripts)
! Notes
|-
| attack
| oolite_beginningAttack
| Commencing an attack, repetitive
|-
| flee
| oolite_startFleeing
| Ship begins fleeing combat
|-
| jump
| oolite_engageWitchspaceDriveFlee
| Ship to escape from a fight via witchspace jump
|-
| kill
| oolite_killedTarget
| Current fight target destroyed
|-
| witchspace
| oolite_engageWitchspaceDrive
| Preparing to witchspace jump
|-
| greet
| personalitiesOXP_greet
| (Only with PriorityAI) First chatter
|-
| chatter
| personalitiesOXP_chatter
| Player nearby, repetitive
|-
| launch
| personalitiesOXP_launch
| Launched from a main station
|-
| attacked
| personalitiesOXP_attacked
| Someone hits the ship, repetitive
|-
| dead
| personalitiesOXP_dead
| Killed or ejected escape pod
|-
| captured
| personalitiesOXP_captured
| Escape pod unloaded at station
|}

'''Note:''' With PriorityAI scripts you can also use any [[Oolite_Javascript_Reference:_PriorityAI_Documentation#Standard_Communications_Keys PriorityAI|standart comms key]] with or without <code>oolite_</code> prefix:
"personalities-''name''-messageTypes" = "dockingWait oolite_selectedStation"; // In messageTypes entry types must be writen same as in descriptions key!
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_dockingWait|dockingWait]]" = ("Complaints about tedious waiting for docking");
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_selectedStation|oolite_selectedStation]]" = ("Phrase about going to check local ConStore");

If you have any questions or suggestions, don't hesitate to ask them in [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or send a PM to Alnivel.
</div>
---------------

*[http://oolite.aegidian.org/bb/viewtopic.php?p=286858#p286858 Alnivel's 2022 instructions & comments]

*[http://oolite.aegidian.org/bb/viewtopic.php?p=287046#p287046 Post to Lestradae] with some suggestions for updating his character

== Minimum Requirements ==
Personalities 0.95 was updated for Oolite 1.90. The AI's are still in .plist form, but can now be located in a specific system/galaxy.
Personalities 0.9 was written and tested on [[Oolite]] 1.73.4. It should run on Oolite 1.73 and above. Some of its features will only be available and enabled from Oolite 1.74 onwards.

== Download Location ==
[https://www.dropbox.com/s/93yfevfm182veqv/Personalities%20OXP.zip?dl=1 Personalities.oxp v 0.91] (2022)
[http://app.box.com/shared/4h1n4j1dvy Personalities.oxp v 0.9] (2009) is available for download via Box.com.

== Installation ==
Move or copy the file Personalities.oxp from the main download folder into your AddOns folder. Where this resides, depends on your OS and your personal preferences. Restart Oolite.

[[File:IconLib.png|right]]
== Tweaking ==
This oxp is customisable through [[Library OXP]] - via the '''Config for AddOns''' option on the docked F4 screen

== Version History ==
*version 0.9.1 (September, 2022) by Alnivel
:requires Oolite 1.9 (probably can work even on versions 1.82+, but not tested)
:fixed several broken function calls
:changed names of internal variables and resources to avoid conflicts
:changed comms message using method, it now requires a description.plist entry to be defined in this format:
::"personalities-<personality name>-messageTypes" = "<list of space separated message types>";
:rewritten methods for the spawn of special ships, changing a probability of this spawns now easier
:added method for adding role to appear on a specified condition, such as system id, after some event ''etc''

*version 0.9 (November 5th, 2009) by Commander McLane
:functional version for testing and feedback purposes
:script may still get worked over
:requires Oolite 1.73

== Links ==
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 Personalities.oxp] (2009 - date)
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6736 Forum Denizen OXPs] This seems to be the fons et origo of this oxp (2009)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=569 How would you like to appear as a Cameo in OOLite?] (2005)

[[Category:Oolite]]
{{ambience-OXP}}

Personalities OXP

2022-10-22T20:51:55Z

Alnivel: /* Adding yourself as a character */ Added table of message types

Adds Oolite community personalities to your game
[[File:Lestradae.png|right|400px]]
== Overview ==
This [[OXP]] adds characters we all know and love from the [http://www.aegidian.org/bb Oolite Bulletin Boards] to the Ooniverse. Each personality has some specific behaviour and communication patterns.

== Notable Features ==
There is a 65% chance that you will meet one well-known personality when you either jump into a new system or launch from a main station. Some of them are traders or engage in asteroid mining, some of them are bounty hunters and will protect you in case a pirate attacks you—or attack you in case you are the pirate. Some will only engage Thargoids. And some greet you friendly first, but may try to make you one more step on their ELITE ladder if nobody else is looking. Their behaviour in combat varies, but expect all of them to be a little tougher than your average adversary.

A list of the personalities contained in the basic OXP can be found at the very bottom of its ReadMe, separated by enough whitespace. If you like to be surprised, don't scroll down.

== Notes on Alnivel's update version 0.91 (2022) ==
Update of the original 10 personalities to work with newer versions of Oolite. Adds more options.

== Notes on original version 0.9 (2009)==
=== DISCLAIMER ===
Personalities.oxp is a '''work in progress''', and this version 0.9 is meant as a sneak preview, to give you a feeling what it looks like. It works as it is, but the final release may be different. Please help improving it by reporting bugs and strange or unexpected behaviour in [http://aegidian.org/bb/viewtopic.php?t=6806 its thread on the Oolite Bulletin Boards]. Thanks very much!

=== How do I remove my own character? ===
1) Open the shipdata.plist inside the "Config" folder.
2) Look for the entry "personalities-<yourname>".
3a) Remove it completely.
or
3b) Go to its "roles" key, and delete the roles "personalities" and "personalities_launcher".

=== Adding yourself as a character ===

'''Make an entry about your ship in [[shipdata.plist|shipdata.plist]]'''
#As a base you can take a entry from the game files or OXP or, if your ship is from OXP, from its files.
#Adjust the parameters so that they correspond to the specs of your ship in the game. Pay special attention to:
#* [[shipdata.plist#max_flight_speed|max_flight_speed]],
#* [[shipdata.plist#max_flight_pitch|max_flight_pitch]],
#* [[shipdata.plist#max_flight_roll|max_flight_roll]],
#* [[shipdata.plist#thrust|thrust]],
#* [[shipdata.plist#max_energy|max_energy]],
#* [[shipdata.plist#energy_recharge_rate|energy_recharge_rate]],
#* laser types (only [[shipdata.plist#forward_weapon_type|forward]] and [[shipdata.plist#aft_weapon_type|aft]] laser available),
#* [[shipdata.plist#laser_color|laser_color]],
#* the number of [[shipdata.plist#missiles|missiles]] you carry and their [[shipdata.plist#missile_role|main type]],
#* [[shipdata.plist#frangible|frangibility]] of your ship (if applicable),
#* installed equipment extras:
#** [[shipdata.plist#has_ecm|ECM]],
#** [[shipdata.plist#has_escape_pod|Escape Capsule]],
#** [[shipdata.plist#has_fuel_injection|Fuel Injectors]],
#** [[shipdata.plist#has_scoop|Fuel Scoops]],
#** [[shipdata.plist#has_shield_booster|Shield Boosters]],
#** [[shipdata.plist#has_shield_enhancer|Shield Enhancers]],
#** an Extra Energy Unit or Naval Energy Unit (will influence the [[shipdata.plist#max_energy|max_energy]]),
#** [[shipdata.plist#heat_insulation|Heat Shields]],
#** [[shipdata.plist#has_cloaking_device|Cloaking Device]],
#** [[shipdata.plist#has_energy_bomb|Q-bomb]]

'''Make sure that models, textures and shaders used be ship will be available not only for you'''

# Copy them to the appropriate folder of OXP.
# (Optional) It would be great if you change resource names, both filenames and references inside the models (.dat) and shipdata.plist, as this will help avoid conflicts.
::Model files are just regular text files, same as shipdata.plist, so they can be opened in a any decent text editor. It might be a good idea to use search and replace - one Griff's Cobra model has more than 800 lines with the name of the texture.

'''(Optional) Add a character entry in [[characters.plist|characters.plist]]'''

If you're carrying an escape capsule with you, you should create this entry, or one day a complete stranger will escape the ship instead of you!

Example of such a entry:
<pre>
"personalities-hesperus" = {
bounty = 150;
name = "Captain Jack Hesperus";
"random_seed" = "0 0 0 0 0 0";
"short_description" = "a notorious, feline trumble dealer from Orrira";
};
</pre>

'''Give your ship a personality (shipdata.plist)'''
:*'''[[shipdata.plist#name|name]]''' - <code>shipname: charactername</code>.
:*'''[[shipdata.plist#pilot|pilot]]''' - key of entry in characters.plist, for example,<code>personalities-hesperus</code>.
:*'''[[shipdata.plist#roles|roles]]''':
::: general role: <code>personalities</code>
::: occupation: <code>personalities_cruiser</code> (trader), <code>personalities_privateer</code> (pirate) or <code>personalities_hunter</code> (bounty hunter)
::: spawn options (several or even none may be specified):
::::<code>personalities_galaxy_any</code> - can appear in space or near main station in any galaxy
::::<code>personalities_launcher_galaxy_any</code> - can apear launching from main station in any galaxy (some ships are too big for that)
::::<code>personalities_galaxy_0</code>, <code>personalities_launcher_galaxy_0</code> - similar to 'any' variant but limited only to the Galaxy '''One'''.
::::<code>personalities_yourCharacterName</code> - opional but useful for testing
::::'''Examples:'''
::::# <code>personalities personalities_privateer personalities_galaxy_any personalities_launcher_galaxy_any personalities_aodhan</code> - pirate by name "Aodhan" that can appear in any galaxy both in space and via launch from main station,
::::# <code>personalities personalities_hunter personalities_galaxy_7 personalities_launcher_galaxy_7 personalities_cwydion</code> - bounty hunter by name "Gwydion" that can appear only in Galaxy Eight both in space and via launch from main station,
::::# <code>personalities personalities_cruiser personalities_galaxy_0 ppersonalities_galaxy_1 personalities_galaxy_2 personalities_jameson</code> - trader by name "Jameson" that can appear only in Galaxy One, Two and Three and only in space

:*'''[[shipdata.plist#ai_type|ai_type]]''' and '''[[shipdata.plist#script|script]]''' - there are two options here: plist AI or priority AI
::''Plist AI'' - relatively obsolete, but more straightforward for making your own tweaks:
::: '''ai_type''' - <code>personalitiesCruiserAI.plist</code>, <code>personalitiesHunterAI.plist</code> or <code>personalitiesPrivateerAI.plist</code>
::: '''script''' - <code>personalities-ship-script.js</code>
::''Priority AI'' - available more communications and slightly better interaction with the environment:
::: '''ai_type''' - <code>personalities-cruiserAI.js</code>, <code>personalities-hunterAI.js</code> or <code>personalities-privateerAI.js</code>
::: '''script''' - <code>personalities-priorityai-ship-script.js</code>
::''You can also put in your own AI scripts, but then OXP will only decide when to add your personality, and you have to implement everything else yourself.''

'''Customize behavior via [[shipdata.plist#Format|script_info]] (shipdata.plist)''' 

{| class="wikitable" style="vertical-align:middle;"
|+ Plist AI
|-
! Key
! Value
! Meaning
|-
| name
|
| internal identifier for the character's chatter
|-
| displayName
|
| the character's human readable name
|-
| attacked
| "flee"
| lets the ship flee with injectors immediatly if attacked
|-
| attackProbability
| number in range [0; 1]
| chance of finding the ship's prey (see below) with each scan
|-
| cargoType
| role
| special cargo carried by the ship (e.g. "missilepod")
|-
| rowspan="3" | energyDown
| "flee"
| lets the ship flee with injectors, if its energy is down to 1/2 (= shields depleted)
|-
| "jump"
| lets the ship jump out, if its energy is down to 1/2 (= shields depleted)
|-
| "cloak"
| lets the ship only use its cloak if its energy is down to 1/2 (= shields depleted)
|-
| rowspan="2" | energyLow
| "flee"
| lets the ship flee with injectors, if its energy is down to 1/4
|-
| "jump"
| lets the ship jump out, if its energy is down to 1/4
|-
| rowspan="2" | launch
| "jump"
| lets the ship jump out of the system, after launching from the main station
|-
| "stay"
| lets the ship set course to the witchpoint, after launching from the main
|-
| maxCargo
| integer
| the maximum number of cargopods spawned if the ship dies
|-
| miningProbability
| rowspan="3" | number in range [0; 1]
| chance of finding asteroids with each scan (only if no prey found) and mining them
|-
| fuelstationProbability
| chance of using the fuel station (if any), if spawned at witchpoint
|-
| sunskimProbability
| chance of going to the sun first, if spawned at witchpoint
|-
| rowspan="4" | prey
| "traders"
| (privateers only) will only attack ships which are victims
|-
| "everybody"
| (privateers only) will attack any ship
|-
| "offenders"
| (hunters only) will attack any ship with a bounty above a certain treshold
|-
| "thargoids"
| (hunters only) will only attack Thargoids, not pirates
|-
| preyLimit
| integer
| (hunters only) bounty treshold for offenders (or fugitives) to be attacked
|}

{| class="wikitable" style="vertical-align:middle;"
|+Priority AI
|-
! Key
! Key meaning / commentary
! Value
! Value meaning / commentary
|-
| name
| internal identifier, required
|
|
|-
| displayName
| the character's human readable name, required
|
|
|-
| rowspan="3" | attacked
| rowspan="3" | what to do when attacked
| "flee"
| flee away from the fight
|-
| "destroy"
| destroy the attacker, even if he no longer wants to fight
|-
| "repel"
| repel the attacker
|-
| rowspan="3" | energyDown
| rowspan="3" | what to do in combat when energy is less than 1/2 (shield down)
| "flee"
| flee away from the fight
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | energyLow
| rowspan="3" | what to do in combat when energy is less than 1/4
| "flee"
| flee away from the fight (default)
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | launch
| rowspan="3" | what to do after launch from the main station
| "jump"
| jump to another system
|-
| "stay"
| keep in this system
|-
| "random"
| 50 / 50 (default)
|-
| rowspan="6" | prey
| rowspan="6" | who to hunt
| "everybody"
| (privateer only) any clean or not ship (but not police)
|-
| "loneVictim"
| (privateer only) lone pirate victims
|-
| "traders"
| (privateer only) pirate victim ships
|-
| "offenders"
| (hunter only) any offender with sufficient bounty
|-
| "thargoids"
| (hunter only) only thargoids
|-
| "nobody"
| (default) but logicale suitable only for cruisers
|-
| preyLimit
| the minimum bounty that is worth attacking prey
| positive number
| if not specified, the standard fine threshold / 2 is used
|-
| rowspan="6" | preyCombatOdds
| rowspan="6" | what combat odds are sufficient to attack, "good" is default
| "none"
| rowspan="6" | Note that the standard oolite hunters are happy with the (not) bad outcome: <br \>"if we require bounty hunters to have actual *good* odds they'll never shoot anything" <br \>(from oolite-bountyHunterAI.js)
|-
| "excelent"
|-
| "good"
|-
| "bad"
|-
| "terrible"
|-
| "any"
|-
| rowspan="3" | distressCallReaction
| rowspan="3" | what to do if you hear a distress call if combat odds good enough
| "ignore"
| (default) do distressCallInsufficientOddsReaction
|-
| "help"
| intervene on the side of the victim (this is not necessarily who sent the call)
|-
| "finishOff"
| attack the sender of the call
|-
| distressCallCombatOdds
| what combat odds are sufficient to intervene
|
| same as for preyCombatOdds
|-
| rowspan="3" | distressCallInsufficientOddsReaction
| rowspan="3" | what to do if it's too dangerous to intervene
| "ignore"
| (default) do nothing, just fly by
|-
| "leaveVicinity"
| leave vicinity of the sender of distress call
|-
| "jumpOut"
| preventively try to witchspace out
|-
| miningProbability
| chance to start mining if nothing to do more and it posible
| rowspan="3" | number in range [0; 1]
|
|-
| fuelstationProbability
| chance to to refuel at fuelstation after witchspace jump if posible and need
|
|-
| sunskimProbability
| chance to sunskim after witchspace jump if posible and need
|
|}

'''Add communication messages into [[Misc_plists#descriptions.plist|description.plist]]'''
# Add entry of what types of messages are used, ''name'' below must be same as in '''script_info''':
::<code>"personalities-''name''-messageTypes" = "attack attacked captured chatter dead flee jump kill launch witchspace"</code>
# Add the comms themselves:
::<code>"personalities-''name''-attack" = ("Phrase to be sent when attack");</code>
::<code>"personalities-''name''-attacked" = ("Either this phrase will be sent..", "or this one when ship attacked");</code>
::<code>"personalities-''name''-chatter" = ("Also you can add...{pause: 5} some dramatic pauses!");</code>
{| class="wikitable" style="vertical-align:middle;"
|+ List of available message types
|-
! Comms key
! Full form (PriorityAI scripts)
! Notes
|-
| attack
| oolite_beginningAttack
| Commencing an attack, repetitive
|-
| flee
| oolite_startFleeing
| Ship begins fleeing combat
|-
| jump
| oolite_engageWitchspaceDriveFlee
| Ship to escape from a fight via witchspace jump
|-
| kill
| oolite_killedTarget
| Current fight target destroyed
|-
| witchspace
| oolite_engageWitchspaceDrive
| Preparing to witchspace jump
|-
| greet
| personalitiesOXP_greet
| (Only with PriorityAI) First chatter
|-
| chatter
| personalitiesOXP_chatter
| Player nearby, repetitive
|-
| launch
| personalitiesOXP_launch
| Launched from a main station
|-
| attacked
| personalitiesOXP_attacked
| Someone hits the ship, repetitive
|-
| dead
| personalitiesOXP_dead
| Killed or ejected escape pod
|-
| captured
| personalitiesOXP_captured
| Escape pod unloaded at station
|}

'''Note:''' With PriorityAI scripts you can also use any [[Oolite_Javascript_Reference:_PriorityAI_Documentation#Standard_Communications_Keys PriorityAI|standart comms key]] with or without <code>oolite_</code> prefix:
"personalities-''name''-messageTypes" = "dockingWait oolite_selectedStation"; // In messageTypes entry types must be writen same as in descriptions key!
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_dockingWait|dockingWait]]" = ("Complaints about tedious waiting for docking");
"personalities-''name''-[[Oolite_Javascript_Reference:_PriorityAI_Documentation#oolite_selectedStation|oolite_selectedStation]]" = ("Phrase about going to check local ConStore");

If you have any questions or suggestions, don't hesitate to ask them in [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or send a PM to Alnivel.

*[http://oolite.aegidian.org/bb/viewtopic.php?p=286858#p286858 Alnivel's 2022 instructions & comments]

*[http://oolite.aegidian.org/bb/viewtopic.php?p=287046#p287046 Post to Lestradae] with some suggestions for updating his character

== Minimum Requirements ==
Personalities 0.95 was updated for Oolite 1.90. The AI's are still in .plist form, but can now be located in a specific system/galaxy.
Personalities 0.9 was written and tested on [[Oolite]] 1.73.4. It should run on Oolite 1.73 and above. Some of its features will only be available and enabled from Oolite 1.74 onwards.

== Download Location ==
[https://www.dropbox.com/s/93yfevfm182veqv/Personalities%20OXP.zip?dl=1 Personalities.oxp v 0.91] (2022)
[http://app.box.com/shared/4h1n4j1dvy Personalities.oxp v 0.9] (2009) is available for download via Box.com.

== Installation ==
Move or copy the file Personalities.oxp from the main download folder into your AddOns folder. Where this resides, depends on your OS and your personal preferences. Restart Oolite.

[[File:IconLib.png|right]]
== Tweaking ==
This oxp is customisable through [[Library OXP]] - via the '''Config for AddOns''' option on the docked F4 screen

== Version History ==
*version 0.9.1 (September, 2022) by Alnivel
:requires Oolite 1.9 (probably can work even on versions 1.82+, but not tested)
:fixed several broken function calls
:changed names of internal variables and resources to avoid conflicts
:changed comms message using method, it now requires a description.plist entry to be defined in this format:
::"personalities-<personality name>-messageTypes" = "<list of space separated message types>";
:rewritten methods for the spawn of special ships, changing a probability of this spawns now easier
:added method for adding role to appear on a specified condition, such as system id, after some event ''etc''

*version 0.9 (November 5th, 2009) by Commander McLane
:functional version for testing and feedback purposes
:script may still get worked over
:requires Oolite 1.73

== Links ==
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 Personalities.oxp] (2009 - date)
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6736 Forum Denizen OXPs] This seems to be the fons et origo of this oxp (2009)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=569 How would you like to appear as a Cameo in OOLite?] (2005)

[[Category:Oolite]]
{{ambience-OXP}}

Personalities OXP

2022-10-22T18:51:34Z

Alnivel: /* Adding yourself as a character */ Added and fixed tables about script_info and couple other things

Adds Oolite community personalities to your game
[[File:Lestradae.png|right|400px]]
== Overview ==
This [[OXP]] adds characters we all know and love from the [http://www.aegidian.org/bb Oolite Bulletin Boards] to the Ooniverse. Each personality has some specific behaviour and communication patterns.

== Notable Features ==
There is a 65% chance that you will meet one well-known personality when you either jump into a new system or launch from a main station. Some of them are traders or engage in asteroid mining, some of them are bounty hunters and will protect you in case a pirate attacks you—or attack you in case you are the pirate. Some will only engage Thargoids. And some greet you friendly first, but may try to make you one more step on their ELITE ladder if nobody else is looking. Their behaviour in combat varies, but expect all of them to be a little tougher than your average adversary.

A list of the personalities contained in the basic OXP can be found at the very bottom of its ReadMe, separated by enough whitespace. If you like to be surprised, don't scroll down.

== Notes on Alnivel's update version 0.91 (2022) ==
Update of the original 10 personalities to work with newer versions of Oolite. Adds more options.

== Notes on original version 0.9 (2009)==
=== DISCLAIMER ===
Personalities.oxp is a '''work in progress''', and this version 0.9 is meant as a sneak preview, to give you a feeling what it looks like. It works as it is, but the final release may be different. Please help improving it by reporting bugs and strange or unexpected behaviour in [http://aegidian.org/bb/viewtopic.php?t=6806 its thread on the Oolite Bulletin Boards]. Thanks very much!

=== How do I remove my own character? ===
1) Open the shipdata.plist inside the "Config" folder.
2) Look for the entry "personalities-<yourname>".
3a) Remove it completely.
or
3b) Go to its "roles" key, and delete the roles "personalities" and "personalities_launcher".

=== Adding yourself as a character ===

'''Make an entry about your ship in [[shipdata.plist|shipdata.plist]]'''
#As a base you can take a entry from the game files or OXP or, if your ship is from OXP, from its files.
#Adjust the parameters so that they correspond to the specs of your ship in the game. Pay special attention to:
#* [[shipdata.plist#max_flight_speed|max_flight_speed]],
#* [[shipdata.plist#max_flight_pitch|max_flight_pitch]],
#* [[shipdata.plist#max_flight_roll|max_flight_roll]],
#* [[shipdata.plist#thrust|thrust]],
#* [[shipdata.plist#max_energy|max_energy]],
#* [[shipdata.plist#energy_recharge_rate|energy_recharge_rate]],
#* laser types (only [[shipdata.plist#forward_weapon_type|forward]] and [[shipdata.plist#aft_weapon_type|aft]] laser available),
#* [[shipdata.plist#laser_color|laser_color]],
#* the number of [[shipdata.plist#missiles|missiles]] you carry and their [[shipdata.plist#missile_role|main type]],
#* [[shipdata.plist#frangible|frangibility]] of your ship (if applicable),
#* installed equipment extras:
#** [[shipdata.plist#has_ecm|ECM]],
#** [[shipdata.plist#has_escape_pod|Escape Capsule]],
#** [[shipdata.plist#has_fuel_injection|Fuel Injectors]],
#** [[shipdata.plist#has_scoop|Fuel Scoops]],
#** [[shipdata.plist#has_shield_booster|Shield Boosters]],
#** [[shipdata.plist#has_shield_enhancer|Shield Enhancers]],
#** an Extra Energy Unit or Naval Energy Unit (will influence the [[shipdata.plist#max_energy|max_energy]]),
#** [[shipdata.plist#heat_insulation|Heat Shields]],
#** [[shipdata.plist#has_cloaking_device|Cloaking Device]],
#** [[shipdata.plist#has_energy_bomb|Q-bomb]]

'''Make sure that models, textures and shaders used be ship will be available not only for you'''

# Copy them to the appropriate folder of OXP.
# (Optional) It would be great if you change resource names, both filenames and references inside the models (.dat) and shipdata.plist, as this will help avoid conflicts.
::Model files are just regular text files, same as shipdata.plist, so they can be opened in a any decent text editor. It might be a good idea to use search and replace - one Griff's Cobra model has more than 800 lines with the name of the texture.

'''(Optional) Add a character entry in [[characters.plist|characters.plist]]'''

If you're carrying an escape capsule with you, you should create this entry, or one day a complete stranger will escape the ship instead of you!

Example of such a entry:
<pre>
"personalities-hesperus" = {
bounty = 150;
name = "Captain Jack Hesperus";
"random_seed" = "0 0 0 0 0 0";
"short_description" = "a notorious, feline trumble dealer from Orrira";
};
</pre>

'''Give your ship a personality (shipdata.plist)'''
:*'''[[shipdata.plist#name|name]]''' - <code>shipname: charactername</code>.
:*'''[[shipdata.plist#pilot|pilot]]''' - key of entry in characters.plist, for example,<code>personalities-hesperus</code>.
:*'''[[shipdata.plist#roles|roles]]''':
::: general role: <code>personalities</code>
::: occupation: <code>personalities_cruiser</code> (trader), <code>personalities_privateer</code> (pirate) or <code>personalities_hunter</code> (bounty hunter)
::: spawn options (several or even none may be specified):
::::<code>personalities_galaxy_any</code> - can appear in space or near main station in any galaxy
::::<code>personalities_launcher_galaxy_any</code> - can apear launching from main station in any galaxy (some ships are too big for that)
::::<code>personalities_galaxy_0</code>, <code>personalities_launcher_galaxy_0</code> - similar to 'any' variant but limited only to the Galaxy '''One'''.
::::<code>personalities_yourCharacterName</code> - opional but useful for testing
::::'''Examples:'''
::::# <code>personalities personalities_privateer personalities_galaxy_any personalities_launcher_galaxy_any personalities_aodhan</code> - pirate by name "Aodhan" that can appear in any galaxy both in space and via launch from main station,
::::# <code>personalities personalities_hunter personalities_galaxy_7 personalities_launcher_galaxy_7 personalities_cwydion</code> - bounty hunter by name "Gwydion" that can appear only in Galaxy Eight both in space and via launch from main station,
::::# <code>personalities personalities_cruiser personalities_galaxy_0 ppersonalities_galaxy_1 personalities_galaxy_2 personalities_jameson</code> - trader by name "Jameson" that can appear only in Galaxy One, Two and Three and only in space

:*'''[[shipdata.plist#ai_type|ai_type]]''' and '''[[shipdata.plist#script|script]]''' - there are two options here: plist AI or priority AI
::''Plist AI'' - relatively obsolete, but more straightforward for making your own tweaks:
::: '''ai_type''' - <code>personalitiesCruiserAI.plist</code>, <code>personalitiesHunterAI.plist</code> or <code>personalitiesPrivateerAI.plist</code>
::: '''script''' - <code>personalities-ship-script.js</code>
::''Priority AI'' - available more communications and slightly better interaction with the environment:
::: '''ai_type''' - <code>personalities-cruiserAI.js</code>, <code>personalities-hunterAI.js</code> or <code>personalities-privateerAI.js</code>
::: '''script''' - <code>personalities-priorityai-ship-script.js</code>
::''You can also put in your own AI scripts, but then OXP will only decide when to add your personality, and you have to implement everything else yourself.''

'''Customize behavior via [[shipdata.plist#Format|script_info]] (shipdata.plist)''' 

{| class="wikitable" style="vertical-align:middle;"
|+ Plist AI
|-
! Key
! Value
! Meaning
|-
| name
|
| internal identifier for the character's chatter
|-
| displayName
|
| the character's human readable name
|-
| attacked
| "flee"
| lets the ship flee with injectors immediatly if attacked
|-
| attackProbability
| number in range [0; 1]
| chance of finding the ship's prey (see below) with each scan
|-
| cargoType
| role
| special cargo carried by the ship (e.g. "missilepod")
|-
| rowspan="3" | energyDown
| "flee"
| lets the ship flee with injectors, if its energy is down to 1/2 (= shields depleted)
|-
| "jump"
| lets the ship jump out, if its energy is down to 1/2 (= shields depleted)
|-
| "cloak"
| lets the ship only use its cloak if its energy is down to 1/2 (= shields depleted)
|-
| rowspan="2" | energyLow
| "flee"
| lets the ship flee with injectors, if its energy is down to 1/4
|-
| "jump"
| lets the ship jump out, if its energy is down to 1/4
|-
| rowspan="2" | launch
| "jump"
| lets the ship jump out of the system, after launching from the main station
|-
| "stay"
| lets the ship set course to the witchpoint, after launching from the main
|-
| maxCargo
| integer
| the maximum number of cargopods spawned if the ship dies
|-
| miningProbability
| rowspan="3" | number in range [0; 1]
| chance of finding asteroids with each scan (only if no prey found) and mining them
|-
| fuelstationProbability
| chance of using the fuel station (if any), if spawned at witchpoint
|-
| sunskimProbability
| chance of going to the sun first, if spawned at witchpoint
|-
| rowspan="4" | prey
| "traders"
| (privateers only) will only attack ships which are victims
|-
| "everybody"
| (privateers only) will attack any ship
|-
| "offenders"
| (hunters only) will attack any ship with a bounty above a certain treshold
|-
| "thargoids"
| (hunters only) will only attack Thargoids, not pirates
|-
| preyLimit
| integer
| (hunters only) bounty treshold for offenders (or fugitives) to be attacked
|}

{| class="wikitable" style="vertical-align:middle;"
|+Priority AI
|-
! Key
! Key meaning / commentary
! Value
! Value meaning / commentary
|-
| name
| internal identifier, required
|
|
|-
| displayName
| the character's human readable name, required
|
|
|-
| rowspan="3" | attacked
| rowspan="3" | what to do when attacked
| "flee"
| flee away from the fight
|-
| "destroy"
| destroy the attacker, even if he no longer wants to fight
|-
| "repel"
| repel the attacker
|-
| rowspan="3" | energyDown
| rowspan="3" | what to do in combat when energy is less than 1/2 (shield down)
| "flee"
| flee away from the fight
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | energyLow
| rowspan="3" | what to do in combat when energy is less than 1/4
| "flee"
| flee away from the fight (default)
|-
| "jump"
| try to witchspace out from the combat
|-
| "continue"
| keep fighting (default)
|-
| rowspan="3" | launch
| rowspan="3" | what to do after launch from the main station
| "jump"
| jump to another system
|-
| "stay"
| keep in this system
|-
| "random"
| 50 / 50 (default)
|-
| rowspan="6" | prey
| rowspan="6" | who to hunt
| "everybody"
| (privateer only) any clean or not ship (but not police)
|-
| "loneVictim"
| (privateer only) lone pirate victims
|-
| "traders"
| (privateer only) pirate victim ships
|-
| "offenders"
| (hunter only) any offender with sufficient bounty
|-
| "thargoids"
| (hunter only) only thargoids
|-
| "nobody"
| (default) but logicale suitable only for cruisers
|-
| preyLimit
| the minimum bounty that is worth attacking prey
| positive number
| if not specified, the standard fine threshold / 2 is used
|-
| rowspan="6" | preyCombatOdds
| rowspan="6" | what combat odds are sufficient to attack, "good" is default
| "none"
| rowspan="6" | Note that the standard oolite hunters are happy with the (not) bad outcome: <br \>"if we require bounty hunters to have actual *good* odds they'll never shoot anything" <br \>(from oolite-bountyHunterAI.js)
|-
| "excelent"
|-
| "good"
|-
| "bad"
|-
| "terrible"
|-
| "any"
|-
| rowspan="3" | distressCallReaction
| rowspan="3" | what to do if you hear a distress call if combat odds good enough
| "ignore"
| (default) do distressCallInsufficientOddsReaction
|-
| "help"
| intervene on the side of the victim (this is not necessarily who sent the call)
|-
| "finishOff"
| attack the sender of the call
|-
| distressCallCombatOdds
| what combat odds are sufficient to intervene
|
| same as for preyCombatOdds
|-
| rowspan="3" | distressCallInsufficientOddsReaction
| rowspan="3" | what to do if it's too dangerous to intervene
| "ignore"
| (default) do nothing, just fly by
|-
| "leaveVicinity"
| leave vicinity of the sender of distress call
|-
| "jumpOut"
| preventively try to witchspace out
|-
| miningProbability
| chance to start mining if nothing to do more and it posible
| rowspan="3" | number in range [0; 1]
|
|-
| fuelstationProbability
| chance to to refuel at fuelstation after witchspace jump if posible and need
|
|-
| sunskimProbability
| chance to sunskim after witchspace jump if posible and need
|
|}

'''Add communication messages into [[Misc_plists#descriptions.plist|description.plist]]'''
# Add entry of what types of messages are used:
::<code>"personalities-''name''-messageTypes" = "attack attacked captured chatter dead flee jump kill launch witchspace"</code> - "name" here must be same as in '''script_info'''
# Add the comms themselves:
::<code>"personalities-''name''-attack" = ("Phrase to be sent when attack");</code>
::<code>"personalities-''name''-attacked" = ("Either this phrase will be sent..", "or this one when ship attacked");</code>
::<code>"personalities-''name''-chatter" = ("Also you can add...{pause: 5} some dramatic pauses!");</code>
List of avalaible comms coming soon

If you have any questions or suggestions, don't hesitate to ask them in [http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 BB thread] or send a PM to Alnivel.

*[http://oolite.aegidian.org/bb/viewtopic.php?p=286858#p286858 Alnivel's 2022 instructions & comments]

*[http://oolite.aegidian.org/bb/viewtopic.php?p=287046#p287046 Post to Lestradae] with some suggestions for updating his character

== Minimum Requirements ==
Personalities 0.95 was updated for Oolite 1.90. The AI's are still in .plist form, but can now be located in a specific system/galaxy.
Personalities 0.9 was written and tested on [[Oolite]] 1.73.4. It should run on Oolite 1.73 and above. Some of its features will only be available and enabled from Oolite 1.74 onwards.

== Download Location ==
[https://www.dropbox.com/s/93yfevfm182veqv/Personalities%20OXP.zip?dl=1 Personalities.oxp v 0.91] (2022)
[http://app.box.com/shared/4h1n4j1dvy Personalities.oxp v 0.9] (2009) is available for download via Box.com.

== Installation ==
Move or copy the file Personalities.oxp from the main download folder into your AddOns folder. Where this resides, depends on your OS and your personal preferences. Restart Oolite.

[[File:IconLib.png|right]]
== Tweaking ==
This oxp is customisable through [[Library OXP]] - via the '''Config for AddOns''' option on the docked F4 screen

== Version History ==
*version 0.9.1 (September, 2022) by Alnivel
:requires Oolite 1.9 (probably can work even on versions 1.82+, but not tested)
:fixed several broken function calls
:changed names of internal variables and resources to avoid conflicts
:changed comms message using method, it now requires a description.plist entry to be defined in this format:
::"personalities-<personality name>-messageTypes" = "<list of space separated message types>";
:rewritten methods for the spawn of special ships, changing a probability of this spawns now easier
:added method for adding role to appear on a specified condition, such as system id, after some event ''etc''

*version 0.9 (November 5th, 2009) by Commander McLane
:functional version for testing and feedback purposes
:script may still get worked over
:requires Oolite 1.73

== Links ==
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6806 Personalities.oxp] (2009 - date)
*[http://oolite.aegidian.org/bb/viewtopic.php?f=4&t=6736 Forum Denizen OXPs] This seems to be the fons et origo of this oxp (2009)
*[http://www.aegidian.org/bb/viewtopic.php?f=2&t=569 How would you like to appear as a Cameo in OOLite?] (2005)

[[Category:Oolite]]
{{ambience-OXP}}